跳到文档内容
十方十方MAAS开发者文档进入控制台 →

开发者文档 / API 接口

Wan3.0 视频生成 API

使用 Wan 模型生成视频，支持首尾帧、多模态及文件参考。

POST/v1/wan/video-generations

Bearer API Key · JSON · HTTP 202

概览

一个入口选择四种模型，支持文生视频、首尾帧和多模态参考。提交、查询、结果通知、幂等键与其他视频任务一致；任务类型为 wan_video_generation。

调用示例

cURLPythonJavaGo

Bash / macOS / Linux；Windows 可使用 Git Bash。

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_IDEMPOTENCY_KEY:?请设置本次业务请求的幂等键；重试时保持不变}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X POST "${MASS_BASE_URL%/}/v1/wan/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5
}
JSON

Python 3.10+，仅使用标准库。保存为 example.py，运行 python example.py。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

base_url = os.environ.get("MASS_BASE_URL", "https://api.vizen.cc").rstrip("/")
api_key = os.environ["MASS_API_KEY"]
path = "/v1/wan/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5
}''')
headers["Content-Type"] = "application/json"
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
        print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, error.read().decode("utf-8"))
    raise SystemExit(1)
except urllib.error.URLError as error:
    # 创建请求出现网络异常时，保留原幂等键；不要生成新键后盲目重试。
    print("请求未能确认:", error.reason)
    raise SystemExit(1)

JDK 17+，仅使用标准库。保存为 UTF-8 的 Example.java；执行 javac -encoding UTF-8 Example.java，再执行 java Example。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class Example {
    static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("请设置环境变量 " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String base = System.getenv().getOrDefault("MASS_BASE_URL", "https://api.vizen.cc");
        base = base.replaceAll("/+$", "");
        String path = "/v1/wan/video-generations";
        String body = """
            {
              "model": "wan-3.0-pro",
              "prompt": "日落海边，镜头缓缓推进",
              "resolution": "2k",
              "duration": 5
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .header("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
        // 网络异常会抛出异常；重试创建请求时保留相同幂等键和参数。
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode());
        }
    }
}

Go 1.20+，仅使用标准库。保存为 main.go，运行 go run main.go。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requireEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("请设置环境变量 " + name) }
    return value
}

func main() {
    base := os.Getenv("MASS_BASE_URL")
    if base == "" { base = "https://api.vizen.cc" }
    base = strings.TrimRight(base, "/")
    path := "/v1/wan/video-generations"
    body := `{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5
}`
    req, err := http.NewRequest("POST", base + path, strings.NewReader(body))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    req.Header.Set("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    resp, err := client.Do(req)
    // 网络异常不代表创建失败；重试时保留原幂等键和参数。
    if err != nil { panic(err) }
    defer resp.Body.Close()
    data, err := io.ReadAll(resp.Body)
    if err != nil { panic(err) }
    fmt.Println(string(data))
    if resp.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d", resp.StatusCode)) }
}

模型与素材限制

模型支持分辨率
wan-3.0480p / 720p / 1080p
wan-3.0-pro1080p / 2k / 4k
wan-3.0-turbo480p / 720p / 1080p
wan-3.0-pro-turbo1080p / 2k / 4k

resolution 指最终交付分辨率，必须在所选型号的上述范围内；账户方案可进一步缩小范围，具体以当前 Key 的可用规格为准。请求只需指定目标分辨率。

默认输出 1080p、5 秒，自动选择画面比例，生成音轨并扩写提示词。分辨率和 ratio 不区分大小写；四型号的主要字段和素材限制一致。时长可指定 2–30 秒或 -1（智能时长）。

  • 纯文本：填写 prompt。首尾帧：填写 first_frame、last_frame 中至少一个，图片支持公网 HTTPS URL、Data URI 或裸 Base64；单张最多 20MB，支持 JPEG/PNG/BMP/WebP，PNG 不应包含透明通道。
  • 多模态参考：reference_images 最多 10 张、reference_videos 最多 5 段、reference_audios 最多 5 段。视频和音频仅支持 HTTPS URL，各自合计最多 15 秒；视频与生成输出合计最多 30 秒。视频 MP4/MOV，单个最多 100MB；音频 MP3/WAV，单个最多 15MB。
  • 首尾帧与参考模式不能混用。参考文件 file 与公开网页 link 互斥，也不能与首尾帧同时提供。文件最多 100MB，PDF/Word/演示文稿等最多 50 页；网页须无需登录。
  • 仅支持取消尚未提交处理的任务，详见取消任务。

图片边长 240–8000px，视频边长 240–4096px，宽高比均不超过 8:1。提示词中按数组顺序使用 Image 1、Video 1 引用素材。平台请求体总大小最多 64MiB，多张大图请使用 URL。

请求参数

只提交需要的字段。必填、条件必填和默认值分别标明；未定义字段会返回 422。

modelstring必填

Wan3.0 视频生成模型

wan-3.0 / wan-3.0-pro / wan-3.0-turbo / wan-3.0-pro-turbo

默认值：— · 示例："wan-3.0-pro"

promptstring | null条件必填

视频提示词；无首尾帧或参考素材时必填。

默认值：null · 示例："日落海边，镜头缓缓推进"

first_framestring | null可选

首帧图片；支持公网 HTTPS URL、Data URI 或裸 Base64。不能与任何参考素材、file 或 link 同时使用。可单独指定首帧。

默认值：null

last_framestring | null可选

尾帧图片；格式与首帧相同，可单独指定尾帧或与首帧配合；不能与参考素材模式混用。

默认值：null

reference_imagesarray<string> | null可选

最多 10 张参考图片；每项支持公网 HTTPS URL、Data URI 或裸 Base64。提示词可按数组顺序用 Image 1、Image 2 引用。

最多项数 10

默认值：[]

reference_videosarray<string> | null可选

参考视频 HTTPS URL 数组，合计最多 15 秒

最多项数 5

默认值：[]

reference_audiosarray<string> | null可选

参考音频 HTTPS URL 数组，合计最多 15 秒

最多项数 5

默认值：[]

filestring | null可选

参考文件的公网 HTTPS URL，最大 100MB；PDF、Word、演示文稿等最多 50 页。与 link、首尾帧互斥；可与其他参考素材配合。

默认值：null

linkstring | null可选

无需登录即可读取的公开网页 HTTPS URL；与 file、首尾帧互斥。不要填写需要 Cookie 或授权请求头的页面。

默认值：null

resolutionstring可选

对应型号支持的输出分辨率；账户方案不能扩展型号范围

480p / 720p / 1080p / 2k / 4k

默认值：1080p · 示例："2k"

ratiostring可选

画面比例，adaptive 表示自动选择。

adaptive / 16:9 / 4:3 / 1:1 / 3:4 / 9:16

默认值：adaptive

durationinteger可选

2–30 秒或 -1 智能时长；输入与输出视频合计最多 30 秒

默认值：5 · 示例：5

audioboolean可选

生成音轨；关闭不降低费用

默认值：true

prompt_extendboolean可选

自动扩写提示词

默认值：true

seedinteger | null可选

随机种子；省略时由服务决定。

最小值 0；最大值 2147483647

默认值：null

callback_urlstring | null可选

可选的终态 Webhook 公网 HTTPS 地址，详见结果通知。

默认值：null

成功受理返回 HTTP 202 和统一任务对象，type 为 wan_video_generation。

各模式完整调用

以下示例均调用 Wan 接口。替换素材 URL 后执行；首尾帧和参考素材分别演示，不要合并为同一个请求。

首尾帧生成

cURLPythonJavaGo

Bash / macOS / Linux；Windows 可使用 Git Bash。

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_IDEMPOTENCY_KEY:?请设置本次业务请求的幂等键；重试时保持不变}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X POST "${MASS_BASE_URL%/}/v1/wan/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "first_frame": "https://your-domain.example/first.png",
  "last_frame": "https://your-domain.example/last.png"
}
JSON

Python 3.10+，仅使用标准库。保存为 example.py，运行 python example.py。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

base_url = os.environ.get("MASS_BASE_URL", "https://api.vizen.cc").rstrip("/")
api_key = os.environ["MASS_API_KEY"]
path = "/v1/wan/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "first_frame": "https://your-domain.example/first.png",
  "last_frame": "https://your-domain.example/last.png"
}''')
headers["Content-Type"] = "application/json"
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
        print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, error.read().decode("utf-8"))
    raise SystemExit(1)
except urllib.error.URLError as error:
    # 创建请求出现网络异常时，保留原幂等键；不要生成新键后盲目重试。
    print("请求未能确认:", error.reason)
    raise SystemExit(1)

JDK 17+，仅使用标准库。保存为 UTF-8 的 Example.java；执行 javac -encoding UTF-8 Example.java，再执行 java Example。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class Example {
    static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("请设置环境变量 " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String base = System.getenv().getOrDefault("MASS_BASE_URL", "https://api.vizen.cc");
        base = base.replaceAll("/+$", "");
        String path = "/v1/wan/video-generations";
        String body = """
            {
              "model": "wan-3.0-pro",
              "prompt": "日落海边，镜头缓缓推进",
              "resolution": "2k",
              "duration": 5,
              "first_frame": "https://your-domain.example/first.png",
              "last_frame": "https://your-domain.example/last.png"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .header("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
        // 网络异常会抛出异常；重试创建请求时保留相同幂等键和参数。
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode());
        }
    }
}

Go 1.20+，仅使用标准库。保存为 main.go，运行 go run main.go。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requireEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("请设置环境变量 " + name) }
    return value
}

func main() {
    base := os.Getenv("MASS_BASE_URL")
    if base == "" { base = "https://api.vizen.cc" }
    base = strings.TrimRight(base, "/")
    path := "/v1/wan/video-generations"
    body := `{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "first_frame": "https://your-domain.example/first.png",
  "last_frame": "https://your-domain.example/last.png"
}`
    req, err := http.NewRequest("POST", base + path, strings.NewReader(body))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    req.Header.Set("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    resp, err := client.Do(req)
    // 网络异常不代表创建失败；重试时保留原幂等键和参数。
    if err != nil { panic(err) }
    defer resp.Body.Close()
    data, err := io.ReadAll(resp.Body)
    if err != nil { panic(err) }
    fmt.Println(string(data))
    if resp.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d", resp.StatusCode)) }
}

多模态参考

cURLPythonJavaGo

Bash / macOS / Linux；Windows 可使用 Git Bash。

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_IDEMPOTENCY_KEY:?请设置本次业务请求的幂等键；重试时保持不变}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X POST "${MASS_BASE_URL%/}/v1/wan/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "wan-3.0-pro",
  "prompt": "参考 Image 1 的角色外观和 Video 1 的镜头运动",
  "resolution": "2k",
  "duration": 5,
  "reference_images": [
    "https://your-domain.example/character.png"
  ],
  "reference_videos": [
    "https://your-domain.example/motion.mp4"
  ],
  "reference_audios": [
    "https://your-domain.example/music.mp3"
  ]
}
JSON

Python 3.10+，仅使用标准库。保存为 example.py，运行 python example.py。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

base_url = os.environ.get("MASS_BASE_URL", "https://api.vizen.cc").rstrip("/")
api_key = os.environ["MASS_API_KEY"]
path = "/v1/wan/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "wan-3.0-pro",
  "prompt": "参考 Image 1 的角色外观和 Video 1 的镜头运动",
  "resolution": "2k",
  "duration": 5,
  "reference_images": [
    "https://your-domain.example/character.png"
  ],
  "reference_videos": [
    "https://your-domain.example/motion.mp4"
  ],
  "reference_audios": [
    "https://your-domain.example/music.mp3"
  ]
}''')
headers["Content-Type"] = "application/json"
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
        print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, error.read().decode("utf-8"))
    raise SystemExit(1)
except urllib.error.URLError as error:
    # 创建请求出现网络异常时，保留原幂等键；不要生成新键后盲目重试。
    print("请求未能确认:", error.reason)
    raise SystemExit(1)

JDK 17+，仅使用标准库。保存为 UTF-8 的 Example.java；执行 javac -encoding UTF-8 Example.java，再执行 java Example。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class Example {
    static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("请设置环境变量 " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String base = System.getenv().getOrDefault("MASS_BASE_URL", "https://api.vizen.cc");
        base = base.replaceAll("/+$", "");
        String path = "/v1/wan/video-generations";
        String body = """
            {
              "model": "wan-3.0-pro",
              "prompt": "参考 Image 1 的角色外观和 Video 1 的镜头运动",
              "resolution": "2k",
              "duration": 5,
              "reference_images": [
                "https://your-domain.example/character.png"
              ],
              "reference_videos": [
                "https://your-domain.example/motion.mp4"
              ],
              "reference_audios": [
                "https://your-domain.example/music.mp3"
              ]
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .header("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
        // 网络异常会抛出异常；重试创建请求时保留相同幂等键和参数。
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode());
        }
    }
}

Go 1.20+，仅使用标准库。保存为 main.go，运行 go run main.go。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requireEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("请设置环境变量 " + name) }
    return value
}

func main() {
    base := os.Getenv("MASS_BASE_URL")
    if base == "" { base = "https://api.vizen.cc" }
    base = strings.TrimRight(base, "/")
    path := "/v1/wan/video-generations"
    body := `{
  "model": "wan-3.0-pro",
  "prompt": "参考 Image 1 的角色外观和 Video 1 的镜头运动",
  "resolution": "2k",
  "duration": 5,
  "reference_images": [
    "https://your-domain.example/character.png"
  ],
  "reference_videos": [
    "https://your-domain.example/motion.mp4"
  ],
  "reference_audios": [
    "https://your-domain.example/music.mp3"
  ]
}`
    req, err := http.NewRequest("POST", base + path, strings.NewReader(body))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    req.Header.Set("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    resp, err := client.Do(req)
    // 网络异常不代表创建失败；重试时保留原幂等键和参数。
    if err != nil { panic(err) }
    defer resp.Body.Close()
    data, err := io.ReadAll(resp.Body)
    if err != nil { panic(err) }
    fmt.Println(string(data))
    if resp.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d", resp.StatusCode)) }
}

参考文件

cURLPythonJavaGo

Bash / macOS / Linux；Windows 可使用 Git Bash。

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_IDEMPOTENCY_KEY:?请设置本次业务请求的幂等键；重试时保持不变}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X POST "${MASS_BASE_URL%/}/v1/wan/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "file": "https://your-domain.example/storyboard.pdf"
}
JSON

Python 3.10+，仅使用标准库。保存为 example.py，运行 python example.py。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

base_url = os.environ.get("MASS_BASE_URL", "https://api.vizen.cc").rstrip("/")
api_key = os.environ["MASS_API_KEY"]
path = "/v1/wan/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "file": "https://your-domain.example/storyboard.pdf"
}''')
headers["Content-Type"] = "application/json"
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
        print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, error.read().decode("utf-8"))
    raise SystemExit(1)
except urllib.error.URLError as error:
    # 创建请求出现网络异常时，保留原幂等键；不要生成新键后盲目重试。
    print("请求未能确认:", error.reason)
    raise SystemExit(1)

JDK 17+，仅使用标准库。保存为 UTF-8 的 Example.java；执行 javac -encoding UTF-8 Example.java，再执行 java Example。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class Example {
    static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("请设置环境变量 " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String base = System.getenv().getOrDefault("MASS_BASE_URL", "https://api.vizen.cc");
        base = base.replaceAll("/+$", "");
        String path = "/v1/wan/video-generations";
        String body = """
            {
              "model": "wan-3.0-pro",
              "prompt": "日落海边，镜头缓缓推进",
              "resolution": "2k",
              "duration": 5,
              "file": "https://your-domain.example/storyboard.pdf"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .header("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
        // 网络异常会抛出异常；重试创建请求时保留相同幂等键和参数。
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode());
        }
    }
}

Go 1.20+，仅使用标准库。保存为 main.go，运行 go run main.go。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requireEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("请设置环境变量 " + name) }
    return value
}

func main() {
    base := os.Getenv("MASS_BASE_URL")
    if base == "" { base = "https://api.vizen.cc" }
    base = strings.TrimRight(base, "/")
    path := "/v1/wan/video-generations"
    body := `{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "file": "https://your-domain.example/storyboard.pdf"
}`
    req, err := http.NewRequest("POST", base + path, strings.NewReader(body))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    req.Header.Set("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    resp, err := client.Do(req)
    // 网络异常不代表创建失败；重试时保留原幂等键和参数。
    if err != nil { panic(err) }
    defer resp.Body.Close()
    data, err := io.ReadAll(resp.Body)
    if err != nil { panic(err) }
    fmt.Println(string(data))
    if resp.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d", resp.StatusCode)) }
}

参考网页

cURLPythonJavaGo

Bash / macOS / Linux；Windows 可使用 Git Bash。

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_IDEMPOTENCY_KEY:?请设置本次业务请求的幂等键；重试时保持不变}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X POST "${MASS_BASE_URL%/}/v1/wan/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "link": "https://your-domain.example/storyboard"
}
JSON

Python 3.10+，仅使用标准库。保存为 example.py，运行 python example.py。

import json
import os
import urllib.error
import urllib.parse
import urllib.request

base_url = os.environ.get("MASS_BASE_URL", "https://api.vizen.cc").rstrip("/")
api_key = os.environ["MASS_API_KEY"]
path = "/v1/wan/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "link": "https://your-domain.example/storyboard"
}''')
headers["Content-Type"] = "application/json"
body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
        print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, error.read().decode("utf-8"))
    raise SystemExit(1)
except urllib.error.URLError as error:
    # 创建请求出现网络异常时，保留原幂等键；不要生成新键后盲目重试。
    print("请求未能确认:", error.reason)
    raise SystemExit(1)

JDK 17+，仅使用标准库。保存为 UTF-8 的 Example.java；执行 javac -encoding UTF-8 Example.java，再执行 java Example。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class Example {
    static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("请设置环境变量 " + name);
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String base = System.getenv().getOrDefault("MASS_BASE_URL", "https://api.vizen.cc");
        base = base.replaceAll("/+$", "");
        String path = "/v1/wan/video-generations";
        String body = """
            {
              "model": "wan-3.0-pro",
              "prompt": "日落海边，镜头缓缓推进",
              "resolution": "2k",
              "duration": 5,
              "link": "https://your-domain.example/storyboard"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .header("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
        // 网络异常会抛出异常；重试创建请求时保留相同幂等键和参数。
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        System.out.println(response.body());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode());
        }
    }
}

Go 1.20+，仅使用标准库。保存为 main.go，运行 go run main.go。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requireEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("请设置环境变量 " + name) }
    return value
}

func main() {
    base := os.Getenv("MASS_BASE_URL")
    if base == "" { base = "https://api.vizen.cc" }
    base = strings.TrimRight(base, "/")
    path := "/v1/wan/video-generations"
    body := `{
  "model": "wan-3.0-pro",
  "prompt": "日落海边，镜头缓缓推进",
  "resolution": "2k",
  "duration": 5,
  "link": "https://your-domain.example/storyboard"
}`
    req, err := http.NewRequest("POST", base + path, strings.NewReader(body))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    req.Header.Set("Idempotency-Key", requireEnv("MASS_IDEMPOTENCY_KEY"))
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 120 * time.Second}
    resp, err := client.Do(req)
    // 网络异常不代表创建失败；重试时保留原幂等键和参数。
    if err != nil { panic(err) }
    defer resp.Body.Close()
    data, err := io.ReadAll(resp.Body)
    if err != nil { panic(err) }
    fmt.Println(string(data))
    if resp.StatusCode >= 400 { panic(fmt.Sprintf("HTTP %d", resp.StatusCode)) }
}

成功响应

HTTP 202 Accepted 返回当前任务状态，通常为 queued；幂等重放可能返回已有任务的最新状态。保存 id 后使用任务查询 API跟踪。

{
  "id": "job_example",
  "type": "wan_video_generation",
  "status": "queued",
  "model": "wan-3.0-pro",
  "resolution": "2k",
  "output": null,
  "error": null,
  "created_at": "2026-09-15T03:58:00Z",
  "updated_at": "2026-09-15T03:58:00Z",
  "completed_at": null
}
idstring

平台任务 ID

typestring

video_generation、wan_video_generation 或 video_upscale

statusstring

queued、running、cancelling、reviewing、succeeded、failed 或 cancelled

modelstring | null

生成模型；超分任务为 null

resolutionstring

请求的最终分辨率

outputobject | null

成功结果；未成功、已过期或账单待补款时为 null，费用状态见任务账单接口

errorobject | null

失败信息；未失败时为 null

created_atstring (date-time)

任务创建时间，ISO 8601 UTC

updated_atstring (date-time)

任务最近更新时间，ISO 8601 UTC

completed_atstring (date-time) | null

任务终止时间；处理中为 null

output 和 error 的嵌套字段见任务响应结构。请求错误见错误码。

搜索文档

↑ ↓ 选择 · Enter 跳转

输入关键词，搜索正文、参数和代码示例。