Skip to main content

Overview

Upload a .txt or .docx manuscript and produce narrated audio: full narration, an optional dialogue-only track, and optionally a time-coded transcript. Pick the narrator voice and source language, then run an asynchronous job and fetch URLs when it completes.

Prerequisites

1

Create an account

Sign up at CAMB.AI Studio if you haven’t already.
2

Get your API key

Go to Settings β†’ API Keys in Studio and copy your key. See Authentication for details.
3

Install the SDK

Skip this step if you’re using the direct API.
4

Set your API key to use in your code


Code

create_story / createStory may return either a task_id (poll as above) or, in some flows, a run_id immediately. If you already have run_id, call get_story_run_info / getStoryRunInfo without polling.

Parameters

Required

ParameterTypeDescription
filefile stream.txt or .docx content to narrate
source_languageLanguages enumLanguage of the manuscript (e.g. Languages.EN_US). The raw API also accepts locale-tag strings like "en-us"; numeric IDs still work but are deprecated.

Optional

ParameterTypeDescription
titlestringStory title
descriptionstringShort description
narrator_voice_idintegerVoice ID for the narrator (use list voices or pick one from Text to Speech)
folder_idintegerFolder for organizing the run
chosen_dictionariesinteger[]Custom pronunciation dictionaries
run_idintegerOptional tracing / linkage

Tips

  • Formats: Use .txt or .docx as described in the Create Story reference.
  • Languages: Use the SDK Languages enum (e.g. Languages.EN_US) for source_language. The raw API also accepts locale-tag strings like "en-us". See Get source languages for the full list.
  • URLs: Download links from audio_url and dialogue_url expire after 24 hoursβ€”fetch and store files promptly.
  • Polling: Cap your loop (for example 60 attempts Γ— 5 seconds) and handle timeouts separately from ERROR status.

Next Steps

Create Story API

Multipart upload and story parameters.

Get Story Status

Poll with task_id.

Get Story Run Info

audio_url, dialogue_url, and optional transcript.

Text to Speech

Generate speech and explore voices for narrator_voice_id.