Stories

Turn a text or Word document into narrated audio using the Python or TypeScript SDK

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

   Python

   pip install camb-sdk
   

   npm install @camb-ai/sdk
   

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

4. Set your API key to use in your code

   export CAMB_API_KEY="your_api_key_here"
   

---

Code

Python

import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

def narrate_story():
    # Replace with your story file (.txt or .docx)
    story_path = "story.txt"

    # Step 1: Submit the story job (multipart upload)
    response = client.story.create_story(
        file=open(story_path, "rb"),
        source_language=Languages.EN_US,
        title="My Story",
        description="Sample narrated story",
        narrator_voice_id=147320,
    )

    # Usually returns task_id for async processing (see Note below)
    task_id = getattr(response, "task_id", None)
    if not task_id:
        print("No task_id on response; if you received run_id directly, skip polling and call get_story_run_info.")
        return

    print(f"Story task created: {task_id}")

    # Step 2: Poll until complete
    max_attempts = 60
    attempt = 0
    while attempt < max_attempts:
        status = client.story.get_story_status(task_id=task_id)
        print(f"Status: {status.status}")

        if status.status == "SUCCESS":
            # Step 3: Full narration, dialogue track, optional transcript
            result = client.story.get_story_run_info(
                status.run_id,
                include_transcript=True,
            )
            print(f"Audio URL: {result.get('audio_url')}")
            print(f"Dialogue URL: {result.get('dialogue_url')}")
            transcript = result.get("transcript")
            if transcript:
                for row in transcript[:2]:
                    print(f"[{row.get('start')}-{row.get('end')}ms] {row.get('speaker')}: {row.get('text')}")
            break
        elif status.status == "ERROR":
            print(f"Story failed: {status.exception_reason}")
            break

        time.sleep(5)
        attempt += 1

narrate_story()

import { CambClient, CambApi } from '@camb-ai/sdk';
import * as fs from 'fs';

const client = new CambClient({
    apiKey: process.env.CAMB_API_KEY
});

async function narrateStory() {
    const storyPath = 'story.txt'; // Replace with your .txt or .docx

    if (!fs.existsSync(storyPath)) {
        console.error('Story file not found:', storyPath);
        return;
    }

    // Step 1: Submit the story job (multipart upload)
    const response = await client.story.createStory({
        file: fs.createReadStream(storyPath),
        source_language: CambApi.Languages.EN_US,
        title: 'My Story',
        description: 'Sample narrated story',
        narrator_voice_id: 147320
    });

    // Usually returns task_id for async processing (see Note below)
    const taskId = 'task_id' in response && response.task_id ? response.task_id : null;
    if (!taskId) {
        console.error('No task_id on response; if you received run_id directly, skip polling and call getStoryRunInfo.');
        return;
    }

    console.log(`Story task created: ${taskId}`);

    // Step 2: Poll until complete
    const maxAttempts = 60;
    let attempt = 0;

    while (attempt < maxAttempts) {
        const status = await client.story.getStoryStatus({
            task_id: taskId
        });

        console.log(`Status: ${status.status}`);

        if (status.status === 'SUCCESS') {
            // Step 3: Full narration, dialogue track, optional transcript
            const result = await client.story.getStoryRunInfo({
                run_id: status.run_id,
                include_transcript: true
            });

            console.log(`Audio URL: ${result['audio_url']}`);
            console.log(`Dialogue URL: ${result['dialogue_url']}`);
            const transcript = result['transcript'];
            if (Array.isArray(transcript)) {
                for (const row of transcript.slice(0, 2)) {
                    const r = row;
                    console.log(
                        `[${r['start']}-${r['end']}ms] ${r['speaker']}: ${r['text']}`
                    );
                }
            }
            break;
        } else if (status.status === 'ERROR') {
            console.error(`Story failed: ${status.exception_reason}`);
            break;
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
        attempt++;
    }

    if (attempt >= maxAttempts) {
        console.error('Timeout waiting for story completion.');
    }
}

narrateStory();

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

Parameter	Type	Description
file	file stream	.txt or .docx content to narrate
source_language	Languages enum	Language 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

Parameter	Type	Description
title	string	Story title
description	string	Short description
narrator_voice_id	integer	Voice ID for the narrator (use list voices or pick one from Text to Speech)
folder_id	integer	Folder for organizing the run
chosen_dictionaries	integer[]	Custom pronunciation dictionaries
run_id	integer	Optional 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.