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.
| Status | Final | Meaning & Billing State |
|---|---|---|
| pending | No | Request accepted and max specification credits held; queued for execution. |
| processing | No | Model generation and output file verification in progress. |
| completed | Yes | Output file verified; exact usage.cost_credits deducted, unused hold returned, and results[0].url ready. |
| failed | Yes | Task 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
POSTwith the sameIdempotency-Keyand identical JSON body returns the existing task without creating a duplicate job or second hold. - Payload Conflict Guard: Reusing an
Idempotency-Keywith different parameters immediately returns HTTP409 idempotency_conflict(0 Creditscharged). - 30-Day Signed Result URLs (
files.callmodels.dev): Every completedresults[i].urlcarries a 30-day signature (expires+sig) that<img />,<video />, or your backend can read directly without passing anAuthorizationheader. Copy files to your own storage if you need to keep them pastexpires_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 Code | Trigger | Charged | Recommended Action |
|---|---|---|---|
| 400 invalid_parameter | Unknown field, bad enum, or invalid URL | 0 | Fix request JSON before resending |
| 401 invalid_api_key | Missing, malformed, revoked, or expired key | 0 | Issue or rotate cm_live_... key in Console |
402 insufficient_balance402 key_quota_exceeded | Available wallet or per-key cap below pre-hold | 0 | Top up wallet or raise key daily/total limit |
| 403 model_not_allowed | Target model excluded from key allowlist | 0 | Add model to key allowlist in Console |
| 409 idempotency_conflict | Same Idempotency-Key sent with different body | 0 | Generate a new Idempotency-Key per distinct payload |
429 rate_limited503 service_unavailable | Temporary rate limit or peak capacity busy | 0 | Exponential backoff (1s → 2s → 4s) with same key |
Task: submission_rejectedTask: upstream_failedTask: timeout | Content policy block, unreachable image_urls, model generation error, or timeout | 0 | Hold already returned; check input and submit with a new Idempotency-Key |