Unified async tasks: submit, poll, and retain results

Beginner: submit and poll

The generic wrapper preserves the original POST path and prefixes it with /async. This example runs video creation in the background; use a model and route shown as supported in the marketplace.

Copysubmit=$(curl -sS "$BASE_URL/async/v1/videos"   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{"model":"<MODEL_ID>","prompt":"A short shot of a city after rain"}')
task_id=$(printf '%s' "$submit" | jq -r .id)

curl -sS "$BASE_URL/get-async?id=$task_id"   -H "Authorization: Bearer $API_KEY"

A successful submission normally returns 202 with an id and queued status. Polling is authorized against the creating user and token context; a task ID is not a public download URL.

States and terminal outcomes

Treat queued, not_start, submitted, and in_progress as nonterminal. Failure and completed are terminal. Expired means the result was removed. Poll with jittered backoff, such as 1, 2, 4, and 8 seconds before a cap, and set a total deadline. Do not poll forever or create a new generation whenever a UI refreshes.

Result envelope

JSON upstream output appears in result. Binary output is Base64 with encoding: "base64", the original content_type, and status_code. Inspect the outer status first, then validate the embedded status and schema. Stream durable media into your own object store immediately after completion.

Unsupported wrapping

Generic async rejects GET, SSE, stream:true, model discovery, /v1/files, /v1/realtime, and Gemini streaming generation. Native video, Kling, Suno, and other task protocols may have separate create and query routes; their IDs are not interchangeable with generic task IDs.

Idempotency, failure, and billing

When the network drops before the submit response, a task may already exist. Save a business request fingerprint and look for an existing task before replaying. Queue-full, validation, and authentication failures should not be retried indefinitely; bounded backoff is for transient 429 or 5xx conditions. Reconcile terminal task ID, Request-ID, and consumption log.

Expert operations

Monitor queue depth, queue delay, execution duration, success rate, failure reason, result size, expiration rate, and free storage. Bound response size and use streaming I/O so media never has to reside fully in memory. Cleanup must protect running tasks, and low storage should reject new work rather than delete results awaiting delivery.