Async Tasks, 30-Day Result URLs & Error Codes

Every image and video generation runs as an async task with 24-hour Idempotency-Key deduplication, 30-day HTTPS media URLs, and structured error handling.

POST /v1/{images,videos}/generations → GET /v1/tasks/:task_id

Task states & polling cadence

Generation endpoints validate your payload, lock the published rate, temporarily hold the maximum specification credits, and return HTTP 202 Accepted with a task_... ID. Poll GET /v1/tasks/:task_id every 2s for images or every 3–5s for videos until completed or failed.

StatusFinalMeaning & Billing State
pendingNoRequest accepted and max specification credits held; queued for execution.
processingNoModel generation and output file verification in progress.
completedYesOutput file verified; exact usage.cost_credits deducted, unused hold returned, and results[0].url ready.
failedYesTask ended with error.code; 100% of held credits returned (0 Credits charged).
{
  "id": "task_01e561ba-859e-47fe-be79-60bc6f1d6499",
  "model": "gpt-image-2.6-flare",
  "object": "image.generation.task",
  "status": "pending",
  "created_at": "2026-11-15T09:49:18.000Z"
}

Idempotency-Key & 30-day HTTPS result URLs

Include a unique Idempotency-Key header (for example crypto.randomUUID() or your internal order ID) on every POST request:

  • Safe Network Retries (24h Window): Repeating a POST with the same Idempotency-Key and identical JSON body returns the existing task without creating a duplicate job or second hold.
  • Payload Conflict Guard: Reusing an Idempotency-Key with different parameters immediately returns HTTP 409 idempotency_conflict (0 Credits charged).
  • 30-Day Signed Result URLs (files.callmodels.dev): Every completed results[i].url carries a 30-day signature (expires + sig) that <img />, <video />, or your backend can read directly without passing an Authorization header. Copy files to your own storage if you need to keep them past expires_at.

HTTP status codes, task errors & retry rules

Every non-2xx HTTP response and every failed task returns { "error": { "code", "message", "retryable" } } plus an X-Request-Id header for support tracing.

HTTP / Error CodeTriggerChargedRecommended Action
400 invalid_parameterUnknown field, bad enum, or invalid URL0Fix request JSON before resending
401 invalid_api_keyMissing, malformed, revoked, or expired key0Issue or rotate cm_live_... key in Console
402 insufficient_balance402 key_quota_exceeded
Available wallet or per-key cap below pre-hold0Top up wallet or raise key daily/total limit
403 model_not_allowedTarget model excluded from key allowlist0Add model to key allowlist in Console
409 idempotency_conflictSame Idempotency-Key sent with different body0Generate a new Idempotency-Key per distinct payload
429 rate_limited503 service_unavailable
Temporary rate limit or peak capacity busy0Exponential backoff (1s → 2s → 4s) with same key
Task: submission_rejectedTask: upstream_failedTask: timeout
Content policy block, unreachable image_urls, model generation error, or timeout0Hold already returned; check input and submit with a new Idempotency-Key