Polling

Webhooks are the simplest way to learn that work finished. When you cannot receive them, poll the narration or video with these three tools.

Long-poll

Add wait (up to 30 seconds) to the read. Scenema holds the request and answers as soon as the status or stage changes, or when the wait ends:

curl -H "Authorization: Bearer $SCENEMA_API_KEY" \
  "https://api.scenema.ai/v1/videos/proj_7c2e91a04b6d3f8?wait=25"

One long-poll loop learns of a change within about a second and makes at most two requests a minute.

ETag and 304

Every read answers an ETag header. Send it back as If-None-Match, and when nothing changed the answer is 304 Not Modified with no body:

curl -H "Authorization: Bearer $SCENEMA_API_KEY" -H 'If-None-Match: W/"5GvWugoKmc93H56w89gMdp"' \
  "https://api.scenema.ai/v1/videos/proj_7c2e91a04b6d3f8?wait=25"

Together with wait, the request holds until the video differs from the one you have. A workspace holds at most 10 such requests at once; more answer at once. The links inside a narration or video (to the MP3, MP4, poster and captions) are signed fresh on every read and do not change the ETag.

When to ask again

While a narration or video is processing, the answer has a Retry-After header (seconds) and pollAfterMs in the body: about 3 seconds for a narration and 30 seconds for a video. A one minute video takes 10 to 15 minutes, so wait 5 to 10 minutes before you start polling it. Once it is completed or failed, both are gone.

Polls count toward your rate limit.