Skip to main content
POST
/
story
Create Story
curl --request POST \
  --url https://client.camb.ai/apis/story \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form source_language=1 \
  --form file=@example-file
{
  "task_id": "<string>"
}
Transform your written content into engaging narrated stories with our story creation endpoint. This powerful service takes your text documents and processes them into compelling stories with professional narration. The system handles the entire process from parsing your document to generating a professionally narrated version, making storytelling accessible.

​
The Story Creation Process

When you submit a story creation request, our system begins a multi-stage workflow:
1

Document Processing

Your uploaded text file or Word document is processed and prepared for narration. Our system extracts and analyzes the content, ensuring proper formatting and structure.
2

Voice Selection

Your chosen AI narrator voice is applied to the story, bringing your content to life with natural-sounding speech patterns and appropriate emotional delivery.
3

Audio Production

The narration is finalized with professional audio quality enhancements, ensuring clarity and engagement.
Throughout this process, you can check on your task’s progress using the /story/{task_id} endpoint with the task_id provided in your initial response.

​
Supported Document Formats

Our story creation service accepts two popular document formats to accommodate your workflow:
Document TypeSupported Formats
Text Files.txt
Word Documents.docx
This flexibility allows you to work with your preferred writing tools without conversion hassles.

​
Language Configuration

Specifying the correct source language is crucial for successful story creation. To find the appropriate language identifier:
  1. Query the /source-languages endpoint for a complete list of supported languages.
  2. Use the returned language ID in your request to ensure accurate processing.

​
Creating Your First Story

Let’s look at how to initiate a story creation task with Python: 
import requests
import json

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# Define your story parameters
title = "The Midnight Garden"
description = "A mysterious tale of discovery and wonder"
source_language = 1  # Example: English (check /languages for IDs)
narrator_voice_id = 20299  # Example: Professional male narrator (check voice options)

# Function to submit a story creation request
def create_story(file_path, title, description, source_language, narrator_voice_id):
    """
    Submits a new story creation task and returns the task ID for tracking.

    Parameters:
    - file_path: Path to the .txt or .docx file containing story content
    - title: Title of the story
    - description: Brief description of the story
    - source_language: Language ID for the story content
    - narrator_voice_id: ID of the voice that will narrate the story
    """
    try:
        # Prepare the multipart form data
        files = {
            'file': (file_path.split('/')[-1], open(file_path, 'rb'))
        }

        data = {
            'title': title,
            'description': description,
            'source_language': source_language,
            'narrator_voice_id': narrator_voice_id
        }

        # Submit the request
        response = requests.post(
            "https://client.camb.ai/apis/story",
            headers=headers,
            files=files,
            data=data
        )

        # Verify the request was successful
        response.raise_for_status()

        # Extract the task ID from the response
        result = response.json()
        task_id = result.get("task_id")

        print(f"Story creation task submitted successfully! Task ID: {task_id}")
        return task_id

    except requests.exceptions.RequestException as e:
        print(f"Error submitting story creation task: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None
    finally:
        # Make sure to close the file
        if 'files' in locals() and 'file' in files:
            files['file'][1].close()

# Call the function with your story file
file_path = "path/to/your/story.docx"  # Replace with your actual file path
task_id = create_story(file_path, title, description, source_language, narrator_voice_id)

​
Monitoring Your Story Creation Progress

After submission, your content enters our processing pipeline. The time required depends on the length and complexity of your document. You can check progress by polling the status endpoint: 
def check_story_status(task_id):
    """
    Checks the status of a story creation task.
    Returns the current status and any available result information.

    Parameters:
    - task_id: The ID of the story creation task to check
    """
    if not task_id:
        print("No task ID provided.")
        return None

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/story/{task_id}",
            headers=headers
        )

        # Verify the request was successful
        response.raise_for_status()

        # Parse the status information
        status_data = response.json()
        print(f"Current status: {status_data['status']}")

        # If the story is complete, display the results
        if status_data['status'] == "SUCCESS":
            print("Story creation completed successfully!")
            print(f"Story URL: {status_data.get('story_url')}")

        return status_data

    except requests.exceptions.RequestException as e:
        print(f"Error checking story status: {e}")
        return None

# Check the status of your story creation task
status_info = check_story_status(task_id)

​
Best Practices for Optimal Results

To get the most from our story creation service, consider these professional tips:
  1. Document Quality: Ensure your document is well-formatted with proper grammar and punctuation for better narration results.
  2. Voice Selection: Choose a narrator voice that matches the tone and style of your story content.
  3. Language Accuracy: Double-check that your source language is correctly specified to ensure proper pronunciation and pacing.
  4. Content Length: While our system can handle documents of various lengths, consider breaking very long works into logical segments for optimal processing.
  5. File Format: Use .docx format when you need to preserve complex formatting, and .txt for simpler text-based stories.

​
Practical Applications

Our story creation functionality opens exciting possibilities across industries:
  • Education: Transform educational content into engaging audio lessons for diverse learning styles.
  • Publishing: Quickly create audio versions of books, articles, and short stories.
  • Content Creation: Convert blog posts and articles into narrated content for podcasts or audio platforms.
  • Accessibility: Make written content accessible to visually impaired audiences or those who prefer audio content.
  • Entertainment: Bring original stories to life with professional-quality narration.
By integrating this API into your workflow, you can efficiently transform written content into engaging audio stories, dramatically reducing the time and expense traditionally associated with professional narration while maintaining impressive quality.

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.

Body

multipart/form-data
​
file
file
required

The text file (.txt) or Word document (.docx) containing your story content. This document will be used as the basis for the audio book.

​
source_language
enum<integer>
required

The language of the contents in the input file. This helps our system accurately process and narrate your content.

Available options:
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21,
22,
23,
24,
25,
26,
27,
28,
29,
30,
31,
32,
33,
34,
35,
36,
37,
38,
39,
40,
41,
42,
43,
44,
45,
46,
47,
48,
49,
50,
51,
52,
53,
54,
55,
56,
57,
58,
59,
60,
61,
62,
63,
64,
65,
66,
67,
68,
69,
70,
71,
73,
74,
75,
76,
78,
79,
80,
81,
82,
83,
84,
85,
86,
87,
88,
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
100,
101,
102,
103,
104,
106,
107,
108,
109,
110,
111,
112,
113,
114,
115,
116,
117,
118,
119,
120,
121,
122,
123,
124,
125,
126,
127,
128,
129,
130,
131,
132,
133,
134,
135,
136,
139,
140,
141,
142,
143,
144,
145,
146,
148
​
title
string | null

A descriptive title for your story, making it easier to identify and organize.

Required string length: 3 - 255
​
description
string | null

A brief synopsis of your story, helping to set context and expectations.

Required string length: 3 - 5000
​
narrator_voice_id
integer

The identifier of the AI voice that will narrate your story. This determines the tone, accent, and delivery style.

​
chosen_dictionaries
integer[] | null

An optional list of dictionary IDs selected by the user. Each entry must be an integer corresponding to a valid dictionary ID. If provided, at least one ID is required.

Minimum length: 1
​
project_name
string | null

Enter a distinctive name for your project that reflects its purpose or content. This name will be displayed in your CAMB.AI workspace dashboard and used to organize related assets, transcriptions, etc.. . Choose something memorable that helps you quickly identify this specific project among your other voice, audio and localization tasks.

Required string length: 3 - 255
​
project_description
string | null

Provide details about your project's goals and specifications. Include information such as the target languages for translation or dubbing, desired voice characteristics, emotional tones to capture, or specific audio processing requirements, outlining the workflow here can serve as valuable documentation for organizational purposes.

Required string length: 3 - 5000
​
folder_id
integer | null

Specify the organizational folder within your CAMB.AI workspace where this task should be created and stored. The folder must already exist in your workspace and be accessible through your current API key authentication. This helps maintain project organization by grouping related tasks together, making it easier to manage and locate your projects.

Required range: x >= 1

Response

Successful Response

A JSON that contains the unique identifier for the task. This is used to query the status of the end to end dubbing task that is running. It is returned when a create request is made for a story.

​
task_id
string