Core concepts
Generations
The life of a generation: statuses, polling, cancel, delete and retention.
A generation is one Siren request. It is created with a mode endpoint (create generation) and read, listed, canceled and deleted with the shared /generations endpoints.
Statuses
| Status | Meaning | Balance |
|---|---|---|
queued | Accepted and waiting. It can be canceled. | Held |
in_progress | Being made. It cannot be canceled. | Held |
succeeded | output.url is the finished MP4. | Charged for the finished length, the rest restored |
failed | error says why. | Fully restored |
canceled | Canceled while queued. | Fully restored |
Polling
Call Get generation with wait_s up to 20. The server holds the request until the generation reaches a terminal status or the time runs out, then answers. Repeat while the status is queued or in_progress. Or send webhook_url with the create request and the finished generation is posted to you (Webhooks).
curl "https://serastudio.app/api/v1/generations/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70?wait_s=20" \
-H "Authorization: Bearer $SERA_API_KEY"Idempotent creation
Send an Idempotency-Key header on every create request. If your request times out or your process restarts, send it again with the same key and body: you get the existing generation back with 200 instead of a second one. The key is scoped to the workspace and kept with the generation.
Retention
- The MP4 and its thumbnail are kept for 7 days after the generation finished (
output.retained_until). Then they are deleted andoutputbecomesnullwithoutput_deleted: true. output.urlis a signed address valid for 60 minutes (output.url_expires_at). Get the generation again for a fresh one.- Delete generation removes the files right away. The record, with its billing, stays.
- Uploads stay until you delete them.