Skip to content
scenemaDocs

Videos

A video is one audio, a narration, a voiceover or a soundtrack, made into a finished explainer in one style. Audio is the only input: the API takes no documents, images or video (see Audio is the only input). Creating one checks the request, holds the credits and starts the work; the video moves through its stages to completed (or failed).

Create a video

POST https://api.scenema.ai/v1/videos

Body field Meaning
audioId The audio the video is made of: a completed narration from POST /v1/narrations, or an asset from POST /v1/assets (a voiceover or a soundtrack). The video is as long as the audio.
style A style’s slug from GET /v1/styles or scenema.ai/styles, slug/palette for one of its palettes, or a style id.
aspectRatio Optional: 16:9 (default) or 9:16. A finished video can be made in the other one later; see Change a video.
prompt What the video should show and how: subjects, setting, mood. For a soundtrack, say what the video is about.
quality Optional: 480p (default), 768p or 1080p. Higher qualities cost more and depend on the plan.
title Optional name. The narration’s or asset’s title by default.
webhookUrl Optional https URL that gets video.completed or video.failed. See Webhooks.
captions Optional: {"enabled": true, "preset": "pill"} burns captions into the video. Presets: basic, cc, cue, pill, pop, marker, typewriter, neon, spotlight. Off by default.

Send an Idempotency-Key header with any unique string per video. A request that repeats a key returns the video the first request started, and holds nothing more, so a retry after a timeout is always safe.

The response has status 202 and the video with "status": "processing".

Get a video

GET https://api.scenema.ai/v1/videos/{id} returns the video. Wait 5 to 10 minutes after creating it, then ask every 30 to 60 seconds while it is processing.

{
  "id": "proj_7c2e91a04b6d3f8",
  "title": "Why the sky is blue",
  "status": "completed",
  "stage": "done",
  "audioId": "proj_4559d9dd5dc8d53",
  "style": "pure-ink-whiteboard",
  "styleId": "stl_6f1d0c2e8a9b4",
  "aspectRatio": "16:9",
  "quality": "480p",
  "durationMs": 58200,
  "createdAt": "2026-10-27T14:03:04.996Z",
  "credits": { "held": 1164, "used": 1164, "returned": 0 },
  "video": {
    "url": "https://...",
    "expiresAt": "2026-10-27T15:10:12.000Z",
    "durationMs": 58200,
    "width": 854,
    "height": 480,
    "posterUrl": "https://...",
    "captionsUrl": "https://...",
    "shareUrl": "https://scenema.ai/v/113b946f476ccd48"
  },
  "error": null,
  "studioUrl": "https://scenema.ai/app/studio/proj_7c2e91a04b6d3f8"
}

Stages

Stage What happens
queued The audio is transcribed and laid out into shots.
storyboard Scenema writes the storyboard.
design Every shot is designed.
images The keyframes are generated (also for a new aspect ratio).
animation The keyframes are animated.
audio A new audio track is matched to the shots (see One video, many languages).
waiting A provider is down; the video carries on by itself once it answers (see Failures and retries).
export The full video is exported as an MP4.
done The MP4 is ready.

List videos

GET https://api.scenema.ai/v1/videos lists the workspace’s videos made through the API, newest first, with page and perPage (up to 100).

Video fields

Field Meaning
status processing, completed or failed.
stage Where the video is; see Stages.
credits held: the price, held when the video started. used: credits charged. returned: held credits not charged.
video Set when completed, in the video’s current aspectRatio: url, a private link to the MP4 valid for one hour; expiresAt; durationMs, width, height; posterUrl; captionsUrl (SRT, valid for one hour); shareUrl, a public page that plays it. Fetch the video again for fresh links, and download the file to keep it.
error Why the video failed, when status is failed. On a completed video, why its last change failed: a new aspect ratio (the video kept its ratio) or an audio track (it kept its previous track).
errorCode, retryable When status is failed: why, as a code, and whether POST /v1/videos/{id}/retry can make it. See Failures and retries.
attempt 1, plus one per retry. credits adds up every attempt.
waiting While stage is waiting: since when and why.
formats Every aspect ratio of the video, each with status (completed, processing or failed, with errorCode and retryable), its video once made, and outdated for one made with an earlier audio track. See Change a video.
pending A change PATCH /v1/videos/{id} recorded that POST /v1/videos/{id}/generate has not made yet (aspectRatio, audioId, audioTrackId); null when nothing is pending. See Change a video.
audioTrack The audio track the video plays: id, audioId, language. See One video, many languages.
studioUrl The video’s project in the Scenema studio.

Videos made through the API stay out of the project list in the app; each one opens from its studioUrl.