Create Translation Stream

POST

translation

stream

Create Translation Stream (Deprecated)

curl --request POST \
  --url https://client.camb.ai/apis/translation/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "source_language": "en-us",
  "target_language": "fr-fr",
  "formality": 2,
  "gender": 1
}
'

import requests

url = "https://client.camb.ai/apis/translation/stream"

payload = {
    "text": "<string>",
    "source_language": "en-us",
    "target_language": "fr-fr",
    "formality": 2,
    "gender": 1
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    source_language: 'en-us',
    target_language: 'fr-fr',
    formality: 2,
    gender: 1
  })
};

fetch('https://client.camb.ai/apis/translation/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/translation/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'source_language' => 'en-us',
    'target_language' => 'fr-fr',
    'formality' => 2,
    'gender' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

"<string>"

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

This endpoint is deprecated. For new integrations, use the standard translation task flow with POST /translation, then poll task status and fetch the completed result.

This endpoint provides instantaneous text translation with adaptive context handling, streaming results character-by-character as they’re processed. This approach enables real-time subtitling, live chat translation, and dynamic content localization without waiting for full document processing.

Customizing Your translation

Contextual Adaptation Parameters

Enhance your translations with linguistic context controls:

Formality Level (Optional):
Setting Value Use Case
Formal 1 Business documents, academic papers, official correspondence
Casual 2 Chat messages, social media, casual communication
Grammatical Gender (Optional): Applies to languages with gender-specific grammar
Setting Value
Not Specified 0
Male 1
Female 2
Neutral 9

Setting	Value	Use Case
Formal	1	Business documents, academic papers, official correspondence
Casual	2	Chat messages, social media, casual communication

Setting	Value
Not Specified	0
Male	1
Female	2
Neutral	9

Language Support

Configure your translation pipeline using:
- /source-languages - Supported input languages
- /target-languages - Available output languages

Implementation Guide

Streaming Translation Workflow:

import requests

translation_config = {
    "text": "Jupiter, the largest planet in our solar system...",
    "source_language": "en-us",  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "target_language": "hi-in",
    "formality": 2,         # Formal
    "gender": 1             # Male grammatical gender
}

def sync_translation_stream(config):
    """Handle translation stream synchronously"""
    headers = {"x-api-key": "your_api_key_here"}

    with requests.post(
        "https://client.camb.ai/apis/translation/stream",
        json=config,
        headers=headers,
        stream=True
    ) as response:

        # Verify successful connection
        response.raise_for_status()

        # Display credit cost
        print(f"Credits required: {response.headers.get('X-Credits-Required', 'Unknown')}")

        # Process stream chunks
        full_translation = ""
        for chunk in response.iter_content(chunk_size=128):
            try:
                decoded = chunk.decode('utf-8')
                full_translation += decoded
                print(decoded, end='', flush=True)
            except UnicodeDecodeError:
                print("�", end='')  # Error placeholder

        return full_translation

# Execute the translation
translated_text = sync_translation_stream(translation_config)
print("\nComplete Translation:\n", translated_text)

import aiohttp
import asyncio

translation_config = {
    "text": "Jupiter, the largest planet in our solar system...",
    "source_language": "en-us",  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "target_language": "hi-in",
    "formality": 2,         # Formal translation
    "gender": 1             # Male grammatical gender
}

async def stream_translation(session, config):
    """Process real-time translation stream"""
    async with session.post(
        "https://client.camb.ai/apis/translation/stream",
        json=config,
        headers={"x-api-key": "your_api_key_here"}
    ) as response:

        # Verify successful stream initiation
        if response.status != 200:
            print(f"Error: {await response.text()}")
            return ""

        # Process stream chunks
        full_translation = ""
        async for chunk in response.content.iter_any():
            try:
                decoded_chunk = chunk.decode('utf-8')
                full_translation += decoded_chunk
                print(decoded_chunk, end='', flush=True)
            except UnicodeDecodeError:
                print("�", end='')  # Error placeholder

        return full_translation

async def main():
    async with aiohttp.ClientSession() as session:
        translated = await stream_translation(session, translation_config)
        print("\nFinal Translation:\n", translated)

asyncio.run(main())

When to use synchronous vs asynchronous:

Use synchronous (requests) for:
- Simple scripts
- Low-concurrency applications
- Quick prototyping
Use asynchronous (aiohttp) for:
- High-performance applications
- Parallel translation streams
- Web servers with async frameworks

Response Handling

Stream Format: UTF-8 encoded text/event-stream with incremental translations.
Credit Tracking: X-Credits-Required header shows computational resources used.
Error Handling: Failed streams immediately terminate with error message.

Use Case Examples

Live Caption Translation: Convert spoken language subtitles in real-time
Chat Localization: Instant message translation for multilingual support teams
Document Preview: Stream translated content while full processing continues

This streaming solution is ideal for applications requiring immediate partial results while maintaining full translation context awareness. The character-level streaming allows for dynamic UI updates and progressive content rendering.

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

text

string

required

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"

formality

enum<integer> | null

default:2

Available options:

1,

2

gender

enum<integer> | null

default:1

The gender of the speaker.

Available options:

0,

1,

2,

9

Response

Text translation stream

The response is of type string.

Last modified on May 25, 2026

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

Create Translation Stream (Deprecated)

curl --request POST \
  --url https://client.camb.ai/apis/translation/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "source_language": "en-us",
  "target_language": "fr-fr",
  "formality": 2,
  "gender": 1
}
'

import requests

url = "https://client.camb.ai/apis/translation/stream"

payload = {
    "text": "<string>",
    "source_language": "en-us",
    "target_language": "fr-fr",
    "formality": 2,
    "gender": 1
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    source_language: 'en-us',
    target_language: 'fr-fr',
    formality: 2,
    gender: 1
  })
};

fetch('https://client.camb.ai/apis/translation/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/translation/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'source_language' => 'en-us',
    'target_language' => 'fr-fr',
    'formality' => 2,
    'gender' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

"<string>"

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Getting Started

Models

Tutorials

SDK Guides

Hosting Platforms

Integrations

API Reference

Other Products

Release Logs

Create Translation Stream

Customizing Your translation

Contextual Adaptation Parameters

Language Support

Implementation Guide

Response Handling

Use Case Examples

Authorizations

Body

Response

​Customizing Your translation

​Contextual Adaptation Parameters

​Language Support

​Implementation Guide

​Response Handling

​Use Case Examples

Authorizations

Body

Response

Customizing Your translation

Contextual Adaptation Parameters

Language Support

Implementation Guide

Response Handling

Use Case Examples