Video API

The Video API turns audio into a finished video in any Scenema style, with no one in the loop. Scenema writes the storyboard from the audio, designs every shot, generates the images, animates each shot and exports an MP4 cut to the audio, with captions when you ask for them. Each video is also a project in the workspace, so it opens in the Scenema studio.

Note

The API is available on the Creator and Pro plans. Requests authenticate with an API key from Settings, API keys (see Authentication).

Quickstart

1. Get the audio. Make a narration with the Narration API and wait until it is completed, or upload your own voiceover or soundtrack with the Assets API. Its id is the video’s audioId, and the video is as long as the audio.

2. Start the video. Find a style with GET /v1/styles (search it by keywords) or on scenema.ai/styles, and pass its slug. Send an Idempotency-Key header: a retried request with the same key returns the same video and never starts a second one.

curl -X POST "https://api.scenema.ai/v1/videos" \
  -H "Authorization: Bearer $SCENEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sky-video-1" \
  -d '{"audioId": "proj_4559d9dd5dc8d53", "style": "pure-ink-whiteboard", "prompt": "Show sunlight scattering in the sky.", "aspectRatio": "16:9", "captions": {"enabled": true}}'

The answer comes back at once with status 202, the video’s id, "status": "processing" and the credits held for it.

3. Fetch it until it is completed. A one minute video usually takes 10 to 15 minutes. Wait 5 to 10 minutes before the first fetch, then ask every 30 to 60 seconds; stage says where it is.

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

Once status is completed, download the MP4 from video.url.

Voice or music

A video follows its audio. With a narration or a voiceover asset, the shots follow what is said: every idea gets its picture, cut on the sentences. With a soundtrack asset, Scenema makes a beat synced explainer instead: it listens to the track first, and the shots are cut on its beats and sections, for a video carried by music rather than a voice. Say what the video is about in prompt.

audioId takes a narration from the Narration API or an asset from the Assets API, uploaded as a file or by link.

Audio is the only input

A video through the API is made from one audio track and a prompt. It takes no documents, slides, images or video. In the Scenema app you can hand the Director any file: a PDF, a deck, a recording, a set of screenshots. It reads them and works out the script and the look with you over a conversation. The API skips that conversation, so its input is the one thing that settles a video without questions: the audio, which fixes what is said and how long the video runs. To start from a script, make the audio first with the Narration API.

In this section

• Videos: creating, fetching and listing videos, their stages and every field they return.
• Styles: list and search the styles, and pick one for a video.
• Change a video: a finished video in another aspect ratio (16:9 or 9:16), a new audio track, or both: PATCH records the change, generate makes it.
• One video, many languages: give a finished video a new audio track in another language, and switch back.
• Failures and retries: error codes, retrying a failed video, and waiting out a provider outage.
• Pricing and limits: how credits are held, charged and returned, and the limits.
• Errors: every error status and code.
• API reference: every endpoint with its schemas.