Skip to main content
GET
/
v1
/
jobs
/
recordInfo
获取任务详情
curl --request GET \
  --url https://api.example.com/v1/jobs/recordInfo
{
  "code": 123,
  "msg": "<string>",
  "data": {
    "taskId": "<string>",
    "state": "<string>",
    "progress": 123,
    "resultJson": "<string>",
    "failCode": 123,
    "failMsg": "<string>"
  }
}

​
概述

使用此端点查询通过 API 创建的任何异步任务的状态和结果。这是一个统一的查询接口，适用于所有异步模型（图像生成、视频生成等）。

​
请求参数

​
taskId
string
required
任务 ID，创建任务时返回的唯一标识符

​
请求示例

curl -X GET "https://your-api-domain.com/v1/jobs/recordInfo?taskId=task_z-image_1765174270120" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
响应示例

​
任务进行中

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_z-image_1765174270120",
    "state": "generating",
    "progress": 50
  }
}

​
任务成功

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_z-image_1765174270120",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://cdn.example.com/generated/image1.png\"]}"
  }
}

​
任务失败

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_z-image_1765174270120",
    "state": "fail",
    "failCode": 501,
    "failMsg": "生成失败：内容不符合安全规范"
  }
}

​
任务状态说明

状态描述操作建议
waiting任务已排队等待处理继续轮询
queuing任务在处理队列中继续轮询
generating任务正在处理中继续轮询
success任务成功完成解析 resultJson 获取结果
fail任务失败查看 failCode 和 failMsg 了解详情

​
响应字段

​
code
integer
响应状态码，200 表示请求成功
​
msg
string
响应消息
​
data
object

​
错误码说明

错误码描述解决方案
401未授权 - API 密钥无效或缺失检查您的 API 密钥
404未找到任务验证 taskId 是否正确
422原始请求中的验证错误查看 failMsg 了解详情
500内部服务器错误几分钟后重试
501生成失败查看 failMsg 了解具体错误详情

​
轮询最佳实践

推荐轮询策略： - 初始间隔：2-3 秒 - 最大间隔：10 秒 - 最大尝试次数：60 次（约 5 分钟） - 使用指数退避策略减少请求频率

​
完整轮询示例

import requests
import time
import json

def poll_task_status(task_id, max_attempts=60, interval=3):
    """轮询任务状态直到完成或失败"""

    for attempt in range(max_attempts):
        response = requests.get(
            "https://your-api-domain.com/v1/jobs/recordInfo",
            params={"taskId": task_id},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )

        result = response.json()
        data = result.get("data", {})
        state = data.get("state")

        print(f"尝试 {attempt + 1}: 状态 = {state}")

        if state == "success":
            result_json = json.loads(data.get("resultJson", "{}"))
            print("✅ 任务完成!")
            print("结果:", result_json.get("resultUrls"))
            return result_json

        if state == "fail":
            fail_msg = data.get("failMsg", "未知错误")
            print(f"❌ 任务失败: {fail_msg}")
            raise Exception(fail_msg)

        # 仍在处理中，等待下次轮询
        time.sleep(interval)

    raise Exception("任务在最大尝试次数后超时")

# 使用示例
try:
    results = poll_task_status("task_z-image_1765174270120")
    print("生成的内容 URL:", results.get("resultUrls"))
except Exception as e:
    print(f"错误: {e}")
生产环境建议：在生产环境中，建议使用回调通知（callBackUrl）而非轮询，以减少 API 请求次数并获得更及时的结果通知。