视频生成/Seedance / 创建任务

通过字节（Seedance）接口创建异步视频生成任务。

Seedance / 创建任务

本页用于创建字节（Seedance）视频生成任务。

调用面

项目值
Base URLhttps://video.unigateway.ai
鉴权Authorization: Bearer $UNIGATEWAY_API_KEY

接口

  • 方法：POST
  • 路径：/api/v3/contents/generations/tasks
  • 完整地址：https://video.unigateway.ai/api/v3/contents/generations/tasks

最小请求

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "一只柴犬在雨后街道上慢动作奔跑，电影质感。" }
  ]
}

常用可选字段

字段类型说明
ratiostring画幅比例，例如 16:9、9:16。
durationnumber目标时长（秒）。
resolutionstring分辨率档位（按模型能力支持）。
generate_audioboolean是否生成音频。
service_tierstring服务档位（用于筛选和计费策略）。

参数校验说明

字段规则
model使用账号内真实可用的 Seedance 模型 ID。
content至少包含一个受支持的输入项。
ratio / resolution属于模型相关字段，先用一次 canary 请求验证。
generate_audio不要默认所有模型变体都支持。

cURL 示例

curl https://video.unigateway.ai/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {"type": "text", "text": "夜晚赛博朋克城市，镜头沿街道快速推进。"}
    ],
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": false
  }'

响应示例

{
  "id": "media_task_8f3d0a"
}

说明

  1. 创建成功只保证返回任务 id，最终结果需要后续查询。
  2. 后续使用返回的任务 id 调用 GET /api/v3/contents/generations/tasks/{id} 查询状态。
  3. 这套请求体是 Seedance 特有的任务式接口，不应默认套用到后续其他视频厂商。

推荐查询衔接方式

  • 正常流量下，首次查询建议等待 2-3 秒。
  • 当任务持续处于 queued 或 running 时，逐步拉长轮询间隔。
  • 在调用方保存自己的请求追踪字段，方便识别重复提交。

常见失败场景

状态常见原因处理建议
400字段结构不合法或可选参数不受支持先移除可选字段，回到最小请求重试
401 / 403Key 无效或权限不足先修复凭证或账号权限，不要盲目重试
429频控或审核上限做退避和排队，不要持续打创建接口
5xx网关或上游异常做封顶退避重试，再决定是否重新提交

Example request

Run it in your stack

Pick the SDK style that matches your app and copy the snippet directly into your project.

import requests

api_key = "<YOUR_UNIGATEWAY_API_KEY>"
base_url = "https://video.unigateway.ai"
headers = {
    "Authorization": "Bearer " + api_key,
    "Content-Type": "application/json",
}

resp = requests.post(
    base_url + "/api/v3/contents/generations/tasks",
    headers=headers,
    json={
        "model": "doubao-seedance-2-0-260128",
        "content": [{"type": "text", "text": "A cinematic city night drive."}],
        "ratio": "16:9",
        "duration": 5,
    },
)
resp.raise_for_status()
print(resp.json())