> ## 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.

# 獲取圖片任務狀態

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

> [!NOTE]
>
> **中國大陸用戶請注意：** 中國大陸用戶請使用 `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 查詢生成結果。

```json theme={null}
{
  "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 管理頁面](https://toapis.com/console/token) 獲取您的 API Key

使用時在請求頭中添加：

```
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

**task\_id** `string` *required*

圖片生成 API 返回的任務 ID。也可以傳創建任務時提交的 `client_business_id`，用於按客戶側業務 ID 查詢任務狀態和結果。

> [!NOTE]
>
> 如果創建圖片任務時傳入 `client_business_id`，可直接使用同一個狀態查詢接口：
> `GET /v1/images/generations/{client_business_id}`。業務 ID 會限定在當前 API Key 所屬用戶下查詢。

```bash cURL theme={null}
curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'
```

```python Python theme={null}
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']}")
```

```javascript JavaScript theme={null}
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);
});
```

```go Go theme={null}
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)
    }
}
```

```json 200 - 處理中 theme={null}
{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1768381010,
  "billing": {
    "status": "pending"
  }
}
```

```json 200 - 已完成 theme={null}
{
  "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": 1768467463,
  "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"
  }
}
```

```json 200 - 失敗 theme={null}
{
  "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"
  }
}
```

```json 200 - 已完成 - 免費任務與用量 theme={null}
{
  "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": 1789185558,
  "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"
  }
}
```

```json 404 theme={null}
{
  "error": {
    "code": 404,
    "message": "任務不存在",
    "type": "not_found_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "身份驗證失敗，請檢查您的API密鑰",
    "type": "authentication_error"
  }
}
```

## 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 時間戳）

**finished\_at** `integer`

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

**completed\_at** `integer`

任務完成時間（Unix 時間戳，僅完成時返回）

**expires\_at** `integer`

圖片 URL 過期時間（Unix 時間戳，僅完成時返回）

**result** `object`

任務結果（僅成功時返回）

**屬性**

**type** `string`

結果類型，固定爲 `image`

**data** `array`

圖片數據數組

**數組元素**

**url** `string`

生成的圖片 URL

**billing** `object`

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

**屬性**

**status** `string`

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

**credits** `string`

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

**cost\_usd** `string`

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

**usage** `object`

可選的計費量, 圖片 token 明細及工具次數. `charge_type`, `requests`, `billed_tokens` 等欄位見[任務用量欄位](https://docs.toapis.com/docs/zh-Hant/api-reference/account/pricing.md). 圖片 token 明細僅在 `billing.status` 為 `settled`, 且儲存的用量有效並與最終扣費一致時回傳. 無法確認的部分省略, 已確認金額和圖片結果仍可正常回傳.

| 欄位 | 類型 | 說明 |
| - | - | - |
| `input_tokens` | integer | 輸入 token 總數, 包含文字和圖片 |
| `output_tokens` | integer | 輸出 token 總數 |
| `total_tokens` | integer | `input_tokens + output_tokens` |
| `input_tokens_details.text_tokens` | integer | 文字輸入 token 數 |
| `input_tokens_details.image_tokens` | integer | 圖片輸入 token 數 |
| `input_tokens_details.cached_tokens` | integer | 已快取的輸入 token 數, 已包含在輸入總數中 |
| `input_tokens_details.cached_tokens_details.text_tokens` | integer | 已快取的文字輸入 token 數 |
| `input_tokens_details.cached_tokens_details.image_tokens` | integer | 已快取的圖片輸入 token 數 |
| `output_tokens_details.text_tokens` | integer | 文字輸出 token 數, 僅在有輸出明細時回傳 |
| `output_tokens_details.image_tokens` | integer | 圖片輸出 token 數, 僅在有輸出明細時回傳 |
| `output_tokens_details.text_or_reasoning_tokens` | integer | 文字與思考同價且未細分的輸出 token 數, 不計入 `text_tokens`, 僅在存在時回傳 |
| `charge_type` | string | 計費方式: `per_request` 按次, `per_token` 按 token |
| `requests` | integer | 計費次數, `per_request` 時回傳. 請求中的 `n` 不直接乘算次數 |
| `billed_tokens` | integer | 計價 token 數, `per_token` 時回傳 |
| `input_images` | integer | 扣除免費額度後參與計費的輸入圖片數, 為零時省略 |
| `tool_usage.web_search`, `tool_usage.image_search`, `tool_usage.grounding_queries` | integer | 聯網搜尋, 圖片搜尋和 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 並存.

**error** `object`

錯誤信息（僅失敗時返回）

**屬性**

**code** `string`

錯誤代碼

**message** `string`

錯誤描述

## 計費狀態與費用統計

上述計費規則適用於圖片任務查詢, 不限制模型或管道. 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 是事件建立時的快照, 欄位缺少時可查詢此介面作為後備. 詳見[價格與實際費用](https://docs.toapis.com/docs/zh-Hant/api-reference/account/pricing.md).

## 任務狀態說明

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

## 輪詢策略建議

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

### Python 輪詢示例

```python theme={null}
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("任務超時")
```

## 圖片資源有效期

> [!WARNING]
>
> 生成的圖片 URL 有效期爲 **24 小時**
>
> * 請在有效期內下載保存圖片
> * `expires_at` 字段標識圖片過期時間（Unix 時間戳）
> * 圖片過期後無法訪問，如需重新獲取，需要重新提交生成任務

## 錯誤碼與失敗原因

請求錯誤與任務失敗的差異, 具體原因及處理方式, 請見[錯誤碼速查](https://docs.toapis.com/docs/zh-Hant/api-reference/errors.md). 查詢成功仍需檢查任務狀態, HTTP 狀態不是業務錯誤碼.

> [!NOTE]
>
> ToAPIs 支持統一 [任務 Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md)。回調為主、輪詢後備；至少 5～10 秒並加入抖動，`429` 讀取 `Retry-After`。批次最多 100 個任務，詳見 [限流](https://docs.toapis.com/docs/zh-Hant/api-reference/rate-limits/async-tasks.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.