跳转到主要内容
GET
查询任务状态

任务状态与延期提示

只按 status 判断任务是否结束。 progress=100 或 error 非空都不表示任务已经结束。 适用的视频、图片、音频和文档异步任务已经提交、处理超过 30 分钟且仍未结束时,会在现有 error 字段返回 code=task_delayed、type=task_status。提示写明本任务的实际处理期限;不同任务的期限可能不同,不要把示例中的 2 小时作为固定值。 例如,本次处理期限为 2 小时,且预扣额度尚未退回:
已经超过处理期限、但系统尚未将任务结束时,status 仍为 processing,提示会改为等待系统按超时失败处理。这不表示已经退款,请继续查询。 上述 Gateway 视频、图片、音频和文档任务的退款说明只描述本任务的预扣额度:未预扣时说明无需退款;确认预扣已退回后才说明已退回,不再承诺重复退还。失败任务的退款说明追加在 error.message 中,保留原有公共 error.code 和 error.type。usage.credits_reserved 记录原有预扣额度,退款后仍可为正数,不能用它判断是否未退款。 延期提示本身不修改任务状态或执行退款。sync_upstream=true 仍可按接口说明主动刷新一次任务状态。错误码含义见错误码参考。

results 字段格式说明

任务完成(status=completed)后,results 是一个数组,结构按模型不同而异。解析结果前请先根据响应中的 model 字段判定结构类型。

通用格式(大多数模型)

按任务输出类型(type)分组:
上表通用格式的 url 有效期为 24 小时,请尽快保存。特殊格式的链接保留期如有差异,以对应模型说明为准。

特殊格式(按 model 区分)

以下模型的 results[i] 结构不遵循上表通用格式。调用方必须按 model 单独处理。

GPT Image 2.5 生成元数据

image_metadata 保存图片自身的字段,例如 generation_id、model、size。response_metadata 保存一次生成响应的公共字段,例如 created、background、output_format、quality、size;多张结果中的这部分信息来自同一次请求,不能视作每张图的独立用量。未列举的生成元数据也会保留,调用方应允许新增字段。 下面是结构示例,files.example.com 代表系统返回的文件地址,不是可下载的实测链接:
两款 2.5 的新任务按文字输入总量、图片输入总量、图片输出和文字输出计费,不应用缓存折扣,具体费率见模型说明。缓存统计未报告时保留为未知,不影响按四类总量结算;这些统计不会进入图片结果。 两款 2.5 必须先将图片保存到本系统,才会发布成功结果;元数据中的重复图片地址也会替换为本系统地址。图片结果不包含生成服务的原始图片地址或 usage。这些图片的保留期由本系统文件存储策略决定,请在任务完成后及时下载保存。

档案创建类(不返回媒体 URL)

声音克隆类

语音转写类(不返回媒体 URL)

视频带种子值

seed 字段始终存在:当生成过程回传了种子时为对应整数;若本次生成未回传种子,则为 null。请按「字段始终存在、值可能为 null」处理。

Seedance 2.5(HongniaoAI)

其中 result.output.outputUrls、result.outputs、result.videoUrl、result.videoUrls、result.video_url、result.resultUrls 等字段来自上游任务响应;适配器会把这些字段保留在 results[i].result 中,并将可读取的字段展开到 results[i]。seconds 在鸿鸟任务响应中实测可能是字符串,即使提交请求使用的是整数;调用方应按实际 JSON 类型解析。expires_at、thumbnail_url 以及上游未来新增字段可能缺省,解析器应允许缺失和新增字段。

参考视频快速版降级提示(degraded_reason)

PBR 材质类(单任务返回多个带语义标签的结果)

音乐生成带歌词文本

文档转换类(结果为 ZIP 压缩包 URL,非媒体直链)

解析建议

  • 先读 model,再解析 results:同一 type 下不同 model 的结构可能完全不同
  • URL 类结果注意过期:通用格式的 url 有效期为 24 小时;GPT Image 2.5 按上文文件存储策略保留。业务侧应在收到结果后立即下载转存
  • 档案类任务返回的 voice_id / character_id / profile_id 是长期有效的资源标识,可直接用于后续任务参数

授权

Authorization
string
header
必填

所有接口均需要使用Bearer Token进行认证

使用时在请求头中添加:

Authorization: Bearer YOUR_API_KEY

路径参数

task_id
string
必填

任务ID,由提交任务接口返回

示例:

"task-unified-1757165031-uyujaw3d"

查询参数

sync_upstream
boolean
默认值:false

是否在返回前主动刷新一次任务状态。仅对仍在执行且已有关联远端任务的记录生效;否则直接返回当前任务状态。

示例:

true

响应

查询成功

id
string

任务ID

示例:

"task-unified-1757165031-uyujaw3d"

object
enum<string>

任务的具体类型

可用选项:
video.generation.task,
image.generation.task,
audio.generation.task,
llm.generation.task
示例:

"video.generation.task"

type
enum<string>

任务的输出类型

可用选项:
video,
image,
audio,
llm
示例:

"video"

model
string

实际使用的模型名称

示例:

"lipsync-2"

status
enum<string>

任务状态。仅以此字段判断任务是否结束;progress=100 或 error 非空不能代替状态判断。

可选值:

可用选项:
pending,
processing,
completed,
failed
示例:

"pending"

progress
integer

任务进度百分比

必填范围: 0 <= x <= 100
示例:

0

created
integer

任务创建时间戳(Unix 秒)

示例:

1757165031

results
object[] | null

任务结果列表,仅在 status=completed 时有值。

结构按任务输出类型(type)不同:

通用说明:

  • 结果中的 URL 有效期为 24 小时,请尽快保存
  • type=llm 的结果是对话响应,不产生 URL
  • 部分任务是"非媒体产物"(创建语音档案 / 角色档案等),results 不含 url 而是 id 类字段

图片结果(type=image)。多数图片模型只返回 url;少数模型(Patina 家族)会附带 content_type;PHOTA 创建档案类任务返回 {result_type, profile_id}(非图片产物)

error
object | null

失败信息或处理中任务的延期提示,可为空。status=failed 时返回安全错误说明;部分已提交的异步任务处理超过30分钟且仍为 processing 时,返回 code=task_delayed、type=task_status,并说明本任务的实际处理期限。超过期限但尚未终结时会提示等待系统处理,不代表已失败或已退款。延期提示中,未预扣额度时说明无需退款;已确认预扣退回时才说明已退回,不重复承诺退款。Gateway 视频、图片、音频和文档任务失败后的退款说明只追加到 message,保留原有公共 code/type;成功时为 null。是否结束始终以 status 为准。

usage
object | null

计费信息