Skip to content
scenemaDocs

Narration API

The Narration API turns a script into studio narration in any Scenema voice. It reads the script word for word and returns an MP3 and its duration and, on request, the timing of every word and captions in SRT. Each narration is also a text-to-speech project in the workspace, so it opens in the Scenema studio like any other.

Base URL

https://api.scenema.ai/v1

Quickstart

1. Pick a voice. Search the library by description, language or gender, and listen to a voice’s sampleUrl:

Terminal window
curl -H "Authorization: Bearer $SCENEMA_API_KEY" \
  "https://api.scenema.ai/v1/voices?q=warm%20documentary%20narrator&language=en&perPage=5"

2. Start the narration.

Terminal window
curl -X POST "https://api.scenema.ai/v1/narrations" \
  -H "Authorization: Bearer $SCENEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voiceId": "voice_32f5ddf6f108c7", "title": "Why the sky is blue", "script": "The sky looks blue because air scatters blue sunlight more than any other colour."}'

The answer comes back at once with status 202, the narration’s id and "status": "processing".

3. Fetch it until it is completed.

Terminal window
curl -H "Authorization: Bearer $SCENEMA_API_KEY" \
  "https://api.scenema.ai/v1/narrations/proj_4559d9dd5dc8d53"

A short script finishes in a few seconds and a long one within a few minutes. Ask again every few seconds until status is completed or failed, then download the MP3 from audio.url.

The same flow in JavaScript:

const api = 'https://api.scenema.ai/v1';
const headers = { Authorization: `Bearer ${process.env.SCENEMA_API_KEY}`, 'Content-Type': 'application/json' };


const started = await fetch(`${api}/narrations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ voiceId: 'voice_32f5ddf6f108c7', script: 'The sky looks blue because air scatters blue sunlight.' }),
}).then((r) => r.json());


let narration = started;
while (narration.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  narration = await fetch(`${api}/narrations/${started.id}`, { headers }).then((r) => r.json());
}
console.log(narration.status, narration.audio?.url);

From your assistant

To make narration from Claude, ChatGPT, Cursor or Claude Code instead of code, connect the narration MCP at https://mcp.scenema.ai/audio. It carries the same steps as this API: pick a voice, save the script, record it and fetch the audio. See MCP, Narration.

In this section

  • Voices: listing and searching the voice library and the workspace’s cloned voices.
  • Narrations: creating, fetching and listing narrations, and every field they return.
  • Pricing and limits: what a narration costs and how long a script can be.
  • Errors: every error status and code.
  • API reference: every endpoint with its parameters, request and response schemas, generated from the API’s OpenAPI document.