ToAPIsToAPIs

Get Image Task ステータス

Query image generation task status and results

GET
/v1/images/generations/{task_id}

中国本土のユーザー向け: 中国本土のユーザーは 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

Authorizationstringヘッダー必須

All endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Path パラメータ

task_idstringパス必須

Task ID returned by the image generation API

リクエスト例

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: {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']}")
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);
});
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)
    }
}

レスポンス例

{
  "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",
  "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": "Task not found",
    "type": "not_found_error"
  }
}
{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}

レスポンス

idstring

Unique task identifier

client_business_idstring

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

objectstring

Object type, always generation.task

statusstring

Task status

  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
progressinteger

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

modelstring

Image generation model used

created_atinteger

Task creation time (Unix timestamp)

finished_atinteger

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

completed_atinteger

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

expires_atinteger

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

resultobject

Task result (only returned on success)

Properties
typestring

Result type, always image

dataarray

Image data array

Array Elements
urlstring

Generated image URL

result.data[].backgroundstring

プロバイダーが返した実際の背景種別: opaque または transparent. レイヤー分解のベースは opaque, 他のレイヤーは transparent です. 古いタスクや情報を返さないモデルでは省略されます.

billingobject

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

プロパティ
statusstring

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

creditsstring

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

cost_usdstring

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

usageobject

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

フィールド型説明
input_tokensintegerテキストと画像を含む入力トークンの合計
output_tokensinteger出力トークンの合計
total_tokensintegerinput_tokens + output_tokens
input_tokens_details.text_tokensintegerテキスト入力トークン数
input_tokens_details.image_tokensinteger画像入力トークン数
input_tokens_details.cached_tokensintegerキャッシュされた入力トークン数。入力合計に含まれます
input_tokens_details.cached_tokens_details.text_tokensintegerキャッシュされたテキスト入力トークン数
input_tokens_details.cached_tokens_details.image_tokensintegerキャッシュされた画像入力トークン数
output_tokens_details.text_tokensintegerテキスト出力トークン数。出力内訳がある場合のみ返されます
output_tokens_details.image_tokensinteger画像出力トークン数。出力内訳がある場合のみ返されます
output_tokens_details.text_or_reasoning_tokensintegerテキストと思考が同価格で細分化されていない出力トークン数。text_tokens には含まれず、存在する場合のみ返されます
charge_typestring課金方式: per_request は回数課金, per_token はトークン課金
requestsinteger課金対象のリクエスト数。per_request の場合に返されます。リクエストの n は直接乗算されません
billed_tokensinteger料金計算に使用したトークン数。per_token の場合に返されます
input_imagesinteger無料枠を差し引いた課金対象の入力画像数。ゼロの場合は省略します
tool_usage.web_search, tool_usage.image_search, tool_usage.grounding_queriesintegerWeb 検索、画像検索、Grounding クエリの回数。使用した場合に返されます

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

errorobject

エラー information (only returned on failure)

Properties
codestring

エラー code

messagestring

エラー 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 はイベント作成時のスナップショットです。フィールドがない場合は、このエンドポイントをフォールバックとして照会してください。 料金と実際の請求額も参照してください。

Task ステータス Reference

ステータス説明Is FinalRecommended Action
queuedTask submitted, waiting for processing❌5~10秒以上と jitter を入れて照会
in_progressTask is processing❌5~10秒以上と jitter を入れて照会
completedTask completed successfully✅Get image from url field
failedTask 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

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

Generated images are retained for 30 days

  • 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

エラーと失敗理由

リクエストエラー, タスク失敗の具体的な原因, 復旧方法はエラー早見表を参照してください. 照会成功後もタスク状態を確認し, HTTP ステータスと業務コードを区別してください.

ToAPIs の統一 Task Webhook を優先し、照会はフォールバックにします。5~10秒以上と jitter、429 の Retry-After を使用してください。バッチは最大100件です。レート制限。