Skip to main content
POST
/
translated-story
/
{run_id}
Create Translated Story
curl --request POST \
  --url https://client.camb.ai/apis/translated-story/{run_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "target_language": 1
}
'
{
  "task_id": "<string>"
}
Expand your storytelling to global audiences with our comprehensive translation service. This powerful endpoint transforms your previously created stories into new languages, allowing your content to reach diverse linguistic communities. The system handles everything from translation to voice synthesis, delivering professional-quality results that preserve the original story’s essence while adapting it naturally to the target language.

​
The Translation Process

When you submit a story translation request, our system begins a sophisticated workflow:
1

Original Story Retrieval

Using your provided run_id, our system locates and retrieves your previously generated story, ensuring we’re working with the complete content.
2

Professional Translation

The story content is expertly translated to your target language using our proprietary translation engine, carefully preserving narrative flow, tone, and cultural nuances.
3

Voice Selection and Synthesis

Our system selects appropriate voices for the target language that match the character of the original narration, then generates natural-sounding audio.
4

Quality Assurance

The translated story undergoes final checks to ensure audio quality, proper pacing, and narrative integrity in the new language.
Throughout this process, you can check on your task’s progress using the /translated-story/{task_id} endpoint with the task_id provided in your initial response.

​
Language Selection

Choosing the right target language is essential for effective story translation. Our system supports over 148 languages, giving you incredible global reach. To specify your desired language:
  1. Use the appropriate language ID in your request (an integer value between 1 and 148).
  2. For a complete list of supported languages and their corresponding IDs, query the /languages endpoint.
This ensures our system correctly processes your content for the intended audience.

​
Creating Your First Translated Story

Let’s examine how to initiate a story translation task using Python: 
import requests
import json

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json"
}

# Define your translation request parameters
def translate_story(run_id, target_language):
    """
    Submits a new story translation task and returns the task ID for tracking.

    Parameters:
    - run_id: The ID of the original story to translate
    - target_language: The ID of the target language (check /languages for IDs)
    """
    try:
        # Prepare the request body
        payload = {
            "target_language": target_language
        }

        # Submit the translation request
        response = requests.post(
            f"https://client.camb.ai/apis/translated-story/{run_id}",
            headers=headers,
            data=json.dumps(payload)
        )

        # 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 translation task submitted successfully! Task ID: {task_id}")
        return task_id

    except requests.exceptions.RequestException as e:
        print(f"Error submitting story translation task: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None

# Example usage
run_id = 12345  # Replace with your actual run_id
target_language = 5  # Example: Spanish (check /languages for IDs)
task_id = translate_story(run_id, target_language)

​
Monitoring Your Translation Progress

After submission, your story enters our translation pipeline. You can monitor the progress by polling the status endpoint: 
def check_translation_status(task_id):
    """
    Checks the status of a story translation task.
    Returns the current status and any available result information.

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

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/translated-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 translation is complete, display the results
        if status_data['status'] == "SUCCESS":
            print("Story translation completed successfully!")
            print(f"Translated story URL: {status_data.get('story_url')}")

        return status_data

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

# Check the status of your translation task
status_info = check_translation_status(task_id)

​
Best Practices for Optimal Results

To achieve the best possible translations of your stories, consider these professional recommendations:
  1. Original Quality: Ensure your source story is of high quality, as the translation will preserve any issues present in the original.
  2. Cultural Considerations: Some stories may contain cultural references that don’t translate directly. Consider this when selecting target languages.
  3. Language Pairing: Some language pairs translate more smoothly than others. When possible, start with content that will translate well to your target language.
  4. Sequential Translation: For best results, translate directly from the original language rather than creating “translations of translations.”
  5. Test Translations: Consider testing with shorter stories first to ensure the target language delivers the tone and style you’re seeking.

​
Practical Applications

Our story translation functionality enables exciting opportunities across various fields:
  • Global Education: Make educational stories accessible to learners worldwide in their native languages.
  • Publishing: Quickly expand your literary works to international markets without the traditional translation timeline.
  • Cultural Exchange: Share folktales and cultural narratives across language barriers, fostering global understanding.
  • Language Learning: Create parallel versions of stories for language learners to compare with original texts.
  • International Marketing: Adapt brand stories and narratives for diverse global audiences.
By integrating this translation capability into your workflow, you can efficiently extend your storytelling reach across linguistic boundaries, dramatically reducing the time and resources traditionally required for multilingual content creation while maintaining impressive quality and authenticity.

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.

Path Parameters

​
run_id
integer
required

The unique identifier of the original story you want to translate. This ID was generated during the original story creation process and returned upon task completion. The unique identifier for the run, which was generated during the creation process and returned upon task completion.

Body

application/json
​
target_language
enum<integer>

The language ID for the language you want your story translated into. This determines the text translation and the language in which the story will be narrated.

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,
72,
73,
74,
75,
76,
77,
78,
79,
80,
81,
82,
83,
84,
85,
86,
87,
88,
89,
90,
91,
92,
93,
94,
95,
96,
97,
98,
99,
100,
101,
102,
103,
104,
105,
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,
147,
148,
149,
150

Response

Successful Response

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

​
task_id
string