Docs
← 返回文档列表

Seedance 视频生成 API

本文档描述视频生成与素材资产相关接口协议。

对应能力：

  • 视频生成任务创建
  • 视频生成任务查询
  • 视频生成任务取消
  • 私域素材资产创建
  • 私域素材资产查询

1. 基础信息

  • API 基础地址：https://router.qingting.work
  • 内容生成接口前缀：/v1/contents/generations
  • 素材资产接口前缀：/v1/origin/assets

2. 鉴权方式

支持两种写法：

http
Authorization: Bearer <api_key>

或：

http
x-api-key: <api_key>

认证失败时返回：

json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

3. 计费说明

3.1 计费时机

  1. 调用创建任务接口提交任务
  2. 轮询查询接口获取任务状态
  3. 首次查询到任务成功完成时，系统自动读取 usage.total_tokens 并完成扣费
  4. 同一任务只结算一次，后续重复查询不会重复扣费

3.2 价格档位

  • 请求 content 中包含 video_url → 按「含视频」价格结算
  • 请求 content 中不包含 video_url → 按「不含视频」价格结算
  • image_url 和 audio_url 不触发「含视频」价格

注意：

  • 任务未完成不扣费
  • 任务失败、取消或无可用结果不扣费

4. 路由清单

路由方法说明
/v1/contents/generations/tasksPOST创建视频生成任务
/v1/contents/generations/tasks/{id}GET查询视频生成任务
/v1/contents/generations/tasks/{id}DELETE取消视频生成任务
/v1/origin/assets/createPOST创建素材资产
/v1/origin/assets/get?id={id}POST查询素材资产

5. 创建视频生成任务

5.1 请求

http
POST /v1/contents/generations/tasks?requestId=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer your-api-key
Content-Type: application/json

请求体示例：

json
{
  "model": "seedance-2-0",
  "content": [
    {
      "type": "text",
      "text": "保留人物服装和镜头运动风格，生成一段夏日海边广告视频"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ref-1.png"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/ref-1.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/ref-1.mp3"
      },
      "role": "reference_audio"
    }
  ],
  "generate_audio": true,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 8,
  "watermark": false
}

说明：

  • model 填可用的模型名称，请在「模型广场」查看
  • requestId 可选，建议传 UUID 便于排障
  • content 支持 text、image_url、video_url、audio_url

代码示例：

import requests
import uuid

api_key = "your-api-key"
base_url = "https://router.qingting.work"
request_id = str(uuid.uuid4())

response = requests.post(
    f"{base_url}/v1/contents/generations/tasks",
    params={"requestId": request_id},
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-0",
        "content": [
            {"type": "text", "text": "生成一段夏日海边广告视频"},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/ref.png"},
                "role": "reference_image",
            },
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 8,
    },
)

data = response.json()
print("Task ID:", data["id"])  # cgt-2026xxxx

5.2 成功响应

json
{
  "id": "cgt-2026xxxx"
}

5.3 错误响应

json
{
  "error": {
    "message": "audio_url 类型内容必须提供 audio_url 字段",
    "type": "invalid_request_error"
  }
}

6. 查询视频生成任务

6.1 请求

http
GET /v1/contents/generations/tasks/cgt-2026xxxx
Authorization: Bearer your-api-key

代码示例：

import requests

api_key = "your-api-key"
base_url = "https://router.qingting.work"
task_id = "cgt-2026xxxx"

response = requests.get(
    f"{base_url}/v1/contents/generations/tasks/{task_id}",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()
print("Status:", data["status"])

if data["status"] == "succeeded":
    print("Video URL:", data["content"]["video_url"])

6.2 成功响应示例

json
{
  "seed": 80843,
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 411300,
    "total_tokens": 411300
  },
  "created_at": 1774506188,
  "generate_audio": true,
  "resolution": "720p",
  "content": {
    "video_url": "https://example.com/result.mp4"
  },
  "duration": 11,
  "framespersecond": 24,
  "updated_at": 1774506889,
  "draft": false,
  "model": "seedance-2-0",
  "service_tier": "default",
  "id": "cgt-2026xxxx",
  "status": "succeeded",
  "ratio": "16:9"
}

6.3 轮询建议

  1. 创建任务后每隔几秒查询一次
  2. status 变为 succeeded 时读取结果，系统自动完成扣费
  3. status 变为 failed / cancelled / expired 时按失败处理

7. 取消视频生成任务

7.1 请求

http
DELETE /v1/contents/generations/tasks/cgt-2026xxxx
Authorization: Bearer your-api-key

代码示例：

import requests

api_key = "your-api-key"
base_url = "https://router.qingting.work"
task_id = "cgt-2026xxxx"

response = requests.delete(
    f"{base_url}/v1/contents/generations/tasks/{task_id}",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()
print("Cancelled:", data["status"])  # cancelled

7.2 成功响应示例

json
{
  "message": "取消成功"
}

说明：一般只有任务还在排队阶段时取消才有意义。

8. 创建素材资产

8.1 请求

http
POST /v1/origin/assets/create?requestId=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer your-api-key
Content-Type: application/json

请求体示例：

json
{
  "URL": "https://example.com/asset-image.png",
  "Name": "brand-reference-image",
  "AssetType": "Image",
  "ProjectName": "default"
}

字段说明：

字段类型必填说明
URLstring是素材文件的可访问 URL
Namestring是素材名称
AssetTypestring是素材类型：Image、Video、Audio
ProjectNamestring是项目名称，一般传 default

8.2 成功响应示例

json
{
  "Result": {
    "Id": "asset-20260330170834-sztnw"
  }
}

9. 查询素材资产

9.1 请求

http
POST /v1/origin/assets/get?id=asset-20260330170834-sztnw
Authorization: Bearer your-api-key
Content-Type: application/json

请求体通常可为空：

json
{}

9.2 成功响应示例

json
{
  "Result": {
    "Id": "asset-20260330164126-dwr9q",
    "Name": "",
    "URL": "https://example.com/asset.png",
    "AssetType": "Image",
    "GroupId": "group-20260330162801-vmpfz",
    "Status": "Active",
    "CreateTime": "2026-03-30T08:41:26Z",
    "UpdateTime": "2026-03-30T08:41:33Z",
    "ProjectName": "default"
  }
}

推荐使用方式：

  1. 先调用 /v1/origin/assets/create
  2. 再轮询 /v1/origin/assets/get?id=...
  3. 只有 Result.Status = Active 时，再把素材 ID 用于视频生成请求

10. 推荐接入流程

10.1 纯视频生成

  1. POST /v1/contents/generations/tasks 创建任务
  2. 轮询 GET /v1/contents/generations/tasks/{id}
  3. status 为 succeeded 时读取视频 URL

10.2 先入库素材再生成视频

  1. POST /v1/origin/assets/create 创建素材
  2. 轮询 POST /v1/origin/assets/get?id=... 直到 Status = Active
  3. 在创建任务请求的 content 中，使用 asset://{asset_id} 格式引用素材（而非直接使用素材 URL）
  4. 轮询任务查询接口获取结果

引用素材示例（在视频生成请求体的 content 数组中）：

json
{
  "type": "image_url",
  "image_url": {
    "url": "asset://asset-20260507111841-fd6q4"
  },
  "role": "reference_image"
}

注：asset:// 协议后跟素材的 Id（即 /v1/origin/assets/create 返回的 Result.Id，或 /v1/origin/assets/get 返回的 Result.Id）。

11. 错误处理

HTTP 状态码说明
401认证失败：API Key 无效、已过期或未提供
402余额不足
400请求参数错误
502服务错误