国内怎么调用 Seedance 2.5 视频生成 API？

Seedance 2.5 是字节跳动豆包大模型团队的视频生成模型，在 EasyAPI 的公开目录中的模型 ID 为 seedance-2.5。国内开发者注册 EasyAPI、创建 API Key 并保证钱包有余额后，就可以通过 HTTP 接口调用。

和文本模型不同，视频生成耗时较长，不能通过对话接口同步返回，而是「提交任务 → 轮询状态 → 下载成片」的异步流程。下面的接口与字段均来自 EasyAPI 的视频生成 API 文档。

关键要点

• 提交任务：POST https://token.easyapi.com/v1/videos，成功时返回 202 和 job_id。
• 查询状态：GET https://token.easyapi.com/v1/videos/{job_id}，状态取值为 pending、in_progress、completed、failed。
• 任务完成后响应里会出现 download_url，同时返回文件过期时间 expires_at，需要及时下载保存。
• 必填字段只有 model 和 prompt，时长、分辨率、宽高比、参考素材等为可选。
• 视频按量计费：提交时预扣预估费用，任务完成后按实际结果结算。

调用流程

1. 在控制台令牌管理中创建 API Key，并确认钱包余额充足。
2. 提交生成任务，记下返回的 job_id。
3. 每隔几秒查询一次任务状态。
4. 状态为 completed 后，从 download_url 下载视频；为 failed 时根据返回信息调整后重新提交。

提交任务

curl -X POST https://token.easyapi.com/v1/videos \
  -H "Authorization: Bearer $EASYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-20261110-001" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "一只金毛犬在阳光下的海滩上奔跑，电影感运镜",
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": false
  }'

Idempotency-Key 是可选的幂等键：用相同的 key 重复提交时会返回首次创建的任务，不会重复创建，适合在网络重试时防止重复扣费。

返回内容包在 data 里，关键字段如下（示例值为示意）：

{
  "code": 200,
  "msg": "",
  "data": {
    "job_id": "video_abc123",
    "status": "in_progress",
    "status_url": "https://token.easyapi.com/v1/videos/video_abc123",
    "estimated_cost": "…",
    "pre_deduct_amount": "…"
  }
}

查询状态并下载

curl https://token.easyapi.com/v1/videos/video_abc123 \
  -H "Authorization: Bearer $EASYAPI_API_KEY"

任务完成后，data 中会包含 download_url、billed_cost（实际扣费金额）、billing_status（pre_deducted 或 settled）以及 expires_at。

请求字段

图生视频通过 input_references 传入素材，role 可取 first_frame（首帧图）、last_frame（尾帧图）、reference_image（外观参考图）、reference_video、reference_audio 等，素材地址必须是可直接访问的 HTTPS 地址。

需要注意的地方

• 文档示例与本文模型不同。 官方文档的示例以 Seedance 2.0 为例。Seedance 2.5 支持的时长、分辨率和参考素材类型可能不同，提交前请在模型广场的模型详情里确认，并以那里显示的模型 ID 为准。
• 余额不足会被拒绝。 提交时返回 402，响应中包含预估费用与当前余额。
• 提示词长度由上游决定。 EasyAPI 本身不设硬性上限，超出模型限制时由上游拒绝。
• 任务只属于提交它的 Key。 用其他 Key 查询会返回 404。
• 下载链接会过期。 请在 expires_at 之前把文件保存到自己的存储。
• 价格不在本文列出。 视频的计价与时长、分辨率等有关，以模型广场的实时价格和任务返回的 billed_cost 为准。

如果只想控制成本做批量生成，目录里还有同系列的 seedance-2.0、seedance-2.0-fast 和 seedance-2.0-mini，后两者在目录描述中定位为更偏速度与成本的版本。

常见问题

Seedance 2.5 可以用 OpenAI SDK 的对话接口调用吗？

不可以。视频生成使用独立的 /v1/videos 异步任务接口，需要直接发 HTTP 请求。同步等待对话接口返回视频容易超时，这也是文档中明确不建议的做法。

生成一个视频要等多久？

没有固定时长，取决于模型、视频长度、分辨率和当时的排队情况。建议每隔几秒轮询一次状态，或者提交时填写 webhook_url，让任务完成后主动回调。

任务失败了会扣费吗？

文档说明的是「任务完成后按实际结果结算」，提交时的金额只是预扣。具体到某一个任务，请以查询结果中的 billed_cost 和 billing_status 以及控制台记录为准。

国内调用需要特殊网络环境吗？

接口域名是 token.easyapi.com，按普通 HTTPS 接口调用即可。API Key 应放在服务端，不要写进浏览器或移动端代码。

小结

调用 Seedance 2.5 的关键是按异步流程走：POST /v1/videos 提交、GET /v1/videos/{job_id} 轮询、用 download_url 下载。参数取值范围和价格以模型详情为准，完整字段说明见 EasyAPI 文档；其他可用模型见 一个 API Key 可以同时调用哪些国产大模型。