跳轉到主要內容
GET
/
v1
/
images
/
generations
/
{task_id}
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
}
  • 查詢異步圖片生成任務的執行狀態和結果
  • 實時狀態更新和進度跟蹤
  • 任務完成時獲取生成的圖片
  • 支持多語言返回（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
必填
所有接口均需要使用 Bearer Token 進行認證獲取 API Key：訪問 API Key 管理頁面 獲取您的 API Key使用時在請求頭中添加：
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
task_id
string
必填
圖片生成 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服務器內部錯誤