Skip to main content
POST
/
story-setup
Setup Story
curl --request POST \
  --url https://client.camb.ai/apis/story-setup \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form file='@example-file' \
  --form source_language=1 \
  --form title=null \
  --form description=null \
  --form narrator_voice_id=123 \
  --form chosen_dictionaries=null \
  --form folder_id=2
{
  "run_id": 1,
  "story_details": {
    "story_title": "<string>",
    "story_description": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "source_language": 1,
    "target_languages": [
      1
    ],
    "folder_id": 1,
    "studio_url": "<string>"
  }
}
Transform your written content into professional audiobook projects with our Story Setup endpoint. This intelligent service bridges the gap between automated project initialization and creative audiobook production, allowing you to programmatically create story projects that seamlessly integrate with CAMB.AI Studio for detailed narration refinement and management. Story Setup differs from direct story creation by building a project workspace rather than producing immediate results. Think of it as preparing a professional editing suite where creative teams can adjust pacing, refine pronunciation, and enhance overall audiobook quality.

​
How it Works

Story Setup handles the technical foundation while preserving creative control. Your API request processes text analysis, configures narrator settings, and creates a Studio workspace with all preparation complete. Creative teams receive a ready-to-edit project rather than starting from raw text files. The workflow naturally divides responsibilities between automated setup and creative refinement, enabling consistent project initialization while maintaining the flexibility needed for high-quality audiobook production.

​
Quick Implementation

import requests

headers = {"x-api-key": "your-api-key"}

def create_audiobook_project(file_path, title, description, source_language, narrator_voice_id):
    """Creates audiobook project workspace in CAMB.AI Studio"""

    files = {'file': open(file_path, "rb")}
    data = {
        'title': title,
        'description': description,
        'source_language': source_language,
        'narrator_voice_id': narrator_voice_id
    }

    try:
        response = requests.post(
            "https://client.camb.ai/apis/story-setup",
            headers=headers, files=files, data=data
        )
        response.raise_for_status()
        result = response.json()

        print(f"Project created! Studio URL: {result.get('story_details', {}).get('studio_url')}")
        return result.get("run_id")

    except requests.exceptions.RequestException as e:
        print(f"Creation failed: {e}")
        return None
    finally:
        files['file'].close()

# Example usage
run_id = create_audiobook_project(
    "story.docx", # Replace with your local file path you are uploading.
    "My Audiobook Project",
    "Adventure story requiring dramatic narration",
    1,  # English
    20299  # Professional narrator
)

​
Essential Configuration

Use clear project names and detailed descriptions to help Studio editors understand your content context and narration requirements. Verify language settings using the source languages endpoint and select narrator voices that match your content’s tone and target audience. Prepare documents with proper formatting and structure, as chapter organization and text quality directly impact the editing workflow. For specialized content with unique terminology, consider preparing pronunciation dictionaries to ensure consistent narration.

​
When to Choose Story Setup

Use Story Setup for collaborative audiobook projects requiring creative refinement, quality control, or complex narration requirements. This endpoint excels when audiobook quality and team collaboration matter more than immediate results. For simple, immediate narrated content without extensive editing needs, consider direct story creation instead. Story Setup provides the foundation for professional audiobook production where creative control and collaborative workflows drive the final 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 array length: 1
​
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

​
run_id
integer

The unique identifier for the run, which was generated during the Story setup process and returned upon task completion.

Required range: x >= 0
​
story_details
object