跳转到主要内容
GET
https://toapis.com
/
v1
/
images
/
generations
/
{task_id}
curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'

{
  "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
  "object": "image.generation",
  "status": "in_progress",
  "model": "gpt-4o-image",
  "created_at": 1735516800
}
  • 查询异步图片生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的图片
  • 支持多语言返回（zh/en/ko/ja）
所有图片生成任务都是异步执行的。提交任务后，您需要通过查询接口获取任务状态和结果。

​
Authorizations

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

​
Path Parameters

​
task_id
string
必填
图片生成 API 返回的任务 ID
curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'

{
  "id": "task_01KA040M0HP1GJWBJYZMKX1XS1",
  "object": "image.generation",
  "status": "in_progress",
  "model": "gpt-4o-image",
  "created_at": 1735516800
}

​
Response

​
id
string
任务唯一标识符
​
object
string
对象类型，固定为 image.generation
​
status
string
任务状态
  • submitted - 已提交，等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
​
model
string
使用的图片生成模型
​
created_at
integer
任务创建时间（Unix 时间戳）
​
completed_at
integer
任务完成时间（Unix 时间戳，仅完成时返回）
​
url
string
生成的图片 URL（仅成功时返回）
​
revised_prompt
string
优化后的提示词（部分模型支持）
​
expires_at
integer
图片 URL 过期时间（Unix 时间戳）
​
error
object
错误信息（仅失败时返回）

​
任务状态说明

状态说明是否终态建议操作
submitted任务已提交，等待处理❌等待 2-3 秒后重试查询
in_progress任务正在处理中❌等待 3-5 秒后重试查询
completed任务成功完成✅获取 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服务器内部错误