Async tasks

Why async tasks

Video and audio/music generation are not exposed as OpenAI-compatible synchronous endpoints (there is no /api/v1/videos/generations or /api/v1/audio/*). These modalities can take anywhere from several seconds to several minutes, so the gateway exposes them through a single async task queue: you submit a job, then poll for its result.

1. Submit a task

POST a model alias and a model-specific input object, then poll the returned task_id for status. Polling is the only source of truth — the gateway sends no completion webhook, and a callback field is rejected with 400 rather than silently ignored.

The accepted keys inside input differ per model, and there is no single shape that fits all of them. Do not guess from the example below: call GET /api/public/models and read the playgroundFormJson.fields array for the alias you are using. Every field there carries its name, type, whether it is required, and the allowed values for enums — that array is the parameter contract for that model. Required fields that are omitted are rejected before the job is queued (for example a music model needs customMode alongside prompt).

2. Poll for the result

Use the returned task_id to check status. Poll at a reasonable interval (a few seconds) until the task reaches a terminal state.

Task status values

• QUEUED — accepted, waiting to start.
• RUNNING — in progress upstream.
• SUCCESS — finished; result contains one or more output URLs.
• FAILED — finished with an error; see error.code and error.message.
• EXPIRED — the task result window elapsed before it was retrieved.

Submit request fields

• model (required) — an async-capable model alias (video, audio, or async image).
• input (required) — a model-specific object, passed through to the underlying model.

Billing

Billed in Credits when the task reaches SUCCESS. Failed or expired tasks are not charged.