查询任务

火山官方格式

GET /api/v3/contents/generations/tasks/{task_id}
Authorization: Bearer <API_KEY>

任务状态：

状态	含义
queued	已进入队列
running	正在生成
succeeded	已成功，可读取视频地址
failed	生成失败，查看 error
cancelled	任务已取消
expired	任务已过期

成功响应遵循火山官方字段结构：

{
  "id": "task_xxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "draft": false,
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.png"
  },
  "seed": 89742,
  "resolution": "720p",
  "duration": 5,
  "priority": 0,
  "ratio": "16:9",
  "framespersecond": 24,
  "service_tier": "default",
  "generate_audio": true,
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  },
  "created_at": 1787535000,
  "updated_at": 1787535150
}

只有创建任务时启用 return_last_frame，成功结果才会包含 content.last_frame_url。queued 和 running 响应不保证提供 progress，请以 status 为准。

最终 Token 计费以 usage.completion_tokens 为优先依据；上游仅返回 total_tokens 时使用 total_tokens。

OpenAI 兼容格式

GET /v1/video/generations/{task_id}
Authorization: Bearer <API_KEY>

该接口返回与火山查询相同的 Seedance 任务对象，成功视频地址位于 content.video_url。

处理中与失败响应

处理中响应会返回任务元数据，但不包含成片和 Token 用量：

{
  "id": "task_xxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "running",
  "resolution": "720p",
  "duration": 5,
  "ratio": "adaptive",
  "created_at": 1787535000,
  "updated_at": 1787535010
}

失败响应通过 error 给出原因：

{
  "id": "task_xxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "failed",
  "error": {
    "code": "InvalidParameter",
    "message": "the request parameter is invalid",
    "type": "BadRequest"
  },
  "created_at": 1787535000,
  "updated_at": 1787535012
}

轮询建议

• 保存创建接口返回的任务 ID，不要保存或拼接上游任务地址。
• 建议从 3～5 秒轮询一次开始，随后逐步增加间隔。
• 只在 succeeded 后读取视频地址。
• 下载并持久化成片；临时视频 URL 可能过期。
• 对终态查询和回调处理实现幂等，避免重复记账或重复入库。