Narrations

A narration is a script read word for word in one voice. Creating one starts the work and returns at once; the narration moves from processing to completed (or failed), and its audio and transcript appear when it is completed.

Create a narration

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

Body field	Meaning
script	The text to narrate, up to 10,000 characters. It is read exactly as written.
voiceId	A voice id from Voices.
title	Optional name for the narration. Without one it is named after the time it was made.
webhookUrl	Optional https URL that gets narration.completed or narration.failed. See Webhooks.
language	Optional language code of the script. When the script is clearly in another language, the narration follows the script.
transcript	Optional, false by default. true also returns the timing of every word and SRT captions; the narration then completes a few seconds later, once the transcript is ready.

The response has status 202 and the narration with "status": "processing". The credits are charged at this moment; see Pricing and limits.

Get a narration

GET https://api.scenema.ai/v1/narrations/{id} returns the narration. Ask every few seconds while it is processing. This narration was created with "transcript": true; without it, transcript is null.

{
  "id": "proj_4559d9dd5dc8d53",
  "title": "Why the sky is blue",
  "status": "completed",
  "voiceId": "voice_32f5ddf6f108c7",
  "language": "en",
  "characters": 81,
  "createdAt": "2026-10-26T16:03:04.996Z",
  "audio": {
    "url": "https://...",
    "expiresAt": "2026-10-26T17:24:47.630Z",
    "durationMs": 5799,
    "format": "mp3"
  },
  "transcript": {
    "srt": "1\n00:00:00,400 --> 00:00:00,500\nThe\n...",
    "words": [
      { "word": "The", "startMs": 400, "endMs": 500 },
      { "word": "sky", "startMs": 500, "endMs": 1000 }
    ]
  },
  "error": null,
  "studioUrl": "https://scenema.ai/app/studio/proj_4559d9dd5dc8d53"
}

List narrations

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

Narration fields

Field	Meaning
id	The narration id. It is also the id of its project in the studio.
title	The narration’s name.
status	processing, completed or failed.
voiceId, language	The voice and the language of the narration.
characters	Characters in the script.
createdAt	When the narration was created, in ISO 8601.
audio	Set when completed: url, a private link to the MP3 valid for one hour; expiresAt; durationMs; format (mp3). Fetch the narration again for a fresh link, and download the file to keep it.
transcript	Set when completed for a narration created with "transcript": true: srt, captions with one word per cue, and words, each spoken word with startMs and endMs. Otherwise null.
error	Why the narration failed, when status is failed.
studioUrl	The narration’s project in the Scenema studio, where the take can be played, regenerated or used in a video.

Narrations made through the API stay out of the project list in the app, so a busy integration does not crowd it; each one opens from its studioUrl.