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

> Translate text into multiple languages with customizable settings for formality, gender, and specialized vocabulary to meet your global communication needs.

This endpoint transforms your source text into fluent, natural-sounding translations in your target language, enabling seamless multilingual communication for your applications. When you provide text along with language preferences and customization options, our system initiates a translation task and returns a unique identifier you can use to track its progress.

## Customizing Your Translation

### Language Selection

For successful translation, you'll need to specify both source and target languages:

* **Source Language**: The original language of your text
* **Target Language**: The language you want your text translated into

To see what's available:

* Check the [`/source-languages`](get-source-languages) or [`/target-languages`](get-target-languages) endpoints for a complete list of supported languages with their corresponding IDs.

### Style and Tone Customization

Our platform offers several ways to tailor translations to your specific audience:

* **Formality**: Adjust the formality level to match your context:
  * Formal (1): Professional communications, official documents
  * Informal (2): Casual conversations, social media content

* **Gender**: Specify grammatical gender preferences when relevant in the target language

* **Age**: Adjust vocabulary and expressions to be age-appropriate for your intended audience

### Domain Expertise

For specialized content, you can enhance accuracy with domain-specific terminology:

* **Chosen Dictionaries**: Include specialized vocabulary dictionaries to ensure technical terms are translated appropriately for fields like medicine, law, technology, or other industries

## How the Process Works

This endpoint uses an asynchronous workflow, allowing your application to continue operations while translation processing happens in the background:

<Steps>
  <Step title="Submit Your Request">
    Send your text array along with language and customization preferences. You can translate multiple text segments in a single request, which is ideal for processing larger documents or batches of content.
  </Step>

  <Step title="Receive Your `task_id`">
    Once your request is submitted, the system immediately returns a unique `task_id`. This identifier lets you check on your translation's progress at any time.
  </Step>

  <Step title="Track Progress of Your Translation">
    Use your `task_id` to monitor the current status of your request by calling the [`/translate/{task_id}`](poll-translation-result) endpoint. This will tell you whether your translation is still in progress, completed, or if any issues occurred.
  </Step>
</Steps>

This asynchronous approach is particularly effective for handling longer texts or processing multiple translations simultaneously without blocking your application's workflow.

## Example: Creating Your First Translation

Here's a practical example showing how to translate business communications from English to Spanish:

```python [expandable] theme={null}
import requests
import time

# Define the translation request
translation_payload = {
    "source_language": 1,     # English
    "target_language": 2,     # Spanish
    "texts": [
        "Thank you for your inquiry about our services.",
        "We would be happy to schedule a meeting next week to discuss your needs in detail.",
        "Please let us know what day works best for you."
    ],
    "formality": 1,           # Formal tone
    "gender": 1,              # Male grammatical forms when applicable
    "age": 30                 # Adult-appropriate language
}

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

# Step 1: Submit your translation request
response = requests.post(
    "https://client.camb.ai/apis/translate",
    json=translation_payload,
    headers=headers
)

# Check if the request was successful
response.raise_for_status()
task_data = response.json()
task_id = task_data["task_id"]
print(f"Translation task created! Task ID: {task_id}")

# Step 2: Check progress until complete
while True:
    status_response = requests.get(
        f"https://client.camb.ai/apis/translate/{task_id}",
        headers=headers
    )
    status_data = status_response.json()
    status = status_data["status"]
    print(f"Status: {status}")

    if status == "SUCCESS":
        run_id = status_data["run_id"]
        break
    elif status == "ERROR":
        print("Translation task failed!")
        break

    # Wait before checking again
    time.sleep(2)

# Step 3: Process your translated text
if status == "SUCCESS":
    print("✨ Translation complete!")
    print(f"Use the `run_id` {task_data.get('run_id')} to fetch your translation.")
```

With this approach, you can efficiently translate content across languages while maintaining appropriate tone, formality, and specialized terminology to ensure your message resonates with its intended audience.


## OpenAPI

````yaml post /translate
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /translate:
    post:
      tags:
        - Apis
      summary: Create Translation
      operationId: translate_translate_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_translate_translate_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
                description: >-
                  A JSON that contains unique identifier for the task. This is
                  used to query the status of the translation task that is
                  running. It is returned when a create request is made for
                  translation.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    Body_translate_translate_post:
      allOf:
        - $ref: '#/components/schemas/CreateTaskWithNameAndDescription'
        - properties:
            source_language:
              $ref: '#/components/schemas/SourceLanguages'
              description: >-
                The original language of your text. This field is required and
                must contain a valid language ID.
            target_language:
              $ref: '#/components/schemas/Languages'
              example: 81
              description: >-
                The language you want your text translated into. This field is
                required and must contain a valid language ID.
            texts:
              type: array
              items:
                type: string
              title: Texts
              description: >-
                An array of strings to be translated. This field is required and
                can contain multiple text segments for batch translation.
            age:
              type: integer
              title: Age
              description: >-
                An integer representing the intended audience age. This helps
                adjust vocabulary and expressions to be age-appropriate, which
                is particularly important when translating content for children,
                teenagers, or specific age demographics.
            formality:
              $ref: '#/components/schemas/Formalities'
              title: Formality
              description: >-
                Specifies whether the translated text should be formal or
                informal. This affects the tone and word choices in languages.
            gender:
              $ref: '#/components/schemas/Gender'
              description: >-
                Specifies grammatical gender preferences when relevant in the
                target language. In many languages, adjectives, nouns, and verbs
                may change form based on gender, and this parameter helps ensure
                the translation uses the appropriate forms.
            chosen_dictionaries:
              $ref: '#/components/schemas/ChosenDictionariesSchema'
              description: ' An optional parameter that allows you to specify specialized vocabulary dictionaries to use during translation. This ensures that technical terms are translated appropriately for specific fields like medicine, law, technology, or other industries.'
          type: object
          required:
            - source_language
            - target_language
            - texts
      title: Body_translate_translate_post
    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
    CreateTaskWithNameAndDescription:
      properties:
        project_name:
          type: string
          title: Project Name
          description: >-
            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.
          minLength: 3
          maxLength: 255
          nullable: true
        project_description:
          type: string
          title: Project Description
          description: >-
            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.
          minLength: 3
          maxLength: 5000
          nullable: true
    SourceLanguages:
      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
        - 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
      default: 1
    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
    Formalities:
      type: integer
      enum:
        - 1
        - 2
      title: Formalities
    Gender:
      type: integer
      enum:
        - 0
        - 1
        - 2
        - 9
      title: Gender
      description: The gender of the speaker.
    ChosenDictionariesSchema:
      type: array
      nullable: true
      items:
        type: integer
      uniqueItems: true
      minItems: 1
      default: null
      description: >-
        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.
    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.

````