视频/查询任务

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

字节 Seedance / 查询任务

查询已创建的视频生成任务。

接口信息

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

查询请求

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

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

响应示例（成功）

{
  "id": "cgt-20260514135903-68khw",
  "model": "doubao-seedance-2.0-fast",
  "status": "succeeded",
  "content": {
    "video_url": "https://<your-cdn>/media/output/cgt-20260514135903-68khw.mp4"
  },
  "usage": {
    "billing_mode": "credits",
    "credits": 50
  }
}

响应示例（失败）

{
  "id": "cgt-20260514135903-68khw",
  "model": "doubao-seedance-2.0-fast",
  "status": "failed",
  "content": {},
  "usage": null,
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Upstream task failed"
  }
}

任务状态

状态含义操作
queued已接收，尚未处理继续轮询
running生成处理中继续轮询
succeeded结果已就绪保存 content.video_url
failed处理失败查看 error 字段，决定是否重新提交
expired任务或结果已过期需要时重新提交
cancelled任务已终止视为终态
approved_asset_required需要审核素材按业务流程处理
content_adjustment_required需要调整内容按业务流程处理

queued 和 running 都是处理中状态。在任务进入终态前，content.video_url 和 usage 可能为空。

轮询策略

  • 首次查询：创建后等待 2-3 秒
  • 处理中：随着等待时间增长，逐步拉长轮询间隔（3s -> 5s -> 10s -> 15s）
  • 总超时：在调用方设置最大等待时间，避免无限轮询
  • 不要对同一任务 ID 发起高频并发查询

查询任务列表

curl "https://video.unigateway.ai/api/v3/contents/generations/tasks?page_num=1&page_size=20" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"
  • 只返回最近 7 天的任务
  • page_num 默认 1，page_size 默认 20
  • page_num 和 page_size 当前最大值均为 500
  • 可选过滤：filter.status、filter.task_ids（可重复）、filter.model、filter.service_tier
  • filter.status 支持：queued、running、cancelled、succeeded、failed、expired、approved_asset_required、content_adjustment_required

响应：

{
  "total": 1,
  "items": [
    {
      "id": "cgt-20260514135903-68khw",
      "status": "succeeded"
    }
  ]
}

删除任务

curl -X DELETE "https://video.unigateway.ai/api/v3/contents/generations/tasks/cgt-20260514135903-68khw" \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"
  • 排队中的任务会被取消，返回 {}
  • 运行中的任务不能删除
  • 已取消的任务不能再次删除
  • 已结束的任务删除返回 {}

常见失败场景

状态码原因处理
404任务 ID 错误或 Base URL 不正确核对任务 ID 和接口地址
429轮询过于频繁增加退避间隔，减少并发查询
5xx网关或上游服务异常对同一任务 ID 做封顶退避重试