TTokenPortal

端点参考 · 查询生成任务

文档状态已发布功能状态已上线最后更新：2026-09-21

1. 概述

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

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

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

2. 使用前提

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 }
  }
}
字段类型说明
idstring作业 ID，与创建时返回的一致。⛔ 不要从它里面解析时间或任何含义——它的形态由执行该任务的货源决定，平台**⛔ 保证**其规则与稳定性；要创建时刻请读下面的 created_at。
created_atinteger，可选作业创建时刻（Unix 秒，UTC）。⚠ 取不到时这个键不出现，⛔ 假设它恒在。
statusstring冻结的 5 态之一：queued / running / succeeded / failed / canceled。上游各种方言词汇都会被归一到这 5 个之一，客户端只需要处理这 5 种
outputarray | null非 succeeded 时恒为 null；成功且有产物时是数组。null 与 [] 含义不同：前者"还没有"，后者"有零个"——成功场景下只会看到 null 变成非空数组的过程，不会拿到一个 url 为空字符串的元素
output[].type / output[].urlstring产物类型（video 或 image）与下载地址
output[].rolestring，可选省略 = 主产物。目前唯一取值 last_frame：首帧生视频请求了 return_last_frame 时，数组会多出第二个元素（type=image），是这次生成的尾帧截图
usage.total_tokensinteger消耗计数，仅在有计数时非空；不代表计价档位，具体按哪一档计费请查用量查询
usage.tool_usageobject | null，可选目前只有联网搜索次数 web_search（integer）。null = 上游本次未回显该项，⛔ 不要理解成「用了 0 次」
errorobject | null非失败态恒为 null；失败/过期/取消时给出
error.reasonstring三个稳定取值之一：upstream_error（上游生成失败）/ upstream_expired（上游超时未完成）/ canceled（已取消）。请按这个字段分支，不要解析 message 文案
error.messagestring平台按 reason 写的固定人读句子，不含上游原始措辞，跨版本可能微调文案但不改变 reason 枚举
echoobject，可选仅在平台确实拿到额外可回显信息时才出现，整个对象可能不存在。里面分两类字段，各自独立可能缺失：生成参数回显（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 后尽快下载；超期后无法找回，但账单不会因此撤销
端点参考 · 查询生成任务 · TokenPortal