Seedance API 端点：真实的方舟路径与请求字段

Seedance API 就是火山方舟的内容生成 API，五条事实覆盖大部分内容。创建任务用 POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks。模型 ID 是 doubao-seedance-2-5-260628，该不该选它，两代对照里有判断依据。鉴权是 Authorization: Bearer $ARK_API_KEY。调用是异步的，先建任务再轮询。结果 URL 的有效期是 24 小时。手动出片是另一条产品线，见上手教程。

端点就这一行

整套接入只有两个调用。创建任务是 POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks，读回任务是 GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}。路径里的 /api/v3/ 是 API 版本，跟模型代次无关，所以不管你把 model 写成哪一代，请求发到 /v2/... 都不可能成功。两条路径的分工很干脆：创建那条只收下请求并返回一个 cgt- 开头的任务 ID，查询那条把状态和结果取回来，没有同步接口能一次调用就拿到视频。API 总览把这些调用放回了整个平台的位置上。

这些端点并不存在

搜这个端点，前排大多数会给出一条厂商没有文档化的路径。一家转售站的开篇是 curl -X POST https://api.seedance.com/v2/generate，还带一个方舟里根本不存在的 motion_score 字段。另一家在自己的域名下发布 POST /api/open/v1/video/generations，第三家把 /v2/generate 和 GET /v2/status 写在一起，第四家列的是 /api/v1/generate/text-to-video。

方舟没有 v1 或 v2 这套 API 版本方案。上面那些路径全都属于转发真实服务的中间层，字段名就是破绽：官方请求用 content、ratio 和 duration，转售的写法用 prompt、aspect_ratio 和 motion_score。判断方法只有一条：认准 ark.cn-beijing.volces.com 这个主机名和 contents/generations/tasks 这段路径。

鉴权与两条 Base URL

每个官方调用都带 -H "Authorization: Bearer $ARK_API_KEY" 和 -H "Content-Type: application/json"。API Key 长效有效，所以它属于密钥管理，不属于客户端包。Key 在方舟控制台的 API Key 管理页创建，官方描述为长效 Key，没有公布有效期上限，也没有公布轮换周期，按长期凭据来管就行：放进密钥服务，不要写进仓库，也不要塞进前端。

第二行要把企业版 Key 和它的 Base URL 配成一对使用，混用会 调用失败或产生额外费用。

创建任务：请求字段

最小请求

curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "A 30-second sequence in three shots: [0-10s] a workshop at dawn, [10-20s] hands assembling a clock movement, [20-30s] the finished clock on a windowsill." },
      { "type": "image_url",
        "image_url": { "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_30s_input.png" },
        "role": "reference_image" }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 30
  }'

请求由三组字段撑起来。model 指定模型。content 是数组，每个条目声明一个 type，媒体条目还要声明 role。生成参数放在顶层，这里是 generate_audio、ratio 和 duration。

role 的取值是 first_frame、last_frame、reference_image、reference_video、reference_audio。输出 4 到 30 秒，分辨率 480p、720p 或 1080p，容器 mp4 或 mov，ratio 接受 21:9、16:9、4:3、1:1、3:4、9:16 和 adaptive。content 数组能装多少，由参考素材上限决定：Seedance 2.5 一次最多 50 项，也就是 30 张图、10 段视频、10 段音频，2.0 系列只有 15 项。音频在 2.5 上可以单独出现，在 2.0 上必须配图片或视频。

一点提醒。创建任务参考页里还有教程页没露面的字段，包括 resolution、seed、watermark 和 callback_url，而那一页在本次核查中无法完整读取。上面这些字段都有官方示例里的确切取值。

用 Python 调它

方舟提供官方 Python SDK，包名是 volcenginesdkarkruntime，各视频模型共用一套调用形态。

import os

from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ["ARK_API_KEY"])

task = client.content_generation.tasks.create(
    model="doubao-seedance-2-5-260628",
    content=[
        {
            "type": "text",
            "text": "A workshop at dawn, hands assembling a clock movement.",
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/video-generation/seedance2.5_30s_input.png"
            },
            "role": "reference_image",
        },
    ],
    generate_audio=True,
    ratio="16:9",
    duration=30,
)

print(task.id)

result = client.content_generation.tasks.get(task_id=task.id)
print(result.status)

创建调用返回任务 ID，查询调用返回状态，成功时连托管好的视频 URL 一起返回。

轮询与任务状态

TASK_ID="cgt-2026****-****"

while :; do
  payload=$(curl -s -X GET \
    "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/${TASK_ID}" \
    -H "Authorization: Bearer $ARK_API_KEY")
  status=$(printf '%s' "$payload" | jq -r .status)
  [ "$status" = "queued" ] || [ "$status" = "running" ] || break
  sleep 10
done

if [ "$status" = "succeeded" ]; then
  curl -sL -o "seedance-${TASK_ID}.mp4" \
    "$(printf '%s' "$payload" | jq -r .content.video_url)"
fi

状态取值

status 有六个取值：queued、running、cancelled、succeeded、failed、expired。只有排队中的任务能被取消，取消记录 24 小时后消失。

三条限制决定了这个循环怎么写。只能查最近 7 天的任务，更早的 ID 已经不存在。结果 URL 有效期 24 小时。Seedance 2.5 的结果 URL 下载次数上限 100 次，这是官方在提醒你把文件转存到自己的存储，而不是把方舟链接发给用户。

回包里值得先记住几个字段：id、model、status、content.video_url、usage、created_at、duration、resolution、ratio、seed、output_format 与 draft。官方示例那条回包用的是 doubao-seedance-2-0-260128、720p、5 秒和 108900 token，它是 2.0 的真实回包，不能拿来当 2.5 的用量估计。

四类任务接着约束参数。

视频编辑还要求参考视频本身在 4 到 30 秒之间，而把 omni_reference_task_type 设好，能在生成之前而不是之后把类型错误暴露出来。

官方没有公布什么

本次核查中官方没有公布：延迟、队列深度与成功率保证；任何秒级单价，方舟按 token 计费，公式写在价格拆解里；创建任务页的逐字段类型与默认值，因为那一页无法完整读取；以及这个模型的免费额度。限流是公布的：企业用户 600 次请求每分钟，个人用户 180 次。

另一条容易忽略的官方写法是弱校验传参：把参数追加在提示词后面，例如 --rs 720p --rt 16:9 --dur 5 --seed 11 --cf false --wm true，依次对应分辨率、宽高比、时长、种子、camera_fixed 与 watermark。常规方式仍然是在 request body 里直接传参。

常见问题

Seedance API 是官方的吗？ 是。它文档在火山引擎域下，用方舟 API Key 鉴权，计费也走方舟的定价页。

为什么我的请求在 ratio 上报错？ 首帧/首尾帧、视频编辑和视频延长三类任务都要求 ratio 为 adaptive，视频编辑还要把 duration 设为 -1。

我有多久时间去取视频？ 24 小时，2.5 的结果 URL 最多下载 100 次。任务在 7 天内可查，而回调地址可以替掉轮询循环。

同一个模型 ID 在两条 Base URL 上都能用吗？ 不能。Agent Plan 企业版那条要用自己的 Key 和它支持的模型，混用会失败或产生额外费用。

上线前把每个字段对着官方页面核一遍。

发布于

2026年9月17日

信息核验

2026年9月17日

作者

AI Tool Blog 编辑部