Async jobs
Video, music, and 3D generation run on the async-job pattern. Submit returns a job record immediately (HTTP 202); poll /v1/jobs/{id} or provide a webhook_url to receive the completion callback. Result files are served from media.aigateway.sh.
Submit a job
POST /v1/videos/generations { "prompt": "a cat doing parkour", "model": "google/veo-3.1-fast", "webhook_url": "https://yours.example.com/callbacks/veo" } // → 202 { "id": "job_...", "status": "queued", "object": "job" } GET /v1/jobs/job_... // → { "status": "completed", "result": { "file_url": "https://media.aigateway.sh/v1/files/jobs/..." } }
Job statuses
| Status | Meaning |
|---|---|
queued | Accepted by the gateway, waiting on provider capacity. |
running | Provider is actively generating — typical 30s–5min. |
completed | result.file_url is ready (signed, valid 24h). |
failed | error.code and error.message explain why. No charge. |
cancelled | You called POST /v1/jobs/{id}/cancel. |
Polling
Poll /v1/jobs/{id} no more than once every 3 seconds — faster polls return 304 Not Modified. For workloads with known long durations, prefer webhooks.
Webhook callback
If you pass webhook_url at submit time, we POST the completed job record to that URL. The callback carries all of the standard webhook headers — signature, delivery id, attempt count — and retries on failure.
Result URLs
Result files are served from media.aigateway.sh with a signed query string, valid for 24h. After expiry, re-fetch the job record to get a fresh URL (the underlying file persists for 7 days, then is GC'd).