Seedance 2.0 中转站 API 文档

Seedance 2.0 中转站为 B 端客户提供与火山引擎 Seedance 2.0 官方 API 完全兼容的代理接口。
您只需将 Base URL 和 API Key 替换为中转站分配的地址和 Relay Key，其余请求格式完全一致。

兼容性说明

中转站 API 与火山引擎 Seedance 2.0 官方 API 完全兼容。您现有的代码只需修改两处：

// 修改前（直接调用火山引擎）
baseURL: "https://ark.cn-beijing.volces.com/api/v3"
Authorization: Bearer <火山引擎 API Key>

// 修改后（通过中转站）
baseURL: "https://your-host/relay/v3"
Authorization: Bearer rk-xxxxxxxx

快速开始

3 步快速接入：

最简示例 (cURL)

# 第一步：创建视频生成任务
curl -X POST https://your-host/relay/v3/contents/generations/tasks \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "温暖阳光下，一只猫在阳台上打哈欠"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

# 返回：{"id": "cgt-xxxxxxxxxxxx-xxxxx"}

# 第二步：轮询任务状态（重复直到状态为终态）
curl https://your-host/relay/v3/contents/generations/tasks/cgt-xxxxxxxxxxxx-xxxxx \
  -H "Authorization: Bearer rk-your-relay-key"

# 完成时返回：{"status": "succeeded", "content": {"video_url": "https://..."}, ...}

鉴权方式

所有请求必须在 HTTP Header 中携带 Relay Key：

处理流程

视频生成流程

素材 + 视频生成流程

错误码

所有响应遵循统一格式：

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "配额已用尽或账户未激活"
  }
}

中转站错误

上游错误（来自火山引擎）

当上游火山引擎 API 返回错误时，中转站会原样转发响应体。常见的 Seedance 错误：

配额与限流

每个中转账户都有可配置的配额限制：

当配额达到上限时，API 返回 429 QUOTA_EXCEEDED。当任务到达终态（成功/失败/过期/取消）时，通过查询接口会自动减少并发任务计数。

创建视频生成任务

创建 Seedance 2.0 视频生成任务。支持文生视频、图生视频（首帧/首尾帧）、多模态参考生成等模式。

请求体

内容项说明

响应

{
  "id": "cgt-20260601120000-xxxxx"
}

返回任务 ID，使用查询任务接口轮询结果。

可用模型

您也可以使用管理员配置的自定义端点 ID（例如 ep-20260528xxxxxx-xxxxx）。

查询任务状态

轮询视频生成任务的状态。请持续轮询直到状态变为终态。

路径参数

响应（运行中）

{
  "id": "cgt-20260601120000-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "running"
}

响应（成功）

{
  "id": "cgt-20260601120000-xxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-prod-asset.tos-cn-beijing.volces.com/...",
    "last_frame_url": "https://..."
  },
  "usage": {
    "completion_tokens": 50638,
    "total_tokens": 50638
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "seed": 37072,
  "generate_audio": true
}

任务状态值

查询可用模型与端点

查询当前中转账户可用的模型和端点列表。用于发现已配置的模型/端点。

响应

{
  "success": true,
  "data": {
    "allowed_models": ["ep-20260528130905-bjj8g"],
    "endpoints": [
      {
        "id": "ep-20260528130905-bjj8g",
        "name": "seedance-2.0-fast",
        "status": "Running",
        "model_name": "doubao-seedance-2-0-fast",
        "model_version": "260128",
        "description": "快速模型端点"
      }
    ]
  }
}

allowed_models：如果非空，则仅允许使用这些模型 ID / 端点 ID。
endpoints：该账户 IAM 子用户可见的所有端点。状态为 Running 表示端点可用。

素材库概述

素材库允许您上传个人图片/视频作为素材，用于 Seedance 2.0 视频生成（例如虚拟形象、参考素材等）。素材按 素材组 进行分组管理。

在视频生成中使用素材

素材上传后，等待状态变为 active，即可在视频生成提示词中使用其 ID：

{
  "content": [
    { "type": "image_url", "image_url": { "url": "asset://asset-20260601-xxxxx" } },
    { "type": "text", "text": "图片1中的人物正在雨中跳舞" }
  ]
}

素材要求

创建素材组

创建一个素材组，用于组织相关素材（例如同一虚拟角色的所有素材）。

请求体

响应

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "group-20260601-xxxxx"
  }
}

列表素材组

请求体

请求示例

{
  "Filter": { "GroupType": "AIGC" },
  "PageNumber": 1,
  "PageSize": 10
}

上传素材

向素材组中上传素材（图片/视频/音频）。这是一个异步接口，素材初始状态为 processing。

请求体

响应

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "asset-20260601-xxxxx",
    "Status": "Processing"
  }
}

查询素材

查询素材的状态和详细信息。请轮询直到状态变为 Active，然后才能在视频生成中使用。

响应（已激活）

{
  "ResponseMetadata": { ... },
  "Result": {
    "Id": "asset-20260601-xxxxx",
    "Status": "Active",
    "AssetType": "Image",
    "PreviewUrl": "https://..."
  }
}

素材状态值：Processing（处理中） → Active（可使用） 或 Failed（失败）。

示例：文生视频

// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "夕阳下，一只金毛在海滩奔跑，电影感，慢动作，4K画质"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true
}

示例：图生视频（首帧模式）

// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" }
    },
    {
      "type": "text",
      "text": "镜头缓缓推进，人物微笑并挥手"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

示例：素材 + 视频生成

使用已上传的虚拟形象素材作为参考：

// 第一步：上传素材（需先创建素材组）
// POST /relay/v3/assets
{
  "AssetGroupId": "group-20260601-xxxxx",
  "URL": "https://example.com/portrait.jpg",
  "AssetType": "Image"
}
// 返回：{ "Result": { "Id": "asset-20260601-xxxxx" } }

// 第二步：等待素材变为 Active 状态（轮询 POST /relay/v3/assets/asset-xxx）

// 第三步：使用素材生成视频
// POST /relay/v3/contents/generations/tasks
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "image_url",
      "image_url": { "url": "asset://asset-20260601-xxxxx" },
      "role": "reference_image"
    },
    {
      "type": "text",
      "text": "图片1中的人物正在舞台上发表演讲"
    }
  ],
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

cURL 示例

创建任务

curl -X POST https://your-host/relay/v3/contents/generations/tasks \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{"type": "text", "text": "夜晚的未来城市，飞行汽车穿梭其中"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

查询任务

curl https://your-host/relay/v3/contents/generations/tasks/cgt-xxxxx \
  -H "Authorization: Bearer rk-your-relay-key"

查询模型列表

curl https://your-host/relay/v3/models \
  -H "Authorization: Bearer rk-your-relay-key"

列表素材组

curl -X POST https://your-host/relay/v3/assets/groups/list \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupType": "AIGC"}, "PageNumber": 1, "PageSize": 10}'

创建素材组

curl -X POST https://your-host/relay/v3/assets/groups \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{"Name": "我的角色", "GroupType": "AIGC"}'

上传素材

curl -X POST https://your-host/relay/v3/assets \
  -H "Authorization: Bearer rk-your-relay-key" \
  -H "Content-Type: application/json" \
  -d '{
    "AssetGroupId": "group-xxxxx",
    "URL": "https://example.com/portrait.jpg",
    "AssetType": "Image"
  }'