端点参考 · 查询生成任务

1. 概述

查询一个已创建的生成作业的状态与结果。轮询这个端点直到作业进入终态。

已经对接过火山方舟（字节）Seedance？本平台另有火山兼容路径 GET /api/v3/contents/generations/tasks/{id}：返回体包含火山方舟查询接口的全部字段（取不到时为 null），状态词与火山一致。详见《Seedance 系列模型接入指南》 §0a。本页描述的是 /v1 路径。


状态	已上线
计费	查询本身不计费。作业成功完成时按平台计费规则扣费一次——通常发生在你轮询到 `succeeded` 的那次请求；即便完全不轮询，平台也会在产物保留期到期前兜底补记这一次费用，不轮询不能省掉这笔钱，只会让你拿不到产物地址
重试	查询请求本身失败可以直接重试，不会重新创建任务

2. 使用前提

已用创建生成任务拿到作业 id

3. 鉴权与地址

GET https://intertoken.ai/v1/contents/generations/tasks/{id}
Authorization: Bearer sk-…

4. 请求

无请求体。{id} 是创建接口返回的作业 ID。

5. 响应

本端点的响应是平台归一化、稳定冻结的信封，与创建端点的透传响应形状不同——这一层字段不随供应商变化。

{
  "id": "cgt_xxx",
  "status": "succeeded",
  "output": [{ "type": "video", "url": "https://…/xxx.mp4" }],
  "usage": { "total_tokens": 50638, "tool_usage": { "web_search": 2 } },
  "error": null,
  "echo": {
    "seed": 12345,
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "output_format": "mp4",
    "model": "volcengine/doubao-seedance-2.0",
    "created_at": 1758000000,
    "updated_at": 1758000012,
    "draft_task_id": "draft_xxx",
    "upstream_task_id": "...",
    "upstream_url": "https://...",
    "upstream_model": "...",
    "upstream_usage": { "total_tokens": 50638 }
  }
}

字段	类型	说明
`id`	string	作业 ID，与创建时返回的一致。⛔ 不要从它里面解析时间或任何含义——它的形态由执行该任务的货源决定，平台⛔ 保证其规则与稳定性；要创建时刻请读下面的 `created_at`。
`created_at`	integer，可选	作业创建时刻（Unix 秒，UTC）。⚠ 取不到时这个键不出现，⛔ 假设它恒在。
`status`	string	冻结的 5 态之一：`queued` / `running` / `succeeded` / `failed` / `canceled`。上游各种方言词汇都会被归一到这 5 个之一，客户端只需要处理这 5 种
`output`	array \| null	非 `succeeded` 时恒为 `null`；成功且有产物时是数组。`null` 与 `[]` 含义不同：前者"还没有"，后者"有零个"——成功场景下只会看到 `null` 变成非空数组的过程，不会拿到一个 `url` 为空字符串的元素
`output[].type` / `output[].url`	string	产物类型（`video` 或 `image`）与下载地址
`output[].role`	string，可选	省略 = 主产物。目前唯一取值 `last_frame`：首帧生视频请求了 `return_last_frame` 时，数组会多出第二个元素（`type=image`），是这次生成的尾帧截图
`usage.total_tokens`	integer	消耗计数，仅在有计数时非空；不代表计价档位，具体按哪一档计费请查用量查询
`usage.tool_usage`	object \| null，可选	目前只有联网搜索次数 `web_search`（integer）。`null` = 上游本次未回显该项，⛔ 不要理解成「用了 0 次」
`error`	object \| null	非失败态恒为 `null`；失败/过期/取消时给出
`error.reason`	string	三个稳定取值之一：`upstream_error`（上游生成失败）/ `upstream_expired`（上游超时未完成）/ `canceled`（已取消）。请按这个字段分支，不要解析 `message` 文案
`error.message`	string	平台按 `reason` 写的固定人读句子，不含上游原始措辞，跨版本可能微调文案但不改变 `reason` 枚举
`echo`	object，可选	仅在平台确实拿到额外可回显信息时才出现，整个对象可能不存在。里面分两类字段，各自独立可能缺失：生成参数回显（`seed`/`duration`/`ratio`/`resolution`/`output_format`/`model`/`created_at`/`updated_at`/`draft_task_id`）与对账四字段（`upstream_task_id`/`upstream_url`/`upstream_model`/`upstream_usage`）。对账四字段只在经过可核对的中间供应链环节时才出现，直连路径没有这类信息可回显不代表调用异常

6. 示例

curl "https://intertoken.ai/v1/contents/generations/tasks/{TASK_ID}" \
  -H "Authorization: Bearer sk-你的密钥"

7. 错误

HTTP	含义	处理
404	作业不存在，或不属于当前 Key	核对 `id` 与所用的 Key 是否一致
5xx	查询本身失败	可直接重试同一个 `id`，不会重新创建任务

完整错误码 → 错误码。

8. 重试规则

情况	能否重试	说明
查询请求失败（网络错、5xx）	可以，直接重试同一个 `id`	查询不会重新创建任务
未到终态	继续轮询	建议间隔从几秒起步、指数退避，直至 `succeeded`/`failed`/`canceled`
本地停止等待（关窗口、Ctrl+C）	远端任务不会取消	之后用保存的 `id` 重新查询即可继续跟踪
产物已超过保留期	无法恢复	上游通常只保留任务产物 7 天，请在拿到 `succeeded` 后尽快下载；超期后无法找回，但账单不会因此撤销