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

开发者文档 / 接入指南

快速开始

从创建任务到保存视频，完成第一次调用。

概览

  1. 联系管理员开通账户和需要的 API，并确认余额充足。
  2. 登录控制台，在“API 密钥”中创建并保存密钥。
  3. 从自己的服务端提交任务，保存返回的 id。
  4. 查询任务或接收结果通知，成功后及时保存视频。

先按环境变量配置设置地址、密钥及幂等键，选择需要的语言运行；模型、分辨率以当前账户已开通能力为准。下方使用 Seedance；Wan 和超分只需替换创建接口与请求参数，查询和下载流程相同，但 Wan 与超分的结果字段为 output.video_url。

1. 提交任务

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/video-generations" \
  -H "Authorization: Bearer $MASS_API_KEY" \
  -H "Idempotency-Key: $MASS_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "清晨的海边，镜头缓慢推进，海浪轻拍沙滩"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9"
}
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/video-generations"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MASS_IDEMPOTENCY_KEY"]
payload = json.loads(r'''{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "清晨的海边，镜头缓慢推进，海浪轻拍沙滩"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9"
}''')
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/video-generations";
        String body = """
            {
              "model": "doubao-seedance-2-5-260628",
              "content": [
                {
                  "type": "text",
                  "text": "清晨的海边，镜头缓慢推进，海浪轻拍沙滩"
                }
              ],
              "resolution": "720p",
              "duration": 5,
              "ratio": "16:9"
            }
            """;
        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/video-generations"
    body := `{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {
      "type": "text",
      "text": "清晨的海边，镜头缓慢推进，海浪轻拍沙滩"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9"
}`
    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，响应示例如下。保存 id；202 表示请求已受理，不表示视频已生成完成。每个新业务任务换一个 Idempotency-Key，同一次请求重试时保持不变。

{
  "id": "job_example"
}

2. 查询进度

将创建时返回的 id 保存到 MASS_TASK_ID 环境变量，按选择的语言执行查询。

cURLPythonJavaGo

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

# 先按“鉴权与通用约定”设置环境变量
: "${MASS_API_KEY:?请先设置 MASS_API_KEY}"
: "${MASS_TASK_ID:?请先设置 MASS_TASK_ID}"
MASS_BASE_URL="${MASS_BASE_URL:-https://api.vizen.cc}"

curl --silent --show-error --fail-with-body --max-time 120 \
  -X GET "${MASS_BASE_URL%/}/v1/tasks/${MASS_TASK_ID}" \
  -H "Authorization: Bearer $MASS_API_KEY"

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"]
task_id = urllib.parse.quote(os.environ["MASS_TASK_ID"], safe="")
path = "/v1/tasks/{task_id}".replace("{task_id}", task_id)
headers = {"Authorization": "Bearer " + api_key}
body = None
request = urllib.request.Request(
    base_url + path, data=body, headers=headers, method="GET"
)
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.URLEncoder;
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 taskId = URLEncoder.encode(requireEnv("MASS_TASK_ID"), StandardCharsets.UTF_8)
            .replace("+", "%20");
        String path = "/v1/tasks/{task_id}".replace("{task_id}", taskId);
        HttpRequest request = HttpRequest.newBuilder(URI.create(base + path))
            .timeout(Duration.ofSeconds(120))
            .header("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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"
    "net/url"
    "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 := strings.ReplaceAll("/v1/tasks/{task_id}", "{task_id}", url.PathEscape(requireEnv("MASS_TASK_ID")))
    req, err := http.NewRequest("GET", base + path, nil)
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + requireEnv("MASS_API_KEY"))
    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)) }
}

每隔 3～5 秒查询一次。succeeded 时读取 content.video_url；failed 时查看 error；cancelled 时结束。其他状态继续等待。完整字段和状态见查询与保存结果。

3. 保存视频

curl --fail --location '替换为 content.video_url 的完整地址' --output result.mp4

下载使用返回的签名 URL，无需附带 API Key。选择 MOV 输出时将文件名改为 result.mov。请在完成后的 24 小时内保存文件。

搜索文档

↑ ↓ 选择 · Enter 跳转

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