TONDAR API · SEEDANCE

对接 Seedance
视频任务

先创建任务,再按 ID 查询

Seedance 是异步视频任务,不走对话补全。创建接口返回任务 ID,用同一个 ID 查询,直到 status 进入终态。成功时读取 content.video_url。参考图既可以用公网 URL,也可以先上传到素材库再以 asset:// 引用。示例模型 ID 若与控制台不一致,以模型广场为准。

POST/doubao/api/v3/contents/generations/tasks

最小示例

创建和查询使用同一个 Key。查询没有请求体。下面的循环在 succeeded、failed、expired、cancelled 时停下。

curl
curl https://api.tondarai.com/doubao/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TONDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "海边日落,镜头缓慢推进"}
    ],
    "duration": 5,
    "resolution": "720p"
  }'
python
import os, time, requests

base = "https://api.tondarai.com"
headers = {
    "Authorization": f"Bearer {os.environ['TONDAR_API_KEY']}",
    "Content-Type": "application/json",
}
created = requests.post(
    f"{base}/doubao/api/v3/contents/generations/tasks",
    headers=headers,
    json={
        "model": "doubao-seedance-2-0-260128",
        "content": [{"type": "text", "text": "海边日落,镜头缓慢推进"}],
        "duration": 5,
        "resolution": "720p",
    },
).json()

task_id = created["id"]
while True:
    task = requests.get(
        f"{base}/doubao/api/v3/contents/generations/tasks/{task_id}",
        headers=headers,
    ).json()
    if task.get("status") in {"succeeded", "failed", "expired", "cancelled"}:
        break
    time.sleep(3)
print(task)

创建任务

创建

字段类型必填说明
方法POST必填提交一条视频生成任务。
路径string必填/doubao/api/v3/contents/generations/tasks
Authorizationheader必填Bearer 后面接控制台 Key。
Content-Typeheader必填application/json。参考图和参考视频用 URL,这条路由不接收文件上传。

创建成功后立刻拿到对外任务 ID。后续查询、以及 content 里引用上一条成片,都用这个 ID。

created.json
{
  "id": "task_xxx",
  "status": "queued"
}

入参

请求体

字段类型必填说明
modelstring必填模型广场中的 Seedance ID。示例 doubao-seedance-2-0-260128 只在控制台开通了该 ID 时可用。
contentarray必填至少包含一段文本,或一张参考图、一段参考视频。各项结构见下表。
durationnumber可选时长,单位秒,须为正数。不传则由模型使用自己的默认时长。
resolutionstring可选480p、720p、1080p、4k 之一,且必须是该模型支持的档位。不传则由模型决定输出分辨率。
generate_audioboolean可选是否输出音频。只对支持音频的型号生效;不传时按开启处理。
ratio / seed / watermark / camera_fixed / frames按方舟字段可选火山方舟视频任务里的这些字段会原样转发。frames 与 duration 描述的是同一段时长,按你采用的字段填写。

content 的每一项

字段类型必填说明
type = textobject可选文生视频的提示词。字段 text 为字符串。纯文本任务至少有一项。
type = image_urlobject可选参考图。image_url.url 为可公网访问的图片地址,用于图生视频。
type = video_urlobject可选参考视频。video_url.url 为视频地址。只有支持参考视频的型号接受,其余型号会拒绝。
type = draft_taskobject可选基于已有成片继续生成。draft_task.id 填创建接口返回的对外任务 ID。
image-to-video.json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "让画面里的人转头微笑"},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ],
  "duration": 5,
  "resolution": "720p"
}

查询结果

查询

字段类型必填说明
方法GET必填读取任务当前状态。没有请求体。
路径string必填/doubao/api/v3/contents/generations/tasks/{id},id 是创建时返回的对外 ID。
Authorizationheader必填Bearer 后面接同一个 Key。
  • queued 或 pending:排队中,继续查询。
  • running 或 processing:生成中,继续查询。
  • succeeded:完成。视频地址在 content.video_url。
  • failed、expired 或 cancelled:已结束且没有视频。原因在 error.message。
succeeded.json
{
  "id": "task_xxx",
  "status": "succeeded",
  "content": {
    "video_url": "https://..."
  }
}
failed.json
{
  "id": "task_xxx",
  "status": "failed",
  "error": { "message": "失败原因" }
}

和方舟接口的差异

  • 路径挂在 https://api.tondarai.com 下,前缀是 /doubao/api/v3/contents/generations/tasks。
  • Authorization 使用 Tondar 控制台 Key,不使用火山引擎的密钥。
  • 创建和查询返回的 id 是对外任务 ID。draft_task.id 也填这个 ID。
  • 分辨率不在该模型档位内时,请求会在转发前被拒绝。

错误

error.json
{
  "error": {
    "code": "invalid_request",
    "message": "具体原因"
  }
}
  • 未带 Key,或 Key 无效:请求被拒绝。
  • 没有 content,或 content 里既没有文本也没有参考素材:请求被拒绝。
  • resolution 不在该模型支持的档位里:请求被拒绝,正文会列出允许的档位。
  • 任务生成失败:创建请求本身是成功的,之后查询的 status 为 failed,阅读 error.message。

OpenAI 视频兼容路由

如果调用方已经按 OpenAI Videos 写了客户端,可以用下面三条路径。它只覆盖提示词、时长和尺寸。分辨率档位、音频开关、参考视频和 content 数组请用上面的任务接口。

兼容路径

字段类型必填说明
POST /v1/videos创建必填JSON 字段:model、prompt、seconds、size。seconds 为 1 到 3600 的数。不接受文件上传。
GET /v1/videos/{task_id}查询必填返回 id、object(video)、status、progress。status 为 queued、in_progress、completed、failed。
GET /v1/videos/{task_id}/content取片可选任务完成后拉取视频内容。

素材库(上传图片并引用)

Seedance 支持先把图片上传到素材库,审核通过(Active)后在创建视频时以 asset://<素材ID> 引用。素材挂在你 Key 名下,只能引用自己上传的素材;跨用户引用一律按素材不存在处理。素材在上传时所在的渠道与模型上有效,创建视频引用 asset:// 时网关会自动路由回该渠道,无需再关心渠道选择。

素材在控制台「Seedance 素材库」页面可见:管理员看全部用户的素材,普通用户看自己创建的,并可展开分组、预览图片。

素材接口一览

字段类型必填说明
POST /v1/api/assets/upload?model={model}上传素材必填上传一张图片。url 为可公网访问的图片地址(该路由不接收文件上传,先自己传到图床或对象存储再提交地址);asset_type 固定 Image;name 为素材名称;group_id 可选,不传时上游会自动归入 Key 名下的素材组(响应只返回素材 ID,实际归组以查询接口为准)。
GET /v1/api/assets/{asset_id}?model={model}查询素材必填返回素材状态与下载地址。data.status 取值 Processing(审核中,稍后查询)/ Active(可用,可引用)/ Failed(审核失败,读 data.Error)。data.URL 是有时效的图片下载地址,data.GroupId 是实际归组。
POST /v1/seedance-gateway?Action={Action}&Version=2024-01-01&model={model}管理必填素材与素材组的管理入口,按 Action 分流:CreateAssetGroup(建组,请求体 {"Name":"..."},响应 Result.Id 建组后上传时用作 group_id)、ListAssetGroups / ListAssets(列表,请求体 {"PageNumber":1,"PageSize":20},PageSize 最大 100)、DeleteAsset / DeleteAssetGroup(删除,请求体 {"Id":"..."})。
建组 + 上传 + 查询(curl)
# 1. 创建素材组
curl https://api.tondarai.com/v1/seedance-gateway?Action=CreateAssetGroup&Version=2024-01-01&model=doubao-seedance-2-0-260128 \
  -H "Authorization: Bearer $TONDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "产品演示参考图"}'
# 响应: {"Result": {"Id": "group-example"}}

# 2. 上传素材(group_id 可选,不传则由上游自动归组)
curl "https://api.tondarai.com/v1/api/assets/upload?model=doubao-seedance-2-0-260128" \
  -H "Authorization: Bearer $TONDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-example",
    "url": "https://example.com/reference.jpg",
    "asset_type": "Image",
    "name": "产品演示参考图"
  }'
# 响应: {"code": 0, "data": {"Id": "asset-example"}}

# 3. 轮询素材状态,直到 Active
curl "https://api.tondarai.com/v1/api/assets/asset-example?model=doubao-seedance-2-0-260128" \
  -H "Authorization: Bearer $TONDAR_API_KEY"
# data.status: Processing -> Active(或 Failed,读 data.Error)
引用素材生成视频
# asset:// 引用的归属校验与渠道钉扎在 Seedance 原生协议路由上生效
curl https://api.tondarai.com/v1/video/seedance/tasks \
  -H "Authorization: Bearer $TONDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型广场中的 Seedance 模型 ID>",
    "content": [
      { "type": "image_url", "image_url": { "url": "asset://asset-example" } },
      { "type": "text", "text": "以参考图中的主体生成一段短片" }
    ],
    "duration": 5,
    "resolution": "720p"
  }'
  • 素材必须处于 Active 才能引用;引用 Processing 或 Failed 的素材会在上游失败。
  • asset:// 引用的归属校验与渠道钉扎在 /v1/video/seedance/tasks 这条入口生效:未登记、别人的素材、素材组 ID 一律 400 拒绝(asset_not_found / invalid_asset),请求不会发出扣费。/doubao/api/v3/... 厂商路由是否发布取决于网关配置,且不做素材校验。
  • 多个 asset:// 引用必须属于同一渠道,跨渠道混用返回 400(asset_channel_conflict)。
  • 引用素材时网关把请求钉扎回素材上传的渠道,该渠道被禁用或不再声明请求的模型时返回 400(asset_channel_disabled / asset_channel_model_mismatch)。
  • 删除素材或分组用 DeleteAsset / DeleteAssetGroup,删除后本地与上游同步失效,引用会按未登记处理。