
TONDAR API · SEEDANCE
对接 Seedance
视频任务
先创建任务,再按 ID 查询
Seedance 是异步视频任务,不走对话补全。创建接口返回任务 ID,用同一个 ID 查询,直到 status 进入终态。成功时读取 content.video_url。参考图既可以用公网 URL,也可以先上传到素材库再以 asset:// 引用。示例模型 ID 若与控制台不一致,以模型广场为准。
POST/doubao
最小示例
创建和查询使用同一个 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 |
| Authorization | header | 必填 | Bearer 后面接控制台 Key。 |
| Content-Type | header | 必填 | application/json。参考图和参考视频用 URL,这条路由不接收文件上传。 |
创建成功后立刻拿到对外任务 ID。后续查询、以及 content 里引用上一条成片,都用这个 ID。
created.json
{
"id": "task_xxx",
"status": "queued"
}入参
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 模型广场中的 Seedance ID。示例 doubao-seedance-2-0-260128 只在控制台开通了该 ID 时可用。 |
| content | array | 必填 | 至少包含一段文本,或一张参考图、一段参考视频。各项结构见下表。 |
| duration | number | 可选 | 时长,单位秒,须为正数。不传则由模型使用自己的默认时长。 |
| resolution | string | 可选 | 480p、720p、1080p、4k 之一,且必须是该模型支持的档位。不传则由模型决定输出分辨率。 |
| generate_audio | boolean | 可选 | 是否输出音频。只对支持音频的型号生效;不传时按开启处理。 |
| ratio / seed / watermark / camera_fixed / frames | 按方舟字段 | 可选 | 火山方舟视频任务里的这些字段会原样转发。frames 与 duration 描述的是同一段时长,按你采用的字段填写。 |
content 的每一项
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type = text | object | 可选 | 文生视频的提示词。字段 text 为字符串。纯文本任务至少有一项。 |
| type = image_url | object | 可选 | 参考图。image_url.url 为可公网访问的图片地址,用于图生视频。 |
| type = video_url | object | 可选 | 参考视频。video_url.url 为视频地址。只有支持参考视频的型号接受,其余型号会拒绝。 |
| type = draft_task | object | 可选 | 基于已有成片继续生成。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。 |
| Authorization | header | 必填 | 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,删除后本地与上游同步失效,引用会按未登记处理。