Image Generation, Editing, and Async Tasks

QuotaAPI provides synchronous images, asynchronous single-image tasks, and batch image workflows. Choose an endpoint based on task count and expected duration instead of immediately resubmitting when a client times out.

Capabilities and platforms

Workflow	Main endpoints	Eligible groups	Best for
Synchronous generation and edits	/v1/images/generations, /v1/images/edits	OpenAI, Grok	One image with an interactive wait
Asynchronous generation and edits	/v1/images/generations/async, /v1/images/edits/async	OpenAI, Grok	Long-running single images and reliable polling
Batch images	/v1/images/batches	Gemini	Multiple prompts, downloads, and job management

The API Key must bind to a group that supports the endpoint, and image generation must be enabled for that group by an administrator. Model names and parameters remain subject to the target platform, account, and console configuration.

Synchronous image generation

curl https://quotarouter.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A quiet product studio with soft daylight.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

Set the client timeout for a single image to at least 120 seconds. A connection ending before 120 seconds does not prove that the task failed, so do not automatically resubmit a potentially billable request. Prefer the asynchronous endpoint when completion time is uncertain.

Synchronous image edits

Upload a local file as multipart data:

curl https://quotarouter.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Keep the subject and replace the background with a studio." \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "response_format=b64_json"

You can also send image URLs in JSON when the target platform supports them. Do not use a short-lived signed URL in a task that may be retried later.

Asynchronous single-image tasks

Async endpoints accept the same request body as their synchronous counterparts, but streaming image requests are not supported. Submit a generation task:

curl -i https://quotarouter.ai/v1/images/generations/async \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A precise isometric data center illustration.",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

Use /v1/images/edits/async for an edit task. A successful submission returns 202 Accepted, Location, and Retry-After: 3 headers. Its body includes task_id, status, poll_url, created_at, and expires_at.

{
  "task_id": "imgtask_EXAMPLE",
  "status": "processing",
  "poll_url": "/v1/images/tasks/imgtask_EXAMPLE",
  "created_at": 1785984000,
  "expires_at": 1786070400
}

Poll with the same API Key that submitted the task:

The parameterized polling route is GET /v1/images/tasks/{task_id}.

curl https://quotarouter.ai/v1/images/tasks/imgtask_EXAMPLE \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY"

The lifecycle is:

Status	Meaning	Client action
processing	Generation is still running	Wait for Retry-After, normally about 3 seconds, then poll again
completed	Generation completed	Read the result from result or the protected image_url
failed	Generation failed	Inspect http_status and error; do not retry forever

Execution is limited to 30 minutes, and task records and results are retained for 24 hours by default. Results are stored in the configured private object storage and exposed through authenticated /media/... URLs, so download them before expiration. Ownership is scoped to both the user and API Key; another Key owned by the same user cannot poll the task.

WARNING

After a client timeout, continue polling the existing task_id. Create a new task only after an explicit failed status with a retryable error.

Batch images

Batch processing is designed for many prompts and consolidated downloads. First list the models available to the current Key:

curl https://quotarouter.ai/v1/images/batches/models \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY"

Always send a unique Idempotency-Key when submitting so a network retry cannot create a duplicate job:

curl https://quotarouter.ai/v1/images/batches \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-catalog-20260806-01" \
  -d '{
    "task_name": "Product catalog",
    "model": "gemini-2.5-flash-image",
    "aspect_ratio": "1:1",
    "image_size": "1K",
    "items": [
      {
        "custom_id": "cover-001",
        "prompt": "A clean white product background.",
        "output_count": 1
      }
    ]
  }'

The batch API also supports listing jobs, viewing details and items, downloading one image or a ZIP, cancelling work, and deleting records or outputs. The console workflow is covered in the dedicated batch-image guide; API routes share the /v1/images/batches root.

Common errors

Status	Common cause
400	Invalid parameters, file format, model, or streaming option
401	Invalid API Key
403	Image generation is disabled for the group or the capability is unavailable
404	Unsupported platform, async tasks disabled, or task not found
429	User, account, or image concurrency limit reached
503	No eligible account or task storage temporarily unavailable

Use the platform and endpoint compatibility matrix and the current console model list as the source of truth for availability.