跳到主要内容

任务结果查询接口（预览）

提示

当前接口处于预览状态，未来可能会有所调整，请以实际状态为准。

1. 接口介绍​

查询 7 天内的内容生成异步任务状态及结果，可用于轮询任务结果。通常任务有如下几种状态：

  • 正在排队等待处理：待处理任务数量超出上限，排队等待处理
  • 正在处理：任务正在被处理
  • 处理成功：任务处理成功，已有生成结果
  • 处理失败：任务处理失败
  • 已取消：任务被客户取消
  • 已过期：任务结果已过期

2. 请求​

2.1 请求地址​

区域请求地址
国内http://stage.api.open.tuputech.com/<version>/generation/result/<secretId>
提示

<secretId> 需替换为您的应用 SID，请联系客户经理为您开通及配置。关于 SID 详见 常见问题（FAQ）。

2.2 请求方法​

POST

2.3 请求头​

请求头名称取值是否必需示例说明
Content-Typeapplication/json是Content-Type: application/json请求数据类型为 JSON
X-API-Key<API Key>是X-API-Key: <API Key>API Key 用于接口鉴权。请访问控制台 - 数字证书 获取 API Key

2.4 超时时间及异常处理​

  • 建议配置超时时间 1 秒，在 HTTP 响应状态码非 200 或业务状态码为 100/101 （服务错误）时立即进行重试；
  • 在业务状态码为 30/31 （正在排队或正在处理）时，间隔若干时间（取决于应用 QPS 及任务规模）进行重试；
  • 在业务状态码为 29/32/33 （任务已过期、取消或失败）时立即返回

2.5 请求参数说明 🔥​

参数名称类型是否必填说明
requestIdString是任务 ID

2.6 请求示例​

{
  "requestId": "<requestId>"
}

3. 同步响应​

3.1 响应参数说明 🔥🔥​

v3.1 说明

由于历史原因，在 v3.1 版本接口中，同步响应与回调请求的核心内容会先经过转义处理，最终以 json 字段（字符串类型）返回。因此，在解析该接口的业务数据时，需对 json 字段的取值额外执行一次转义还原逻辑，才能获取到原始的业务数据。除此之外，v3.1 与 v4 版本接口出入参数完全一致，相比之下 v4 版本接口更为直观。详见下方字段说明。


参数名称类型说明
signatureString

同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过 图普公钥 进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：

  1. 取 json 字段内容为 SignString；
  2. 将 signature 字段内容进行 Base64 解码，得到 RawSignature；
  3. 使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString
jsonString

同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。

  • 字段内容示例：{\"code\":0, \"message\":\"success\"}；
  • 字段详见下述 JSON 参数说明；
  • 为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

参数名称类型是否必有说明
codeInt是状态码，详见 业务状态码 。可能的返回值包括：

0：任务处理完成
29：任务不存在，或已过期失效
30：任务正在排队等待处理
31：任务正在处理
32：任务已被取消
33：任务处理失败
100/101：服务错误
messageString是状态信息
requestIdString是任务 ID
imagesArray<GenerationOutput>否生成的图片列表，详见 GenerationOutput 参数说明
videosArray<GenerationOutput>否生成的视频列表，详见 GenerationOutput 参数说明
customInfoObject<String, Any>否透传的自定义信息，请求参数中的 customInfo
nonceFloat是随机数（建议使用 Unix 时间戳或若干位随机整数）
timestampInt是当前服务器的 Unix 时间戳

GenerationOutput 参数说明​

参数名称类型是否必有说明
urlString是生成图片/视频时，生成的图片或视频内容 URL（有效期为 7 天）
durationNumber否生成视频时，生成的视频内容时长（单位：秒）

3.2 响应示例​

{
  "code": 0,
  "requestId": "<requestId>",
  "images": [
    {
      "url": "<url>"
    }
  ],
  "videos": [
    {
      "url": "<url>",
      "duration": 10
    }
  ],
  "customInfo": {
    "<key>": "<value>"
  },
  "timestamp": 1685000000,
  "nonce": 1685000000
}

4. 更新日志​

日期说明
2025-12-10调整 v4 与 v3.1 版本接口说明
2025-11-26新增内容生成任务结果查询文档页