The asynchronous order model

POST /orders doesn't generate anything. It validates the request, locks the funds and the token quota, queues the task and answers 201 with status created — in this response result is null, and there are no files and cannot be any. The result appears minutes later, and finding out about it is a separate job for the client.

What the 201 response contains

Four order types, not nine

POST /orders requires one of two: template_id or task_type. A template defines the service and all the settings — that's how TTS is created. A bare task_type works only where the service code matches the task type.

The description key for SFX is text, for Music it's prompt; they're easy to mix up, and the rejection will say “field is required”. Put the keys at the root of task_data, without the sfx_settings / music_settings wrappers from the configuration reference: in a template the wrapper gives 422, in an order it is silently dropped.

curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{
  "task_type": "music",
  "task_data": { "prompt": "Lo-fi hip hop, calm, rainy night", "n_variants": 3,
                 "music_length_ms": 30000, "force_instrumental": true }
}'

The price here depends on the number of generations, not their size: sfx and voice_search are one rate per order, music is the rate x n_variants. A five-minute track costs exactly as much as a ten-second one. The server mixes the service's default_config in on top of your values (disabled with the skip_service_defaults: true flag), so the order's saved task_data will contain keys you never sent.

Nine statuses

Terminal — five: completed, result_delivered, failed, compensated, cancelled. An order in these statuses no longer changes, polling it further is pointless, and file retention (7 days by default) is counted from the moment of this transition.

Non-terminal — four: created, pending, in_progress, partially_completed.

The spec doesn't explain the difference between failed and compensated; what they share is result: null. Cancellation is accepted only in created, pending and partially_completed, otherwise 400.

The trap: partially_completed is not final

An order moves to partially_completed when some of its chunks failed: the finished fragments are in place, the failed ones await your decision. A handler that treats everything except created/pending/in_progress as terminal will quietly abandon such an order half-done — even though it can be brought to completed with two calls.

The playbook for finishing it is in the Retries and idempotency guide. The order-level POST /orders/{order}/retry won't do for this: it doesn't accept partially_completed and creates a new paid order.

Chunks

Text is split into chunks (OrderItem) before generation, and the work proceeds chunk by chunk. “Chunk” and “fragment” mean the same thing in this documentation: in API fields they are chunk_index, total_chunks, completed_chunks. A chunk has its own statuses that don't match the order statuses: pending, processing, completed, failed (a technical error) and policy_flagged (rejected by the content policy).

The list comes in items[] of GET /orders/{order}; the GET /orders list doesn't have this field. Retries and regenerations live as separate records with the same chunk_index and a parent_item_id reference, so the length of items[] doesn't equal total_chunks. Calculate progress from completed_chunks / total_chunks — only the original chunks count there, otherwise the percentage would climb above a hundred.

Readiness: subscribe or poll

Polling isn't forbidden and works perfectly well for short orders — just do it carefully: an interval of 2–5 seconds (the spec doesn't set a rate, but every poll consumes the key's window), base the pause on eta_seconds / eta_at, check a dozen orders with a single GET /orders?status=in_progress instead of N requests, and always set a cap on attempts — failed is an answer too.

Bulk chunk retry is the same case: 202 means “plan accepted”, and the result arrives later via the bulk_retry.completed event or by polling GET /orders/{order}/items.

Files appear later

result.files[] are paths, not links: you exchange them for a temporary URL via POST /storage/url, and it's best to do so right at completed — the files live only until retention. How to tell a live path from a dead one is covered in the Files, links and storage guide.