TONDAR API · SEEDANCE

对接 Seedance
视频任务

先创建任务，再按 ID 查询

Seedance 是异步视频任务，不走对话补全。创建接口返回任务 ID，用同一个 ID 查询，直到 status 进入终态。成功时读取 content.video_url。示例模型 ID 若与控制台不一致，以模型广场为准。

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

最小示例创建任务入参查询结果和方舟接口的差异错误 OpenAI 视频兼容路由

最小示例

创建和查询使用同一个 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视频任务