Get Image Task ステータス
Query image generation task status and results
中国本土のユーザー向け: 中国本土のユーザーは 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_KEYPath パラメータ
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"
}
}レスポンス
idstringUnique task identifier
client_business_idstring省略可能な顧客側の業務 ID. タスク作成時に client_business_id を指定した場合のみ返します.
objectstringObject type, always generation.task
statusstringTask status
queued- Queued for processingin_progress- Processingcompleted- Successfully completedfailed- Failed
progressinteger0-100 の整数の進行率です.
modelstringImage generation model used
created_atintegerTask creation time (Unix timestamp)
finished_atintegerタスク終了時刻, Unix タイムスタンプ. この照会パスでは, 成功または失敗したタスクに保存済みの終了時刻がある場合に返します.
completed_atintegerTask completion time (Unix timestamp, only returned when completed)
expires_atintegerImage URL expiration time (Unix timestamp, only returned on completion)
resultobjectTask result (only returned on success)
Properties
typestringResult type, always image
dataarrayImage data array
Array Elements
urlstringGenerated image URL
result.data[].backgroundstringプロバイダーが返した実際の背景種別: opaque または transparent. レイヤー分解のベースは opaque, 他のレイヤーは transparent です. 古いタスクや情報を返さないモデルでは省略されます.
billingobject画像タスクの課金情報です。省略される場合があります。課金状態は生成状態とは独立しており、completed でも精算済みとは限りません。課金情報を確認できない場合、billing 全体が省略され、null は返されません。省略は無料を意味しません。
プロパティ
statusstringpending は精算または返金が未確認で、金額は省略されます。settled は最終請求額が確定した状態です。refunded は返金済み、または失敗後の正味請求額がゼロと確認された状態で、課金前に失敗した場合も含みます。
creditsstringプラットフォームが顧客に実際に請求したクレジット数を十進数の文字列で返します。settled または refunded の場合のみ返されます。
cost_usdstringプラットフォームが顧客に実際に請求した米ドル金額を十進数の文字列で返します。課金時の割引と倍率を含み、プロバイダーの原価ではありません。
usageobject省略可能な課金数量, 画像トークン内訳, ツール使用回数です. charge_type, requests, billed_tokens などはタスクの使用量フィールドを参照してください. 画像トークン内訳は, 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 は単独でも、画像トークンと併せても返されます。
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 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 secondsPython 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_atfield indicates image expiration time (Unix timestamp)- Expired images cannot be accessed; to regenerate, submit a new task
エラーと失敗理由
リクエストエラー, タスク失敗の具体的な原因, 復旧方法はエラー早見表を参照してください. 照会成功後もタスク状態を確認し, HTTP ステータスと業務コードを区別してください.
429 の Retry-After を使用してください。バッチは最大100件です。レート制限。