端点参考 · 查询生成任务
The guide below is in Chinese.
用创建任务时同一把 API Key 和响应里的 id 调用 GET /v1/contents/generations/tasks/{id}。请求无需请求体,可用同一个 id 重试查询。
查询状态并下载
Shell command
curl "https://staging-dp.taotoken.io/v1/contents/generations/tasks/TASK_ID" \
-H "Authorization: Bearer ${TP_API_KEY}"queued或running:任务还在运行,隔几秒继续查,可以逐渐加大间隔。succeeded:读取output[]中type为video的url,有下载地址时请及时保存。failed或canceled:停止轮询,根据error.reason排查。
火山兼容路径使用 content.video_url,请按火山兼容接口的响应读取结果。
响应字段
下面是 /v1 的统一响应示例,各字段是否返回见表格。
JSON
{
"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": "...",
"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,可选 | 目前只有联网搜索次数 web_search(integer)。字段缺失 = 上游本次未回显该项,⛔ 不要理解成「用了 0 次」 |
error | object | null | 非失败态恒为 null;失败/过期/取消时给出 |
error.reason | string | 稳定取值:upstream_error(上游生成失败)/ upstream_expired(上游超时未完成)/ upstream_task_unavailable(上游任务不存在或已超出查询窗口)/ 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)。对账四字段只在经过可核对的中间供应链环节时才出现,直连路径没有这类信息可回显不代表调用异常 |
失败、超时和有效期
| HTTP | 含义 | 处理 |
|---|---|---|
| 404 | 作业不存在,或不属于当前 Key | 核对 id 与所用的 Key 是否一致 |
| 5xx | 查询本身失败 | 可直接重试同一个 id,不会重新创建任务 |
完整错误码 → 错误码。
查询不会重新创建或再次计费。停止本地轮询后仍可用原 ID 继续查询,成功任务仍可计费。
任务查询窗口与视频链接有效期是两个限制,随实际供货协议而异。例如阿里百炼的 Wan / MiniMax H3 任务查询窗口为 24 小时;MiniMax H3 视频链接有效期为 30 天。平台不据此承诺统一保留期,请在 succeeded 后及时下载;链接失效不会撤销已产生的账单。参考MiniMax H3 上游说明