Core conceptsGenerations

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

StatusMeaningBalance
queuedAccepted and waiting. It can be canceled.Held
in_progressBeing made. It cannot be canceled.Held
succeededoutput.url is the finished MP4.Charged for the finished length, the rest restored
failederror says why.Fully restored
canceledCanceled 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 and output becomes null with output_deleted: true.
  • output.url is 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.