API task lifecycle and errors

Safely poll, resume, cancel, and recover generation tasks.

On this page

Status values

  • SUBMITTED: accepted and waiting to start
  • PROGRESS: generation is running
  • COMPLETED: output is ready for retrieval
  • FAILED: generation ended unsuccessfully
  • CANCEL: the submitted task was cancelled

Read and cancel endpoints

  • GET /api/v1/tasks/{taskId}/status returns the current status
  • GET /api/v1/tasks/{taskId} returns task input, output, status, and completion time
  • PUT /api/v1/tasks/{taskId}/cancel cancels only a task that is still SUBMITTED

All endpoints require the API key in the key header. Query endpoints share a limit of 60 requests per minute per IP and may return HTTP 429 with Retry-After.

Safe retry behavior

Status and detail reads may be retried with backoff. For paid creation, send a stable Idempotency-Key and reuse it only for retries of the identical logical request. Identical retries return the existing task and do not charge twice; using the same key with different request data returns HTTP 409. Also send X-Max-Credits so a request is rejected before billing if its authoritative quote is above the approved amount.

Quote with POST /api/v1/quote/{model} before asking for spending approval. Quotes validate the model fields and price but do not fetch media, run content safety, create tasks, or charge credits. Resume a known task with its task ID rather than creating a replacement.

The downloadable skill exits 0 on success, 1 on validation, API, terminal job, or retrieval failure, and 2 when polling times out while the task remains resumable. Diagnostics go to stderr and the structured JSON result stays on stdout.

Refunds and retrieval

Provider tasks that reach terminal failure are recorded as failed and their debited credits are refunded. If generation completes but details cannot be retrieved, retain the task ID and retry the detail request; do not submit a replacement generation until task state is known.