Seedance API 接入：真实端点、模型 ID 与字段

Seedance 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 小时。

Seedance API 到底是什么

ByteDance Seedance 2.5 没有自己的开发者站点，官方公布的开发者入口只有火山引擎方舟。它的形态是一个任务：创建任务的调用返回一个 ID，查询任务的调用返回状态，成功时再返回一个由方舟托管的视频 URL。整个过程没有同步模式，状态得由你的 worker 自己保存。Seedance 主题总览页汇总了各代模型与平台入口。

那些并不存在的端点

搜这个词，你会遇到官方文档里根本不存在的端点：/v1/generate、/v1/status、/v2/generate、/v2/status，还配了一套 v1/v2 的版本说法。方舟没有这种版本划分：路径里的 /api/v3/ 是 API 版本段，不是模型版本号。另有一个 GitHub 仓库自称 Seedance 2.5 的官方 API 文档，归属却是个人账号，不是 ByteDance 也不是火山引擎。转发类站点同样不是官方渠道。

鉴权与两条 Base URL

每个请求都要带 -H "Authorization: Bearer $ARK_API_KEY"。这个 Key 在方舟控制台的 API Key 管理页获取，官方写明为长效。主机上有两条 Base URL，官方明确警告它们不可混用。

第二条必须搭配 Agent Plan 企业版专属 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 与生成参数。content 是一个有序数组，每一项声明自己的 type，图片和视频项还要声明 role。输出时长为 4 到 30 秒，写 -1 则由模型在有效区间内自行选择；分辨率为 480p、720p 或 1080p，帧率 24 fps，格式为 mp4 或 mov。

参考素材与比例规则

一次调用最多接收 50 个参考素材：30 张图片、10 段视频、10 段音频。role 取值为 first_frame、last_frame、reference_image、reference_video、reference_audio，且只有 2.5 这一代支持单独传入音频，不必搭配图片或视频。其中四种任务类型会反向约束参数。

视频编辑还要求参考视频时长在 4 到 30 秒之间。官方另有一个 omni_reference_task_type 参数，用来显式声明任务类型，把报错提前到生成之前。

查询任务与 status 取值

curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/cgt-2026****-****" \
  -H "Authorization: Bearer $ARK_API_KEY"

{
  "id": "cgt-2026****-****",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/xxx"
  },
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "created_at": 1779348818,
  "updated_at": 1779348874,
  "seed": 78674,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "generate_audio": true,
  "draft": false,
  "priority": 0
}

status 的六个取值

任务 ID 以 cgt- 开头，status 有六个取值：queued、running、cancelled、succeeded、failed、expired。只有排队中的任务能被取消，取消状态 24 小时后自动删除。官方说明生成耗时随模型、负载和输出规格变化，另外也提供 callback URL 来替代轮询。

在结果 URL 过期前取件

# Poll until the task leaves the queue, then take the URL immediately.
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" = "running" ] || [ "$status" = "queued" ] || break
  sleep 10
done

# The vendor states the video URL is valid for 24 hours: archive it now.
if [ "$status" = "succeeded" ]; then
  curl -sL -o "seedance-${TASK_ID}.mp4" "$(printf '%s' "$payload" | jq -r .content.video_url)"
fi

这条循环受三条约束：仅支持查询最近 7 天的任务记录，所以隔了更久的 ID 已经查不到；视频 URL 有效期为 24 小时，请及时下载或转存；Seedance 2.5 生成的视频 URL 下载次数上限为 100 次，所以把文件落到自己的存储里是必要动作。其他厂商的异步接口形态类似，例如 Pika 主题总览页。

按 token 计费与两个官方公式

计费单位是 token，而且单价随输出分辨率和「输入是否包含视频」分档。

1080p 一档当前按原价 72 折执行。两个公式把单价变成账单：视频价格是 token 单价 × token 用量；token 用量是（输入视频时长 + 输出视频时长）× 输出视频的宽 × 高 × 帧率 ÷ 1024。官方规则写明仅对成功生成的视频计费。以 5 秒、720p、16:9 的成片为例，套用官方公式即 5 × 1280 × 720 × 24 ÷ 1024，约 10.8 万 token，按 70.00 的单价接近 7.6 元——这一步乘法是我们的推算，不是官方公布的数字，官方从未给出「每秒多少钱」。还有一点要注意：上面那段回包是 2.0 的示例，它的 token 用量不能拿来当 2.5 的估算依据。

官方没有公布的部分

官方没给的东西有：

• 本模型的免费额度。第三方写的数字不是官方口径。
• 任何秒级单价，也没有 token 与秒数之间的换算示例。
• 若干请求字段的完整类型与默认值，因为其中一页本次未能完整读取。
• 延迟、排队深度与成功率承诺。

限流反而是公布的，而且比某些汇总站写得更严：在线推理企业用户每分钟最多 600 次、个人用户 180 次，最大并发 10 / 3，接口级 QPS 为查询任务 20、查询列表 1、取消或删除 20。

常见问题

Seedance API 是官方的吗？ 是。文档在火山引擎域名下，用方舟 API Key 鉴权，价格发布在方舟的模型价格页。

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

生成结果能留多久？ 24 小时。2.5 的结果 URL 最多下载 100 次，任务记录只支持回查 7 天。

可以不轮询吗？ 可以，用官方提供的 callback URL，状态变化时它会推送一条 POST。

一条片子要多少钱？ 官方只给 token 单价，不给单条价格；套公式算出来的数请标成你自己的估算。

把端点、模型 ID 和 24 小时这三件事当成集成的基本盘，其余数字一律回官方页面核对。Seedance 使用教程讲的是浏览器里那条路，不需要这些管道。

发布于

2026年9月14日

信息核验

2026年9月14日

作者

AI Tool Blog 编辑部