> ## 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.

# Create Translated Story

> Creates a translated story based on a previously generated story using the provided `run_id`

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Quality Assurance">
    The translated story undergoes final checks to ensure audio quality, proper pacing, and narrative integrity in the new language.
  </Step>
</Steps>

Throughout this process, you can check on your task's progress using the [`/translated-story/{task_id}`](get-translated-story-status) 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`](get-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:

```python [expandable] theme={null}
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:

```python [expandable] theme={null}
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.


## OpenAPI

````yaml post /translated-story/{run_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /translated-story/{run_id}:
    post:
      tags:
        - Apis
        - Stories
      summary: Create Translated Story
      operationId: create_translation_for_existing_story__run_id__post
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/RunIDParam'
          description: >-
            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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranslatedStoryRequestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
                description: >-
                  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.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    RunIDParam:
      type: integer
      title: Run ID
      description: >-
        The unique identifier for the run, which was generated during the
        creation process and returned upon task completion.
    CreateTranslatedStoryRequestPayload:
      type: object
      properties:
        target_language:
          $ref: '#/components/schemas/Languages'
          title: Target Language
          description: >-
            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.
    TaskID:
      properties:
        task_id:
          type: string
          title: Task ID
      type: object
      title: Task ID
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Languages:
      type: integer
      enum:
        - 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
      title: Languages
      default: 1
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        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.

````