Skip to main content
POST
/
translate
Create Translation
curl --request POST \
  --url https://client.camb.ai/apis/translate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "source_language": "en-us",
  "target_language": "fr-fr",
  "texts": [
    "<string>"
  ],
  "project_name": "<string>",
  "project_description": "<string>",
  "age": 123,
  "chosen_dictionaries": null
}
'
{
  "task_id": "<string>"
}

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.

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:

​
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:
1

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

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

Track Progress of Your Translation

Use your task_id to monitor the current status of your request by calling the /translate/{task_id} endpoint. This will tell you whether your translation is still in progress, completed, or if any issues occurred.
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: 
import requests
import time

# Define the translation request
translation_payload = {
    "source_language": "en-us",  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "target_language": "es-es",
    "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.

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

application/json
​
source_language
string
required

The language of the input text. Pass a locale tag (en-us, fr-fr, es-es). Numeric language IDs (1 or "1") still work but are deprecated. See all source languages.

Example:

"en-us"

​
target_language
string
required

The target output language. Pass a locale tag (fr-fr, es-es, de-de). Numeric language IDs still work but are deprecated. See all target languages.

Example:

"fr-fr"

​
texts
string[]
required

An array of strings to be translated. This field is required and can contain multiple text segments for batch translation.

​
project_name
string | null

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.

Required string length: 3 - 255
​
project_description
string | null

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.

Required string length: 3 - 5000
​
age
integer

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
enum<integer>

Specifies whether the translated text should be formal or informal. This affects the tone and word choices in languages.

Available options:
1,
2
​
gender
enum<integer>

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.

Available options:
0,
1,
2,
9
​
chosen_dictionaries
integer[] | null

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.

Minimum array length: 1

Response

Successful Response

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.

​
task_id
string