视频生成/Seedance / 查询任务

通过字节（Seedance）接口查询异步视频生成任务结果。

Seedance / 查询任务

本页用于查询已创建的字节（Seedance）视频生成任务。

调用面

项目值
Base URLhttps://video.unigateway.ai
鉴权Authorization: Bearer $UNIGATEWAY_API_KEY
主接口GET /api/v3/contents/generations/tasks/{id}

查询视频任务

  • 方法：GET
  • 路径：/api/v3/contents/generations/tasks/{id}

cURL 示例

curl "https://video.unigateway.ai/api/v3/contents/generations/tasks/media_task_8f3d0a" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

状态值

  • queued
  • running
  • succeeded
  • failed
  • expired
  • cancelled

响应示例（成功）

{
  "id": "media_task_8f3d0a",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://cdn.example.com/media/output/media_task_8f3d0a.mp4"
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "created_at": 1775344800,
  "updated_at": 1775344815,
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "error": null
}

响应示例（失败）

{
  "id": "media_task_8f3d0a",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "failed",
  "content": {},
  "usage": null,
  "created_at": 1775344800,
  "updated_at": 1775344810,
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Upstream task failed"
  }
}

轮询建议

  • 创建任务后先等待 2-3 秒再发起第一次查询。
  • 随着等待时长增长，逐步拉长轮询间隔，不要固定高频循环。
  • 在自己的任务系统里设置总超时，避免无限轮询。

终态处理

状态处理方式
succeeded持久化结果 URL、usage 和任务元数据。
failed查看 error.code 与 error.message，再决定是否创建新任务。
expired视为终态；只有业务仍需要结果时才重新提交。
cancelled视为终态，并排查任务被中断的原因。

说明

  1. 使用创建接口返回的准确任务 id 进行查询。
  2. queued 和 running 都应视为处理中。
  3. 在任务进入终态前，content.video_url 和 usage 可能为空。

常见失败场景

状态常见原因处理建议
404任务 ID 错误或调用面错误先核对 ID 和 Base URL
429轮询过于激进增加退避并减少并发轮询数
5xx网关或上游不稳定对同一任务 ID 做封顶退避重试