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/..." } }
Music works the same way via POST /v1/audio/music. Pass duration (seconds) for a length-controlled clip — honored where the model supports it (e.g. fal-ai/stable-audio-25/text-to-audio, fal-ai/ace-step/prompt-to-audio) and clamped to the model's range; some models (e.g. minimax music) pick their own length. Set is_instrumental or omit lyrics for an instrumental bed.
POST /v1/audio/music { "prompt": "calm lo-fi instrumental, warm Rhodes, vinyl crackle", "model": "fal-ai/stable-audio-25/text-to-audio", "duration": 15, "is_instrumental": true } // → 202 { "id": "job_...", "status": "queued", "object": "job" }
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).