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. Before calling, create a site API key in token management, then copy an exact model ID visible to the current key group and supported on the original route from the model marketplace.

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="your site API key"
export MODEL_NAME="exact model ID copied from the marketplace"

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

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

The final curl above demonstrates one retrieval only. A real client must read status and continue polling nonterminal states with the backoff described below; one retrieval does not mean that the task is complete.

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. This video example creates two layers of work: poll the generic task first. Outer completed means only that the inner POST /v1/videos returned; if result contains a video task ID, continue with the video API's own polling until its SUCCESS or FAILURE.

States and terminal outcomes

Treat queued, not_start, submitted, and in_progress as nonterminal. Failure and completed are outer terminal states; 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.