​
Documentation Index

Fetch the complete documentation index at: https://docs.toapis.com/llms.txt Use this file to discover all available pages before exploring further.

​
获取图片任务状态

查询图片生成任务的状态和结果
  • 查询异步图片生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的图片
  • 支持多语言返回（zh/en/ko/ja）
所有图片生成任务都是异步执行的。提交任务后，您需要通过查询接口获取任务状态和结果。

​
创建任务时传入业务 ID

创建图片任务时，可以在请求体顶层传入 client_business_id。该字段用于保存您系统内的订单号、流水号或业务任务 ID，方便后续按业务 ID 查询生成结果。 
{
  "model": "gpt-4o-image",
  "client_business_id": "order_20260428_001",
  "prompt": "一只可爱的熊猫",
  "size": "1:1",
  "n": 1
}
也兼容放在 metadata.client_business_id 中，但推荐使用顶层字段。

​
Authorizations

​
Authorization
string
required
所有接口均需要使用 Bearer Token 进行认证获取 API Key：访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加：
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
task_id
string
required
图片生成 API 返回的任务 ID。也可以传创建任务时提交的 client_business_id，用于按客户侧业务 ID 查询任务状态和结果。
如果创建图片任务时传入 client_business_id，可直接使用同一个状态查询接口： GET /v1/images/generations/{client_business_id}。业务 ID 会限定在当前 API Key 所属用户下查询。
curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'

{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1768381010
}

​
Response

​
id
string
任务唯一标识符
​
client_business_id
string
客户侧业务 ID。仅当创建任务时传入 client_business_id 时返回。
​
object
string
对象类型，固定为 generation.task
​
model
string
使用的图片生成模型
​
status
string
任务状态
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
​
progress
integer
任务进度百分比（0-100）
​
created_at
integer
任务创建时间（Unix 时间戳）
​
completed_at
integer
任务完成时间（Unix 时间戳，仅完成时返回）
​
expires_at
integer
图片 URL 过期时间（Unix 时间戳，仅完成时返回）
​
result
object
任务结果（仅成功时返回）
​
error
object
错误信息（仅失败时返回）

​
任务状态说明

状态说明是否终态建议操作
queued任务排队等待处理❌等待 2-3 秒后重试查询
in_progress任务正在处理中❌等待 3-5 秒后重试查询
completed任务成功完成✅从 result.data[0].url 获取图片
failed任务处理失败✅检查 error 信息

​
轮询策略建议

初始等待: 2 秒
轮询间隔: 3 秒
最大等待: 120 秒
典型耗时: 5-30 秒

​
Python 轮询示例

import time
import requests

def poll_image_task(task_id, api_key, max_wait=120):
    """轮询图片生成任务直到完成或超时"""
    start_time = time.time()
    interval = 3  # 3秒间隔
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f'https://toapis.com/v1/images/generations/{task_id}',
            headers={'Authorization': f'Bearer {api_key}'}
        )
        data = response.json()
        
        if data['status'] == 'completed':
            return data['url']
        elif data['status'] == 'failed':
            raise Exception(f"生成失败: {data['error']['message']}")
        
        time.sleep(interval)
    
    raise TimeoutError("任务超时")

​
图片资源有效期

生成的图片 URL 有效期为 24 小时
  • 请在有效期内下载保存图片
  • expires_at 字段标识图片过期时间（Unix 时间戳）
  • 图片过期后无法访问，如需重新获取，需要重新提交生成任务

​
常见错误

错误码错误类型说明
400invalid_request请求参数无效
401unauthorized认证失败，检查 API Key
402insufficient_quota余额不足
404task_not_found任务不存在
422content_policy_violation内容违规
429rate_limit_exceeded请求频率超限
500internal_error服务器内部错误