ToAPIsToAPIs
獲取圖片任務狀態

獲取圖片任務狀態

查詢圖片生成任務的狀態和結果

GET
/v1/images/generations/{task_id}

中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址(Base URL)。文檔示例中的 https://toapis.com 請替換為 https://toapis.cn。

  • 查詢異步圖片生成任務的執行狀態和結果
  • 實時狀態更新和進度跟蹤
  • 任務完成時獲取生成的圖片
  • 支持多語言返回(zh/en/ko/ja)

所有圖片生成任務都是異步執行的。提交任務後,您需要通過查詢接口獲取任務狀態和結果。

一般圖片和影片任務也可透過 GET /v1/tasks/{task_id} 查詢, usage 和 billing 採用相同口徑. 本頁描述的是頁首生成任務查詢路徑的回應.

以下範例用於展示欄位, 不代表模型目前的價格或固定計費方式. 實際欄位與金額以本次任務回傳為準.

創建任務時傳入業務 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

Authorizationstring請求頭必填

所有接口均需要使用 Bearer Token 進行認證

獲取 API Key:

訪問 API Key 管理頁面 獲取您的 API Key

使用時在請求頭中添加:

Authorization: Bearer YOUR_API_KEY

Path Parameters

task_idstring路徑必填

圖片生成 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>'
import requests
import time

API_BASE = 'https://toapis.com'
API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

def get_image_status(task_id):
    response = requests.get(f'{API_BASE}/v1/images/generations/{task_id}', headers=headers)
    return response.json()

def wait_for_image(task_id, max_attempts=60, interval=3):
    for _ in range(max_attempts):
        result = get_image_status(task_id)
        status = result.get('status')

        print(f"狀態: {status}")

        if status == 'completed':
            return result
        elif status == 'failed':
            raise Exception(f"任務失敗: {result}")

        time.sleep(interval)

    raise Exception("任務超時")

# 使用示例
task_id = "task_01KA040M0HP1GJWBJYZMKX1XS1"
result = wait_for_image(task_id)
print(f"圖片URL: {result['url']}")
const API_BASE = 'https://toapis.com';
const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

async function getImageStatus(taskId) {
  const response = await fetch(`${API_BASE}/v1/images/generations/${taskId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  return response.json();
}

async function waitForImage(taskId, maxAttempts = 60, interval = 3000) {
  for (let i = 0; i < maxAttempts; i++) {
    const result = await getImageStatus(taskId);
    const status = result.status;

    console.log(`狀態: ${status}`);

    if (status === 'completed') {
      return result;
    } else if (status === 'failed') {
      throw new Error(`任務失敗: ${JSON.stringify(result)}`);
    }

    await new Promise(r => setTimeout(r, interval));
  }

  throw new Error('任務超時');
}

// 使用示例
const taskId = 'task_01KA040M0HP1GJWBJYZMKX1XS1';
waitForImage(taskId).then(result => {
  console.log('圖片URL:', result.url);
});
package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "time"
)

func getImageStatus(taskId string) (map[string]interface{}, error) {
    url := fmt.Sprintf("https://toapis.com/v1/images/generations/%s", taskId)

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer <token>")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var result map[string]interface{}
    json.Unmarshal(body, &result)

    return result, nil
}

func main() {
    taskId := "task_01KA040M0HP1GJWBJYZMKX1XS1"

    for i := 0; i < 60; i++ {
        result, _ := getImageStatus(taskId)
        status := result["status"].(string)

        fmt.Printf("狀態: %s\n", status)

        if status == "completed" {
            fmt.Println("圖片生成完成!")
            fmt.Println("圖片URL:", result["url"])
            break
        }

        time.Sleep(3 * time.Second)
    }
}

響應示例

{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1768381010,
  "billing": {
    "status": "pending"
  }
}
{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "client_business_id": "order_20260428_001",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1768381010,
  "finished_at": 1768381063,
  "completed_at": 1768381063,
  "expires_at": 1770973063,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/generated/1768381061_c55c1bbb.jpg"
      }
    ]
  },
  "usage": {
    "charge_type": "per_request",
    "requests": 1
  },
  "billing": {
    "status": "settled",
    "credits": "100",
    "cost_usd": "0.5"
  }
}
{
  "id": "img_73c450923a9a43e4aabf426e1c681d64",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "failed",
  "progress": 0,
  "created_at": 1768215312,
  "billing": {
    "status": "refunded",
    "credits": "0",
    "cost_usd": "0"
  },
  "error": {
    "code": "generation_failed",
    "message": "call upstream API failed: upstream returned status 422"
  }
}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "gpt-image-2.5-flare-official",
  "status": "completed",
  "progress": 100,
  "created_at": 1789099098,
  "finished_at": 1789099158,
  "completed_at": 1789099158,
  "expires_at": 1791691158,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/generated/example.png"
      }
    ]
  },
  "usage": {
    "charge_type": "per_token",
    "billed_tokens": 1000,
    "input_tokens": 100,
    "output_tokens": 900,
    "total_tokens": 1000,
    "input_tokens_details": {
      "text_tokens": 20,
      "image_tokens": 80,
      "cached_tokens": 30,
      "cached_tokens_details": {
        "text_tokens": 10,
        "image_tokens": 20
      }
    },
    "output_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 900
    }
  },
  "billing": {
    "status": "settled",
    "credits": "10",
    "cost_usd": "0.05"
  }
}
{
  "error": {
    "code": 404,
    "message": "任務不存在",
    "type": "not_found_error"
  }
}
{
  "error": {
    "code": 401,
    "message": "身份驗證失敗,請檢查您的API密鑰",
    "type": "authentication_error"
  }
}

Response

idstring

任務唯一標識符

client_business_idstring

客戶側業務 ID。僅當創建任務時傳入 client_business_id 時返回。

objectstring

對象類型,固定爲 generation.task

modelstring

使用的圖片生成模型

statusstring

任務狀態

  • queued - 排隊等待處理
  • in_progress - 處理中
  • completed - 成功完成
  • failed - 失敗
progressinteger

任務進度百分比(0-100)

created_atinteger

任務創建時間(Unix 時間戳)

finished_atinteger

任務結束時間, Unix 時間戳. 本頁查詢路徑在任務成功或失敗且已儲存結束時間時回傳.

completed_atinteger

任務完成時間(Unix 時間戳,僅完成時返回)

expires_atinteger

圖片 URL 過期時間(Unix 時間戳,僅完成時返回)

resultobject

任務結果(僅成功時返回)

屬性
typestring

結果類型,固定爲 image

dataarray

圖片數據數組

數組元素
urlstring

生成的圖片 URL

result.data[].backgroundstring

上游提供時回傳實際背景類型: opaque 或 transparent. 圖層拆分的底圖為 opaque, 其餘圖層為 transparent. 舊工作或其他未提供此資訊的模型會省略此欄位.

billingobject

選填的圖片任務計費資訊. 計費狀態獨立於生成狀態, completed 不保證已經結算. 無法確認計費資料時會省略整個 billing, 不回傳 null, 也不代表免費.

屬性
statusstring

pending 表示待結算或退款尚未確認, 省略金額. settled 表示已確認最終結算. refunded 表示已退款或失敗任務已確認無淨扣款, 包括失敗前未扣款的情況.

creditsstring

平台實際向客戶收取的點數, 使用十進位字串. 僅在 settled 或 refunded 時回傳.

cost_usdstring

平台實際向客戶收取的美元金額, 使用十進位字串. 已包含任務計費時採用的折扣和倍率, 不代表供應商成本.

usageobject

可選的計費量, 圖片 token 明細及工具次數. charge_type, requests, billed_tokens 等欄位見任務用量欄位. 圖片 token 明細僅在 billing.status 為 settled, 且儲存的用量有效並與最終扣費一致時回傳. 無法確認的部分省略, 已確認金額和圖片結果仍可正常回傳.

欄位類型說明
input_tokensinteger輸入 token 總數, 包含文字和圖片
output_tokensinteger輸出 token 總數
total_tokensintegerinput_tokens + output_tokens
input_tokens_details.text_tokensinteger文字輸入 token 數
input_tokens_details.image_tokensinteger圖片輸入 token 數
input_tokens_details.cached_tokensinteger已快取的輸入 token 數, 已包含在輸入總數中
input_tokens_details.cached_tokens_details.text_tokensinteger已快取的文字輸入 token 數
input_tokens_details.cached_tokens_details.image_tokensinteger已快取的圖片輸入 token 數
output_tokens_details.text_tokensinteger文字輸出 token 數, 僅在有輸出明細時回傳
output_tokens_details.image_tokensinteger圖片輸出 token 數, 僅在有輸出明細時回傳
output_tokens_details.text_or_reasoning_tokensinteger文字與思考同價且未細分的輸出 token 數, 不計入 text_tokens, 僅在存在時回傳
charge_typestring計費方式: per_request 按次, per_token 按 token
requestsinteger計費次數, per_request 時回傳. 請求中的 n 不直接乘算次數
billed_tokensinteger計價 token 數, per_token 時回傳
input_imagesinteger扣除免費額度後參與計費的輸入圖片數, 為零時省略
tool_usage.web_search, tool_usage.image_search, tool_usage.grounding_queriesinteger聯網搜尋, 圖片搜尋和 Grounding 查詢次數, 依實際發生回傳

charge_type, requests, billed_tokens 和 input_images 是計費量, 只與 billing.status=settled 同時回傳. 提交時一次扣清的按次任務同樣回傳 settled 和實際金額. 所有 token 數均為非負 JSON 整數. 快取 token 是輸入 token 的子集, 不能重複相加. output_tokens_details 在未提供明細時整體省略. usage.tool_usage.web_search 可獨立回傳, 也可與圖片 token 並存.

errorobject

錯誤信息(僅失敗時返回)

屬性
codestring

錯誤代碼

messagestring

錯誤描述

計費狀態與費用統計

上述計費規則適用於圖片任務查詢, 不限制模型或管道. GPT-Image-2.5 的 Sunburst 和 Flare VIP / Official 型號已支援 token 用量, 其他模型是否回傳取決於既有結算資料. 範例金額僅用於說明回應格式, 不是固定單價.

billing.status意義金額與圖片 token
pending生成中, 待結算, 或退款尚未確認省略金額和圖片 token; 預扣不代表最終費用
settled已確認最終結算回傳金額, 有有效用量時回傳圖片 token; 免費任務金額也可為 "0"
refunded已退款或失敗後已確認無淨扣款credits 和 cost_usd 均為 "0", 省略圖片 token
  • 金額來自任務已確認的最終扣款, 查詢不會觸發扣款, 補扣或退款, 也不會按最新模型價格重新計算. 統計時直接使用回傳金額, 不要用 token 乘目前單價替代.
  • 依任務 id 去除重複紀錄並更新金額, 不要累加每次輪詢的回傳值. 使用十進位計算; pending 或欄位缺少不能視為零費用.
  • 金額使用十進位字串, 不保證固定小數位數.
  • 計費紀錄缺少或不一致時可能省略 billing. 圖片尚無法交付而暫時顯示為 in_progress 時, 也可能同時省略 billing 和 usage.
  • 成功 Webhook 的 data.usage 和 data.billing 與此介面使用同一確認條件和欄位取值. Webhook 是事件建立時的快照, 欄位缺少時可查詢此介面作為後備. 詳見價格與實際費用.

任務狀態說明

狀態說明是否終態建議操作
queued任務排隊等待處理❌等待至少 5-10 秒並加入抖動後查詢
in_progress任務正在處理中❌等待至少 5-10 秒並加入抖動後查詢
completed任務成功完成✅從 result.data[0].url 獲取圖片
failed任務處理失敗✅檢查 error 信息

輪詢策略建議

初始等待: 5 秒
輪詢間隔: 至少 5-10 秒並加入隨機抖動
最大等待: 120 秒
典型耗時: 5-30 秒

Python 輪詢示例

import time
import random
import requests

def poll_image_task(task_id, api_key, max_wait=120):
    """輪詢圖片生成任務直到完成或超時"""
    start_time = time.time()
    interval = 5

    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}'}
        )
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', interval))
            time.sleep(retry_after + random.uniform(0, 1))
            interval = min(interval * 2, 60)
            continue
        response.raise_for_status()
        data = response.json()

        if data['status'] == 'completed':
            return data['url']
        elif data['status'] == 'failed':
            raise Exception(f"生成失敗: {data['error']['message']}")

        time.sleep(interval + random.uniform(0, 1))

    raise TimeoutError("任務超時")

圖片資源有效期

生成的圖片保留 30 天

  • 請在有效期內下載保存圖片
  • expires_at 字段標識圖片過期時間(Unix 時間戳)
  • 圖片過期後無法訪問,如需重新獲取,需要重新提交生成任務

錯誤碼與失敗原因

請求錯誤與任務失敗的差異, 具體原因及處理方式, 請見錯誤碼速查. 查詢成功仍需檢查任務狀態, HTTP 狀態不是業務錯誤碼.

ToAPIs 支持統一 任務 Webhook。回調為主、輪詢後備;至少 5~10 秒並加入抖動,429 讀取 Retry-After。批次最多 100 個任務,詳見 限流。