视频/字节 Seedance / 查询任务

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

字节 Seedance / 查询任务

查询 Seedance 任务状态、结果、用量和任务历史。

查询单个任务

项目值
方法GET
路径/api/v3/contents/generations/tasks/{id}
Base URLhttps://api.unigateway.ai
鉴权Authorization: Bearer $UNIGATEWAY_API_KEY

将 {id} 替换为创建接口返回的任务 ID：

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

执行中响应：

{
  "id": "task_123456",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "running",
  "usage": {
    "billing_mode": "quota",
    "charged_quota": 875000
  },
  "created_at": 1781255171,
  "updated_at": 1781255181,
  "progress": "50%",
  "service_tier": "default",
  "generate_audio": false,
  "content": {},
  "error": null
}

完成响应：

{
  "id": "task_123456",
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://video.demo.url"
  },
  "usage": {
    "billing_mode": "token",
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "created_at": 1781255171,
  "updated_at": 1781255427,
  "completed_at": 1781255427,
  "progress": "100%",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "service_tier": "default",
  "generate_audio": false,
  "error": null
}

失败响应：

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

响应字段

字段说明
id任务 ID
model请求使用的模型 ID
status原始任务状态
content.video_url任务成功后的生成视频 URL
usage可用时返回用量对象
created_at / updated_at / completed_at可用时返回秒级 Unix 时间戳
progress可用时返回进度字符串
ratio / duration / resolution / generate_audio / service_tier可用时回显请求参数
error失败任务的错误对象；无错误时为 null
presentation_status / presentation_reason可用时返回审核相关展示状态

usage 取决于供应商和计费方式，可能包含 completion_tokens、total_tokens、request_count、duration_seconds、total_duration_seconds、size_multiplier、billing_units、credits、charged_quota 或 billing_mode。

任务状态

状态含义处理
queued已接收，等待处理继续轮询
running正在生成继续轮询
succeeded结果已就绪保存 content.video_url
failed处理失败查看 error，决定是否重试
expired任务或结果已过期需要时重新提交
cancelled任务已取消视为终态
approved_asset_required需要素材审核审核或替换引用素材
content_adjustment_required需要调整内容修改提示词或输入媒体

任务进入终态前，content.video_url 可能为空，usage 也可能为空或不完整。

轮询策略

  • 首次查询：创建任务后等待 2 到 3 秒
  • 处理中逐步拉长间隔，例如 3s、5s、10s、15s
  • 调用方设置总超时
  • 不要对同一个任务 ID 高频并发查询

查询任务列表

项目值
方法GET
路径/api/v3/contents/generations/tasks
Base URLhttps://api.unigateway.ai
curl -sS "https://api.unigateway.ai/api/v3/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

查询参数：

参数必填说明
page_num否默认 1，最大 500
page_size否默认 20，最大 500
filter.status否queued、running、cancelled、succeeded、failed、expired、approved_asset_required、content_adjustment_required
filter.task_ids否可重复传入，用于按多个任务 ID 过滤
filter.model否按模型 ID 过滤
filter.service_tier否按请求服务档位过滤

响应：

{
  "total": 1,
  "items": [
    {
      "id": "task_123456",
      "status": "succeeded",
      "model": "doubao-seedance-2-0-fast-260128",
      "created_at": 1781255171,
      "updated_at": 1781255427,
      "content": {
        "video_url": "https://video.demo.url"
      }
    }
  ]
}

删除任务

项目值
方法DELETE
路径/api/v3/contents/generations/tasks/{id}
Base URLhttps://api.unigateway.ai
curl -sS -X DELETE "https://api.unigateway.ai/api/v3/contents/generations/tasks/task_123456" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

删除行为：

  • 排队中的任务会被取消并返回 {}
  • 运行中的任务不能删除
  • 已取消任务不能再次删除
  • 已完成或失败任务删除成功时返回 {}
  • 删除任务后不要依赖继续查询该任务

常见失败

状态码原因处理
400状态过滤、分页参数或删除状态不合法修正参数或任务状态
401 / 403API Key 无效或权限不足检查 API Key 和账号权限
404任务 ID 不存在确认任务 ID 和账号
429轮询过于频繁增加退避间隔，减少并发查询
5xx网关或上游供应商异常使用封顶退避重试