Skip to main content
POST
Create Narration
Unlike the other endpoints here, narration creates a new run rather than acting on one, so it takes a project_name, project_description and folder_id. Point video_url at the video and set video_type to say what it is. Supply script_file_key to narrate a script you have written, or omit it to have one written for you. narration_type picks between reading a script (narration) and describing what is on screen (audio_description). narrator_voice_id chooses the voice, and remove_fg_audio decides whether the original foreground audio stays under the narration. Track progress by polling /narration/{task_id} with the task_id returned in the response.

Authorizations

x-api-key
string
header
required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Headers

traceparent
string | null

Body

application/json
video_url
string
required

Video to narrate, as a public or bucket URL.

video_type
enum<integer>
required

Where video_url points.

Available options:
0,
1,
2,
3
source_language
integer
required

Language spoken in the video.

narrator_voice_id
integer
required

Voice that reads the narration.

project_name
string | null
Required string length: 3 - 255
project_description
string | null
Required string length: 3 - 5000
folder_id
integer | null
Required range: x > 0
narration_type
enum<string>
default:narration

NARRATION reads a script; AUDIO_DESCRIPTION describes what is on screen.

Available options:
narration,
audio_description
video_id
string | null

Platform video id. Derived from video_url when omitted.

script_file_key
string | null

Bucket key of a narration script. Omit to have one written.

remove_fg_audio
boolean
default:true

Drop the original foreground audio under the narration.

chosen_dictionaries
integer[] | null

Dictionaries applied to the narration.

speech_model
enum<string> | null

Speech model used to read the narration. Same choices as the /tts-stream API (e.g. mars-pro, mars-81, mars-81-flash, mars-instruct). Omit to let the system choose automatically.

Available options:
mars-pro,
mars-81,
mars-8.1-pro-beta,
mars-8.1-flash-beta,
mars-81-flash,
mars-flash,
mars-instruct,
mars-x-instruct,
mars-x.b-instruct

Response

Successful Response

task_id
string | null
required
Last modified on October 22, 2026