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

# Get Image Task ステータス

> Query image generation task status and results

> [!NOTE]
>
> **中国本土のユーザー向け：** 中国本土のユーザーは `https://toapis.cn` を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では `https://toapis.com` を `https://toapis.cn` に置き換えてください。

* Query async image generation task execution status and results
* Real-time status updates and progress tracking
* Get generated images when task completes
* Multi-language support (zh/en/ko/ja)

All image generation tasks are executed asynchronously. After submitting a task, you need to query the status and results via the query endpoint.

通常の画像と動画のタスクは `GET /v1/tasks/{task_id}` でも照会でき, `usage` と `billing` の定義は共通です. このページは冒頭に記載した生成タスク照会パスのレスポンスを説明します.

サンプルはフィールドを示すもので, モデルの現在の価格や固定の課金方式を示すものではありません. 実際のタスクで返されたフィールドと金額を確認してください.

## Authorizations

**Authorization** `string` *required*

All endpoints require Bearer Token authentication

Get your API Key:

Visit the [API Key Management Page](https://toapis.com/console/token) to get your API Key

Add it to the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Path パラメータ

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

Task ID returned by the image generation API

```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: {status}")

        if status == 'completed':
            return result
        elif status == 'failed':
            raise Exception(f"Task failed: {result}")

        time.sleep(interval)

    raise Exception("Task timeout")

# Usage example
task_id = "task_01KA040M0HP1GJWBJYZMKX1XS1"
result = wait_for_image(task_id)
print(f"Image 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: ${status}`);

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

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

  throw new Error('Task timeout');
}

// Usage example
const taskId = 'task_01KA040M0HP1GJWBJYZMKX1XS1';
waitForImage(taskId).then(result => {
  console.log('Image 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("Status: %s\n", status)

        if status == "completed" {
            fmt.Println("Image generation completed!")
            fmt.Println("Image URL:", result["url"])
            break
        }

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

```json 200 - In Progress 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 - Completed theme={null}
{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "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 - Failed 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": "Task not found",
    "type": "not_found_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}
```

## レスポンス

**id** `string`

Unique task identifier

**client\_business\_id** `string`

省略可能な顧客側の業務 ID. タスク作成時に `client_business_id` を指定した場合のみ返します.

**object** `string`

Object type, always `generation.task`

**status** `string`

Task status

* `queued` - Queued for processing
* `in_progress` - Processing
* `completed` - Successfully completed
* `failed` - Failed

**progress** `integer`

0-100 の整数の進行率です.

**model** `string`

Image generation model used

**created\_at** `integer`

Task creation time (Unix timestamp)

**finished\_at** `integer`

タスク終了時刻, Unix タイムスタンプ. この照会パスでは, 成功または失敗したタスクに保存済みの終了時刻がある場合に返します.

**completed\_at** `integer`

Task completion time (Unix timestamp, only returned when completed)

**expires\_at** `integer`

Image URL expiration time (Unix timestamp, only returned on completion)

**result** `object`

Task result (only returned on success)

**Properties**

**type** `string`

Result type, always `image`

**data** `array`

Image data array

**Array Elements**

**url** `string`

Generated image URL

**billing** `object`

画像タスクの課金情報です。省略される場合があります。課金状態は生成状態とは独立しており、`completed` でも精算済みとは限りません。課金情報を確認できない場合、`billing` 全体が省略され、`null` は返されません。省略は無料を意味しません。

**プロパティ**

**status** `string`

`pending` は精算または返金が未確認で、金額は省略されます。`settled` は最終請求額が確定した状態です。`refunded` は返金済み、または失敗後の正味請求額がゼロと確認された状態で、課金前に失敗した場合も含みます。

**credits** `string`

プラットフォームが顧客に実際に請求したクレジット数を十進数の文字列で返します。`settled` または `refunded` の場合のみ返されます。

**cost\_usd** `string`

プラットフォームが顧客に実際に請求した米ドル金額を十進数の文字列で返します。課金時の割引と倍率を含み、プロバイダーの原価ではありません。

**usage** `object`

省略可能な課金数量, 画像トークン内訳, ツール使用回数です. `charge_type`, `requests`, `billed_tokens` などは[タスクの使用量フィールド](https://docs.toapis.com/docs/ja/api-reference/account/pricing.md)を参照してください. 画像トークン内訳は, `billing.status` が `settled` で, 保存された使用量が有効かつ最終請求と一致する場合のみ返します. 確認できない部分を省略しても, 確認済みの金額と画像の結果は返されます.

| フィールド | 型 | 説明 |
| - | - | - |
| `input_tokens` | integer | テキストと画像を含む入力トークンの合計 |
| `output_tokens` | integer | 出力トークンの合計 |
| `total_tokens` | integer | `input_tokens + output_tokens` |
| `input_tokens_details.text_tokens` | integer | テキスト入力トークン数 |
| `input_tokens_details.image_tokens` | integer | 画像入力トークン数 |
| `input_tokens_details.cached_tokens` | integer | キャッシュされた入力トークン数。入力合計に含まれます |
| `input_tokens_details.cached_tokens_details.text_tokens` | integer | キャッシュされたテキスト入力トークン数 |
| `input_tokens_details.cached_tokens_details.image_tokens` | integer | キャッシュされた画像入力トークン数 |
| `output_tokens_details.text_tokens` | integer | テキスト出力トークン数。出力内訳がある場合のみ返されます |
| `output_tokens_details.image_tokens` | integer | 画像出力トークン数。出力内訳がある場合のみ返されます |
| `output_tokens_details.text_or_reasoning_tokens` | integer | テキストと思考が同価格で細分化されていない出力トークン数。`text_tokens` には含まれず、存在する場合のみ返されます |
| `charge_type` | string | 課金方式: `per_request` は回数課金, `per_token` はトークン課金 |
| `requests` | integer | 課金対象のリクエスト数。`per_request` の場合に返されます。リクエストの `n` は直接乗算されません |
| `billed_tokens` | integer | 料金計算に使用したトークン数。`per_token` の場合に返されます |
| `input_images` | integer | 無料枠を差し引いた課金対象の入力画像数。ゼロの場合は省略します |
| `tool_usage.web_search`, `tool_usage.image_search`, `tool_usage.grounding_queries` | integer | Web 検索、画像検索、Grounding クエリの回数。使用した場合に返されます |

`charge_type`、`requests`、`billed_tokens`、`input_images` は課金数量であり、`billing.status=settled` と同時にのみ返されます。提出時に一括課金される回数課金タスクも、実際の金額とともに `settled` を返します。トークン数はすべて非負のJSON整数です。キャッシュ分は入力トークンの一部なので、再加算しないでください。出力内訳がない場合、`output_tokens_details` 全体が省略されます。`usage.tool_usage.web_search` は単独でも、画像トークンと併せても返されます。

**error** `object`

エラー information (only returned on failure)

**Properties**

**code** `string`

エラー code

**message** `string`

エラー description

## 課金状態と費用の集計

この課金規則はモデルやチャネルを問わず画像タスク照会に適用されます。GPT-Image-2.5のSunburstとFlareのVIP / Officialモデルはトークン使用量に対応しており、その他のモデルは保存済みの精算データに応じて返されます。例の金額はレスポンス形式を示すもので、固定単価ではありません。

| billing.status | 意味 | 金額と画像トークン |
| - | - | - |
| `pending` | 生成中、精算待ち、または返金未確認 | 金額と画像トークンを省略。事前引き落としは最終費用ではありません |
| `settled` | 最終請求額が確定 | 金額を返し、有効な使用量があれば画像トークンも返します。無料タスクは `"0"` を返す場合があります |
| `refunded` | 返金済み、または失敗後の正味請求額がゼロと確認済み | `credits` と `cost_usd` はともに `"0"`。画像トークンは省略 |

* 金額はタスクの確定済みの最終請求額です。照会で課金、追加請求、返金、現在のモデル価格による再計算は行いません。集計には返された金額を使い、トークン数と現在の単価から再計算しないでください。
* タスクの `id` ごとに金額を更新し、ポーリングのたびに同じ金額を加算しないでください。十進数で計算し、`pending` やフィールドの欠損をゼロ費用として扱わないでください。
* 金額は十進数の文字列で、小数点以下の桁数は固定ではありません。
* 課金記録が欠損または不整合の場合、`billing` が省略されることがあります。画像がまだ配信できず、一時的に `in_progress` と表示される場合は、`billing` と `usage` の両方が省略されることもあります。
* 成功 Webhook の `data.usage` と `data.billing` は、このエンドポイントと同じ確認条件とフィールド値を使います。Webhook はイベント作成時のスナップショットです。フィールドがない場合は、このエンドポイントをフォールバックとして照会してください。 [料金と実際の請求額](https://docs.toapis.com/docs/ja/api-reference/account/pricing.md)も参照してください。

## Task ステータス Reference

| ステータス | 説明 | Is Final | Recommended Action |
| - | - | - | - |
| `queued` | Task submitted, waiting for processing | ❌ | 5\~10秒以上と jitter を入れて照会 |
| `in_progress` | Task is processing | ❌ | 5～10秒以上と jitter を入れて照会 |
| `completed` | Task completed successfully | ✅ | Get image from url field |
| `failed` | Task processing failed | ✅ | Check error info |

## Polling Strategy

```
Initial wait: 5 seconds
Polling interval: at least 5–10 seconds with random jitter
Max wait: 120 seconds
Typical time: 5-30 seconds
```

### Python Polling Example

```python theme={null}
import time
import random
import requests

def poll_image_task(task_id, api_key, max_wait=120):
    """Poll image generation task until completion or timeout"""
    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"Generation failed: {data['error']['message']}")

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

    raise TimeoutError("Task timeout")
```

## Resource Expiration

> [!WARNING]
>
> Generated image URLs are valid for **24 hours**
>
> * Please download and save images within the validity period
> * `expires_at` field indicates image expiration time (Unix timestamp)
> * Expired images cannot be accessed; to regenerate, submit a new task

## エラーと失敗理由

リクエストエラー, タスク失敗の具体的な原因, 復旧方法は[エラー早見表](https://docs.toapis.com/docs/ja/api-reference/errors.md)を参照してください. 照会成功後もタスク状態を確認し, HTTP ステータスと業務コードを区別してください.

> [!NOTE]
>
> ToAPIs の統一 [Task Webhook](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md) を優先し、照会はフォールバックにします。5～10秒以上と jitter、`429` の `Retry-After` を使用してください。バッチは最大100件です。[レート制限](https://docs.toapis.com/docs/ja/api-reference/rate-limits/async-tasks.md)。


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