查询图像任务

查询已创建的异步图像生成任务状态与结果。

同步超时（408 generation_timeout）后，可使用返回的 task_id（或响应头 X-Xh-Image-Task-Id）继续轮询，也可保留 task_id 用于异步追溯。适用于统一契约生图与 Images 兼容入口。

创建图像见：创建图像（Images）、创建图像生成（chat）。

---

Endpoint

Method	URL
GET	{TRINITY_BASE_URL}/image/tasks/{taskId}

---

Base URL

项	值
Base URL	https://api.trinitydesk.ai/v1
协议	HTTPS

export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

---

Headers

Header	必填	说明
Authorization	是	Bearer <TRINITY_API_KEY>

---

路径参数

参数	类型	说明
taskId	string	创建响应中的 trinity_task.task_id，形如 imgtsk_xxx

---

请求示例

curl -sS "${TRINITY_BASE_URL}/image/tasks/imgtsk_abc123" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}"

---

返回字段

字段	类型	说明
task_id	string	任务 ID
status	string	任务状态（见下表）
model	string	模型 ID（终态后有值）
result_url	string	图片结果 URL（status=succeeded 时有值）
error_code	string	错误码（status=failed 时有值）
error_message	string	错误描述（status=failed 时有值）

任务状态

status	说明
pending	排队中
running	生成中
succeeded	生成成功，可读取 result_url
failed	生成失败，可读取 error_code / error_message
timed_out	上游处理超时

---

返回示例

生成中

{
  "task_id": "imgtsk_abc123",
  "status": "running",
  "model": "GG-2.5"
}

生成成功

{
  "task_id": "imgtsk_abc123",
  "status": "succeeded",
  "model": "GG-2.5",
  "result_url": "https://..."
}

生成失败

{
  "task_id": "imgtsk_abc123",
  "status": "failed",
  "model": "GG-2.5",
  "error_code": "upstream_task_failed",
  "error_message": "..."
}

---

错误码

HTTP	code	说明
400	invalid_request	任务 ID 格式错误
401	authentication_error	API Key 缺失或无效
404	—	任务不存在或无权限访问
429	rate_limit_exceeded	速率限制

完整错误码见 错误与调试。

---

Python 示例

import os
import requests

r = requests.get(
    f"{os.environ['TRINITY_BASE_URL']}/image/tasks/imgtsk_abc123",
    headers={"Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
result = r.json()
print(f"Status: {result.get('status')}")
if result.get("status") == "succeeded":
    print(f"Image URL: {result.get('result_url')}")
elif result.get("status") == "failed":
    print(f"Error: {result.get('error_code')} - {result.get('error_message')}")

---

相关

• 创建图像生成
• 图像生成 · 高级参数
• 查询视频任务
• 错误与调试