🚀 Introducing MARS8 Series — Four Powerful Variants | Available on All Major Clouds | Learn about the model here
🚀 Introducing MARS8 Series — Four Powerful Variants | Available on All Major Clouds | Learn about the model here
Creates a story based on the content provided in a text file (.txt) or Word document (.docx)
curl --request POST \
--url https://client.camb.ai/apis/story \
--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{
"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.Documentation Index
Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
Use this file to discover all available pages before exploring further.
Document Processing
Voice Selection
/story/{task_id} endpoint with the task_id provided in your initial response.
| Document Type | Supported Formats |
|---|---|
| Text Files | .txt |
| Word Documents | .docx |
/source-languages endpoint for a complete list of supported languages.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 = 147320 # Example
# 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)
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)
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.
The text file (.txt) or Word document (.docx) containing your story content. This document will be used as the basis for the audio book.
The language of the contents in the input file. This helps our system accurately process and narrate your content.
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 A descriptive title for your story, making it easier to identify and organize.
3 - 255A brief synopsis of your story, helping to set context and expectations.
3 - 5000The identifier of the AI voice that will narrate your story. This determines the tone, accent, and delivery style.
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.
1Specify 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.
x >= 1Successful 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.
curl --request POST \
--url https://client.camb.ai/apis/story \
--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{
"task_id": "<string>"
}