Get Image Task Status - ToAPIs Documentation

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.

Authorizations

Authorization

string

必填

All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

task_id

string

必填

Task ID returned by the image generation API

curl --request GET \
  --url 'https://toapis.com/v1/images/generations/task_01KA040M0HP1GJWBJYZMKX1XS1' \
  --header 'Authorization: Bearer <token>'

{
  "id": "img_5b8b19afe5c24ab3a92df996f1a33931",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1768381010
}

Response

string

Unique task identifier

object

string

Object type, always generation.task

status

string

Task status

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

model

string

Image generation model used

created_at

integer

Task creation time (Unix timestamp)

completed_at

integer

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

url

string

Generated image URL (only returned on success)

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

error

object

Error information (only returned on failure)

显示 Properties

code

string

Error code

message

string

Error description

Task Status Reference

Status	Description	Is Final	Recommended Action
`submitted`	Task submitted, waiting for processing	❌	Wait 2-3 seconds, then query again
`in_progress`	Task is processing	❌	Wait 3-5 seconds, then query again
`completed`	Task completed successfully	✅	Get image from url field
`failed`	Task processing failed	✅	Check error info

Polling Strategy

Initial wait: 2 seconds
Polling interval: 3 seconds
Max wait: 120 seconds
Typical time: 5-30 seconds

Python Polling Example

import time
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 = 3  # 3 second interval
    
    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}'}
        )
        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)
    
    raise TimeoutError("Task timeout")

Resource Expiration

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

Error Codes

HTTP Code	Error Type	Description
400	`invalid_request`	Invalid request parameters
401	`unauthorized`	Authentication failed, check API Key
402	`insufficient_quota`	Insufficient balance
404	`task_not_found`	Task not found
422	`content_policy_violation`	Content policy violation
429	`rate_limit_exceeded`	Rate limit exceeded
500	`internal_error`	Internal server error

​Authorizations

​Path Parameters

​Response

​Task Status Reference

​Polling Strategy

​Python Polling Example

​Resource Expiration

​Error Codes

Authorizations

Path Parameters

Response

Task Status Reference

Polling Strategy

Python Polling Example

Resource Expiration

Error Codes