# How Tasks & Runs Work
Source: https://docs.camb.ai/api-reference/basics/tasks-and-runs

Understand the asynchronous task pattern used across CAMB.AI APIs

Most CAMB.AI APIs use an **asynchronous task pattern** that allows your application to submit requests and continue working while processing happens in the background. This guide explains how tasks and runs work.

## The Task Lifecycle

<Steps>
  <Step title="Submit a Request">
    Send your data (text, audio, video) to a creation endpoint. The API immediately returns a `task_id`.
  </Step>

  <Step title="Poll for Status">
    Use the `task_id` to check progress. The task moves through states: `PENDING` → `SUCCESS` (or `ERROR`).
  </Step>

  <Step title="Get the Result">
    Once the status is `SUCCESS`, you receive a `run_id`. Use this to download your result.
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant API as CAMB.AI API

    App->>API: POST /tts (submit text)
    API-->>App: { task_id: "abc123" }

    loop Until SUCCESS
        App->>API: GET /tts/{task_id}
        API-->>App: { status: "PENDING" }
    end

    App->>API: GET /tts/{task_id}
    API-->>App: { status: "SUCCESS", run_id: "xyz789" }

    App->>API: GET /tts-result/{run_id}
    API-->>App: [audio data]
```

## Task vs Run

| Concept  | Description                    | ID        |
| -------- | ------------------------------ | --------- |
| **Task** | A job submitted for processing | `task_id` |
| **Run**  | The completed result of a task | `run_id`  |

A task represents your request being processed. Once complete, the result becomes a run that you can download or reference.

## Task Status Types

| Status             | Meaning                        | Action                         |
| ------------------ | ------------------------------ | ------------------------------ |
| `PENDING`          | Processing in progress         | Continue polling               |
| `SUCCESS`          | Completed successfully         | Retrieve result using `run_id` |
| `ERROR`            | Processing failed              | Check error message, retry     |
| `TIMEOUT`          | Processing exceeded time limit | Break into smaller requests    |
| `PAYMENT_REQUIRED` | Insufficient credits           | Add credits to account         |

## Example: Complete Workflow

Here's a complete example showing the task pattern for text-to-speech:

```python theme={null}
import requests
import time

API_KEY = "your-api-key"
BASE_URL = "https://client.camb.ai/apis"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

# Step 1: Submit the task
response = requests.post(
    f"{BASE_URL}/tts",
    headers=headers,
    json={
        "text": "Hello, this is a test of the task system.",
        "voice_id": 147320,
        "language": "en-us"  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    }
)
task_id = response.json()["task_id"]
print(f"Task submitted: {task_id}")

# Step 2: Poll for completion
while True:
    status_response = requests.get(
        f"{BASE_URL}/tts/{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 in ["ERROR", "TIMEOUT", "PAYMENT_REQUIRED"]:
        print(f"Task failed: {status}")
        exit(1)

    time.sleep(2)  # Wait before polling again

# Step 3: Download the result
result_response = requests.get(
    f"{BASE_URL}/tts-result/{run_id}",
    headers=headers,
    stream=True
)

with open("output.wav", "wb") as f:
    for chunk in result_response.iter_content(chunk_size=1024):
        if chunk:
            f.write(chunk)

print(f"Audio saved! Run ID: {run_id}")
```

## Polling Best Practices

<AccordionGroup>
  <Accordion title="Use appropriate intervals">
    Start with 2-5 second intervals. Shorter tasks (TTS) complete faster than longer ones (dubbing).
  </Accordion>

  <Accordion title="Implement exponential backoff">
    For longer tasks, increase the polling interval over time to reduce API calls.
  </Accordion>

  <Accordion title="Set a maximum timeout">
    Don't poll forever. Set a maximum wait time and handle timeouts gracefully.
  </Accordion>

  <Accordion title="Handle all status types">
    Always handle `ERROR`, `TIMEOUT`, and `PAYMENT_REQUIRED` statuses in your code.
  </Accordion>
</AccordionGroup>

## Bulk Operations

For processing multiple items, use the bulk fetch endpoints:

```python theme={null}
# Fetch multiple results at once
response = requests.post(
    f"{BASE_URL}/fetch-tts-results",
    headers=headers,
    json={
        "run_ids": [123, 456, 789]
    }
)
results = response.json()
```

## APIs Using This Pattern

Most CAMB.AI APIs follow the task pattern:

| API            | Create                     | Status                              | Result                               |
| -------------- | -------------------------- | ----------------------------------- | ------------------------------------ |
| Text-to-Speech | `POST /tts`                | `GET /tts/{task_id}`                | `GET /tts-result/{run_id}`           |
| Translation    | `POST /translation`        | `GET /translation/{task_id}`        | `GET /translation-result/{run_id}`   |
| Transcription  | `POST /transcription`      | `GET /transcription/{task_id}`      | `GET /transcription-result/{run_id}` |
| Subtitles      | `POST /sub`                | `GET /sub/{task_id}`                | `GET /sub-result/{run_id}`           |
| Dubbing        | `POST /end-to-end-dubbing` | `GET /end-to-end-dubbing/{task_id}` | `GET /dubbed-run-info/{run_id}`      |
| Stories        | `POST /create-story`       | `GET /story/{task_id}`              | `GET /story-run/{run_id}`            |

## Streaming Alternative

For real-time applications, some APIs offer streaming endpoints that return data immediately without the task pattern:

* `POST /tts-stream` - Streaming text-to-speech
* `POST /translation/stream` - Deprecated streaming translation. Use `POST /translation` for new integrations.

Use streaming when you need immediate response and can process audio chunks as they arrive.

## Next Steps

<CardGroup>
  <Card title="SDK Guide" icon="code" href="/sdk-guides/general-guide">
    SDKs handle polling automatically
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/create-tts">
    Explore all endpoints
  </Card>
</CardGroup>


# Add Term to Dictionary
Source: https://docs.camb.ai/api-reference/endpoint/add-term-to-dictionary

post /dictionaries/{dictionary_id}/add-term
Adds a new term and its translations to an existing dictionary, enabling you to expand your multilingual terminology database with precise linguistic mappings.

This endpoint serves as your gateway to enriching dictionaries with new linguistic content. When you need to expand a dictionary's vocabulary, whether you're building a comprehensive translation resource or maintaining specialized terminology for your domain, this endpoint provides the mechanism to seamlessly add term-translation pairs that enhance your multilingual capabilities.
Think of this process as carefully placing a new entry into a physical dictionary, but with the added power of digital precision and immediate availability across all your applications. Each term you add becomes instantly searchable and usable through other dictionary endpoints, creating a growing repository of linguistic knowledge that serves your users' translation and terminology needs.

## The Update-Centric Approach

Notice that the operation summary describes this as "Update Term Translation In Dictionary Using Term ID" rather than simply "Add Term." This distinction reveals important architectural decisions about how the system handles dictionary content. Rather than treating each operation as creating entirely new database records, the system views term additions as updates to existing term structures.
This approach offers several advantages for dictionary management. It allows for versioning of translations, supports scenarios where terms need refinement over time, and provides mechanisms for tracking the evolution of linguistic content. When you "add" a term, you might actually be adding a new translation variant to an existing term concept, or updating existing translations with improved accuracy.

## Quality Considerations for Translation Content

Adding terms to dictionaries involves inherent quality considerations that go beyond technical correctness. Translation accuracy, cultural appropriateness, and consistency with existing dictionary content all influence the long-term value of your linguistic resources.
When designing term addition workflows, consider implementing validation steps that help ensure translation quality. This might involve requiring multiple translation variants, providing fields for usage examples or context information, or implementing review processes where translation additions require approval before becoming available to end users.


# Create Audio Separation
Source: https://docs.camb.ai/api-reference/endpoint/create-audio-separation

post /audio-separation
Creates a task to separate an audio file into distinct background and foreground components

Transform your mixed content into clean, isolated components with our powerful audio separation system. This innovative endpoint enables you to extract distinct foreground elements (such as vocals or lead instruments) from background elements (like accompaniment or ambient sounds). Whether you're producing music, cleaning up recordings, creating remixes, or developing audio-focused applications, this capability allows you to deconstruct complex media files into their fundamental components for enhanced control and creative flexibility.

<Tip>For optimal separation quality, we recommend using media files with minimal compression and clear distinction between foreground and background elements. Higher quality input files generally produce better separation results.</Tip>

## The Audio Separation Process

When you submit an audio separation request, our system begins a sophisticated workflow:

<Steps>
  <Step title="Task Creation">
    The system registers your request and establishes a dedicated processing task, returning a unique task identifier (`task_id`) that you'll use to track and retrieve your separated audio components.
  </Step>

  <Step title="Audio Analysis">
    Our advanced audio processing algorithms analyze the spectral and temporal characteristics of your audio file, identifying patterns that distinguish foreground from background elements.
  </Step>

  <Step title="Component Separation">
    Using specialized neural networks, the system carefully separates the audio into distinct foreground and background stems while preserving the acoustic quality of each component.
  </Step>
</Steps>

Throughout this process, you can monitor the status of your separation task by polling the [`/audio-separation/{task_id}`](get-audio-separation-status) endpoint with the `task_id` provided in your initial response.

## Creating Your First Audio Separation Request

Let's examine how to initiate an audio separation task using Python:

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

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

def create_audio_separation(media_file_path):
    """
    Submits a new audio separation task and returns the task ID for tracking.

    Parameters:
    - media_file_path: Path to the audio file you want to separate
    """
    try:
        # Prepare the multipart form data with the audio file
        files = {
            "media_file": (media_file_path.split('/')[-1], open(media_file_path, "rb"))
        }

        # Submit the separation request
        response = requests.post(
            "https://client.camb.ai/apis/audio-separation",
            headers=headers,
            files=files
        )

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

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

# Example usage
audio_path = "path/to/your/audio/file.mp3"
task_id = create_audio_separation(audio_path)
```

## Monitoring Your Separation Progress

After submission, your audio separation task enters our processing pipeline. You can monitor the progress by polling the status endpoint:

```python [expandable] theme={null}
def check_separation_status(task_id):
    """
    Checks the status of an audio separation task.
    Returns the current status and any available result information.

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

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/audio-separation/{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 separation is complete, display the results
        if status_data['status'] == "SUCCESS":
            print("Audio separation completed successfully!")
            print(f"Foreground audio URL: {status_data.get('foreground_url')}")
            print(f"Background audio URL: {status_data.get('background_url')}")

        return status_data

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

# Check the status of your separation task
status_info = check_separation_status(task_id)
```

## Supported Audio Formats

Our audio separation system supports a variety of common audio formats to accommodate your workflow needs:

* **FLAC** (Free Lossless Audio Codec) - Ideal for high-quality lossless audio
* **MP3** (MPEG Audio Layer III) - Common compressed format widely supported across platforms
* **WAV** (Waveform Audio File Format) - Uncompressed audio format with excellent quality
* **AAC** (Advanced Audio Coding) - High-quality compressed format commonly used in mobile devices

## Best Practices for Audio Separation

To achieve the highest quality separation results, consider these professional recommendations:

1. **Use High-Quality Sources**: Whenever possible, use uncompressed (WAV) or lossless (FLAC) audio for separation.

2. **Optimal Length**: While the system can handle various durations, files between 10 seconds and 10 minutes typically yield the best results.

3. **Clear Recording**: Audio with minimal background noise, distortion, or heavy effects will separate more cleanly.

4. **Balanced Mix**: Ensure that both foreground and background elements are audible in the original mix for best separation.

5. **Consider Preprocessing**: For challenging audio, consider using noise reduction or equalization before submission to improve separation quality.


# Create a Custom Voice
Source: https://docs.camb.ai/api-reference/endpoint/create-custom-voice

post /create-custom-voice
Creates a new voice clone by uploading an audio file reference.

## Understanding Voice Cloning Technology

This endpoint empowers you to create personalized synthetic voices by leveraging our advanced voice cloning technology. When you submit an audio sample, our system analyzes the unique vocal characteristics of the speaker—including pitch, timbre, rhythm, and other subtle qualities—and generates a digital voice model that can speak any text with those same characteristics. This process effectively "clones" the voice from your sample, enabling you to create custom content that maintains the distinctive vocal identity of the original speaker.

<Tip>
  For optimal cloning results:

  * Provide a clear, high-quality recording with minimal background noise.
  * The audio should feature natural speech patterns at a consistent pace and volume.
  * Samples of 30-60 seconds typically provide sufficient data for accurate voice modeling.
</Tip>

## The Voice Cloning Process

When you submit your request to this endpoint, several sophisticated processes occur:

1. **Audio Analysis**: Our system processes your audio file, identifying the core vocal characteristics that make the voice unique.

2. **Feature Extraction**: The system extracts key vocal features, including pitch range, tonal qualities, speech cadence, and articulation patterns.

3. **Voice Model Creation**: These extracted features are used to build a voice model that can synthesize new speech matching the original voice's characteristics.

4. **Voice Registration**: The newly created voice is registered in your account and assigned a unique identifier for future use in text-to-speech operations.

Once complete, your custom voice becomes immediately available for use across our platform.

## Audio Sample Recommendations

The quality of your custom voice depends significantly on the quality of your audio sample. Consider these factors when preparing your sample:

1. **Content Quality**:
   * Record in a quiet environment with minimal background noise or echo
   * Use a good quality microphone positioned at an appropriate distance
   * Maintain consistent volume and speaking pace throughout the recording
   * Avoid vocal strains, forced expressions, or unnatural speech patterns

2. **Content Selection**:
   * Choose text with diverse phonetic content that exercises different sounds
   * Include a variety of sentence structures and intonation patterns
   * Select content similar to what you'll ultimately want the voice to produce
   * Avoid highly technical terms unless they're essential to your use case

3. **Sample Duration**:
   * Aim for 30-60 seconds of clean audio at minimum
   * Longer samples (2-3 minutes) can provide better results for more complex use cases
   * Very short samples (15 seconds) may produce less consistent voice clones

Following these guidelines will help ensure that the resulting voice clone accurately captures the essence of the original speaker's voice.

## Implementation Example

Here's a comprehensive Python example that demonstrates how to create a custom voice, including proper error handling:

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

def create_custom_voice(file_path, voice_name, gender, age, description=None, language=None):
    """
    Creates a custom voice clone from an audio sample

    Parameters:
        file_path (str): Path to the audio file containing the voice sample
        voice_name (str): Name to assign to the custom voice
        gender (int): Gender identifier (1=male, 2=female, etc.)
        age (int): Approximate age of the speaker
        description (str, optional): Detailed description of the voice
        language (str, optional): Language code of the voice (e.g., "en-US")

    Returns:
        dict: Response from the API containing voice details
    """
    # Validate file exists
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Audio file not found at: {file_path}")

    # Prepare file for upload
    files = {'file': open(file_path, 'rb')}

    # Prepare metadata
    data = {
        'voice_name': voice_name,
        'gender': gender,
        'age': age
    }

    # Add optional parameters if provided
    if description:
        data['description'] = description
    if language:
        data['language'] = language

    try:
        # Make API request
        response = requests.post(
            "https://client.camb.ai/apis/create-custom-voice",
            files=files,
            data=data,
            headers={
                "x-api-key": os.environ.get("API_KEY")  # Get API key from environment variable
            }
        )

        # Close file handle
        files['file'].close()

        # Check for errors
        response.raise_for_status()

        # Return response data
        return response.json()

    except requests.exceptions.HTTPError as http_err:
        print(f"HTTP error occurred: {http_err}")
        if response.text:
            print(f"Response details: {response.text}")
        return None
    except Exception as err:
        print(f"Error creating custom voice: {err}")
        return None
    finally:
        # Ensure file is closed even if an error occurs
        if 'file' in files and not files['file'].closed:
            files['file'].close()

# Example usage
if __name__ == "__main__":
    result = create_custom_voice(
        file_path="narrator_sample.wav",
        voice_name="Professional Narrator",
        gender=1,
        age=45,
        description="Clear, articulate voice with professional tone. Ideal for documentary narration.",
        language="en-us"  # Locale tag. Numeric IDs (e.g. "1") still work but are deprecated.
    )

    if result:
        print(f"Custom voice created successfully with ID: {result['voice_id']}")
```

## Working with Your Custom Voice

After successfully creating a custom voice, you can use it for various speech synthesis tasks:

1. **Text-to-Speech Conversion**: Use the voice ID with the [`/tts`](create-tts) endpoint to convert text to speech in your custom voice.

2. **Voice Management**: Find your custom voice in the list returned by the [`/list-voices`](list-voices) endpoint, alongside public and shared voices.

3. **Voice Updates**: If needed, you can create a new version of the voice by submitting a new request with the same voice name but a different audio sample.

4. **Voice Publishing**: If you initially created a private voice but later wish to share it, you can use our voice update endpoints to change its publication status.

Custom voices remain associated with your account indefinitely unless explicitly deleted, giving you a persistent library of voices for your various speech synthesis needs.

## Use Cases for Custom Voices

Creating custom voices opens up numerous possibilities for personalized content:

* **Brand Consistency**: Create a consistent voice identity across all your digital touchpoints
* **Character Development**: Build unique voices for characters in games, animations, or interactive experiences
* **Personalized Communication**: Generate content that sounds like a specific individual (with appropriate permissions)
* **Accessibility Solutions**: Create synthetic versions of a person's voice for use in assistive technology
* **Multilingual Content**: Clone a voice and use it to speak multiple languages while maintaining the same vocal identity

By understanding the possibilities, you can better strategize how custom voices might enhance your specific applications and user experiences.

## Ethical Considerations

When creating and using custom voices, please consider these ethical guidelines:

1. Always obtain proper consent from the person whose voice you are cloning
2. Use voice clones respectfully and avoid creating misleading content
3. Clearly identify synthesized speech when there might be confusion about its origin
4. Follow applicable laws and regulations regarding biometric data and privacy

Responsible use of voice cloning technology helps ensure its continued availability while respecting individual rights and social norms.


# Create a Dictionary From File
Source: https://docs.camb.ai/api-reference/endpoint/create-dictionary-from-file

post /dictionaries/create-from-file
This endpoint empowers you to build custom pronunciation and terminology dictionaries by uploading structured data files directly into your CAMB.AI workspace.

What makes this file-based approach particularly valuable is its ability to scale dictionary creation efficiently. Rather than manually entering individual terms one by one, you can prepare comprehensive terminology collections offline using tools your team already knows, then upload complete dictionaries in a single operation. This batch approach becomes essential when working with specialized vocabularies, client-specific terminology, or industry jargon that requires precise handling across multiple audio processing tasks.

## When to Use This Endpoint

Dictionary creation from files serves multiple strategic purposes in your content processing workflow. During project initialization phases, you might upload industry-specific glossaries that ensure consistent pronunciation of technical terms throughout your audio processing operations. When onboarding new clients, their existing terminology databases can be quickly transformed into CAMB.AI dictionaries that maintain brand consistency and domain expertise across all subsequent processing tasks.
The file-based approach excels when you're working with collaborative teams where subject matter experts can contribute terminology knowledge without needing direct access to the CAMB.AI platform. Rather than recreating extensive vocabulary collections manually, you can preserve existing organizational knowledge by transforming it into CAMB.AI-compatible formats and uploading it as structured dictionary resources.

## File Format Requirements and Structure

The endpoint accepts both CSV and Excel file formats, providing flexibility for teams that work with different data preparation tools. Understanding the required structure becomes crucial for successful dictionary creation, as the system expects specific column arrangements and data formatting that enable proper term recognition and pronunciation guidance.

<Note>
  Your dictionary file must follow a structured [format](https://storage.googleapis.com/cambai-prod-public/dictionary/sample.xlsx) where each row represents a distinct term or pronunciation rule, and specific columns contain the information necessary for the AI systems to understand how to process that term.
</Note>

## Long-term Dictionary Management Considerations

File-based dictionary creation establishes the foundation for ongoing terminology resource management that evolves with your organizational needs and processing experience. Understanding how initial dictionary creation connects to long-term maintenance workflows helps you make strategic decisions about file organization and content structure that support sustainable terminology management practices.


# Create Folder
Source: https://docs.camb.ai/api-reference/endpoint/create-folder

post /folders/create
Establish organizational containers within your CAMB.AI workspace to structure audiobook projects effectively. This endpoint creates the foundational filing system that enables efficient project management and team collaboration across your growing content library.

## Overview

Folders serve as the organizational backbone of your CAMB.AI workspace, functioning as digital filing cabinets that contain and categorize your audiobook projects. These containers become increasingly valuable as your content library expands, providing the structural foundation that transforms chaotic project lists into navigable, logical hierarchies that support both individual productivity and collaborative workflows.

The Create Folder endpoint addresses a fundamental workspace management need by establishing these organizational containers before project creation, enabling you to implement consistent categorization strategies that scale effectively as your audiobook production grows from individual projects to comprehensive content libraries.

## When to Create Folders

Strategic folder creation occurs at multiple points in your workflow evolution. During initial workspace setup, you'll establish foundational organizational structures that reflect your content strategy and production approach. As your library grows, you'll create specialized folders that accommodate new content categories, collaboration partnerships, or workflow refinements that emerge from operational experience.

The endpoint proves particularly valuable when implementing systematic project organization strategies. Rather than creating projects first and organizing them later, proactive folder creation enables immediate categorization that maintains structural clarity throughout your production pipeline.

## Implementation and Response Structure

Creating folders requires minimal configuration while providing comprehensive feedback for workflow integration. The endpoint accepts a simple folder name and returns complete organizational information including the unique folder identifier needed for subsequent project assignments.

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

headers = {
    "x-api-key": "your-api-key",
    "Content-Type": "application/json"
}

def create_project_folder(folder_name):
    """Establishes a new organizational container for audiobook projects"""

    try:
        response = requests.post(
            "https://client.camb.ai/apis/folders/create",
            headers=headers,
            json={"folder_name": folder_name}
        )

        response.raise_for_status()
        result = response.json()

        print(f"Created folder '{result.get('folder_name')}' with ID: {result.get('folder_id')}")
        return result

    except requests.exceptions.RequestException as e:
        print(f"Folder creation failed: {e}")
        return None

# Strategic folder creation for audiobook organization
organizational_folders = [
    "Fiction - Mystery Series",
    "Educational Content - Science",
    "Corporate Training - Q2 2024"
]

for folder_name in organizational_folders:
    create_project_folder(folder_name)
```

## Strategic Integration with Project Workflows

The Create Folder endpoint integrates seamlessly with broader project management strategies by establishing organizational foundations before project creation. This proactive approach ensures that audiobook projects inherit appropriate categorization from inception, eliminating the need for retrospective organization that often leads to inconsistent project structures.

Effective folder creation considers both immediate organizational needs and long-term scalability requirements. Folders created with strategic naming conventions and clear categorization logic provide lasting value that compounds as your workspace grows, supporting efficient project discovery and collaborative access patterns that enhance rather than complicate your creative workflows.

Understanding folder creation as a foundational workspace management activity enables more sophisticated organizational strategies that support complex audiobook production pipelines while maintaining the simplicity needed for efficient daily operations.


# Setup Project
Source: https://docs.camb.ai/api-reference/endpoint/create-project-setup

post /project-setup
Initialize dubbing projects through the API for seamless editing and management in CAMB.AI Studio. This endpoint creates the foundation for your dubbing workflow by analyzing source media and establishing optimal configuration parameters.

Bridge the gap between API automation and hands-on creative control with our Project Setup endpoint. This powerful tool allows you to programmatically initialize dubbing projects that seamlessly integrate with CAMB.AI Studio, giving you the best of both worlds: automated project creation through your existing workflows and the flexibility to fine-tune results through our visual interface.

Think of this endpoint as your content's intelligent onboarding system. It analyzes your media, validates configurations, and creates a fully-prepared project ready for detailed editing in CAMB.AI Studio. This approach transforms how content teams work, enabling developers to handle project initialization while creative professionals focus on perfecting the final output.

## Why Project Setup Matters for API Users

The traditional dubbing workflow often creates friction between technical teams managing content pipelines and creative teams perfecting the final product. Project Setup eliminates this friction by establishing a clear handoff point where technical configuration meets creative refinement.

When you submit a project through this endpoint, you're not just uploading media—you're creating a structured workspace in CAMB.AI Studio that contains all the analysis, configuration, and preparation work needed for efficient dubbing. Your creative team receives a project that's already optimized and ready for detailed editing, rather than starting from scratch with raw media files.

## The API-to-Studio Workflow

Understanding how Project Setup connects API automation with Studio editing helps you design more efficient content workflows. The process creates a seamless bridge between programmatic project creation and visual editing tools.

**Automated Project Initialization**: Your API request handles all the technical groundwork—media analysis, language configuration, and optimization parameter selection. This automation ensures consistent project setup across your entire content library while eliminating manual configuration errors.

**Studio-Ready Project Creation**: The endpoint generates a fully-prepared project workspace in CAMB.AI Studio, complete with analyzed audio tracks, configured language settings, and optimized processing parameters. Your creative team can immediately begin working with the content rather than spending time on technical setup.

**Preserved Configuration Context**: All API-specified parameters, including custom dictionaries and advanced audio track settings, carry forward into the Studio environment. This continuity ensures that your technical requirements remain intact while enabling creative refinement.

## Media Source Compatibility

Project Setup accommodates diverse media sources, making it easy to integrate with existing content management systems. Whether your media lives on YouTube, Google Drive, or professional storage systems, the endpoint handles ingestion automatically.

The system supports both consumer formats like MP4 and professional broadcast formats including MXF files for Enterprise customers. This broad compatibility means you can standardize your project creation process regardless of your content's origin or quality level.

<Info>Enterprise plan customers enjoy exclusive access to MXF format support, bringing professional broadcast standards to organizations with specialized media requirements.</Info>

## Implementation Example

Let's examine how to create a project that leverages both API efficiency and Studio flexibility. This example demonstrates the essential parameters while showing how your configuration translates into a Studio-ready workspace.

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

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

# Define project configuration
# This setup creates a project optimized for Studio editing
project_config = {
    "project_name": "Product Launch Campaign",  # Project name visible in Studio
    "project_description": "Multi-language product demo for global markets",  # Context for Studio users
    "media_url": "https://your-storage.com/product-demo.mp4",  # Source media location
    "source_language": "en-us",                       # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "target_languages": ["es-es", "fr-fr", "de-de"],
}

def create_studio_project(payload):
    """
    Creates a project configured for optimal Studio editing experience.
    The resulting project appears in CAMB.AI Studio with all technical setup complete.
    """
    try:
        response = requests.post(
            "https://client.camb.ai/apis/project-setup",
            headers=headers,
            data=json.dumps(payload)
        )

        response.raise_for_status()
        result = response.json()

        task_id = result.get("task_id")
        return task_id

    except requests.exceptions.RequestException as e:
        print(f"Project creation failed: {e}")
        return None

# Create the project
project_setup_task_id = create_studio_project(project_config)

if not project_setup_task_id:
    print(f"Failed to create project '{project_config['project_name']}'. Please check your API key and configuration.")
else:
    print(f"Project '{project_config['project_name']}' task is created successfully! Task ID: {project_setup_task_id}")
```

## Best Practices for API-Studio Integration

Successful integration between API project creation and Studio editing depends on understanding how your configuration choices impact the creative editing experience. Several strategies can significantly improve your team's efficiency and output quality.

**Descriptive Project Naming**: Use clear, descriptive names and descriptions that help Studio users understand project context immediately. This clarity becomes crucial when managing multiple projects or coordinating between team members with different responsibilities.

**Optimal Language Configuration**: Verify locale tags using the dedicated endpoints before submitting projects. Accurate language configuration ensures that Studio users receive projects with properly configured voice options and translation models.

**Quality-Focused Media Selection**: Choose the highest quality source media available, as compression artifacts and audio issues in source material become more apparent during the detailed editing process in Studio. Starting with quality media enables better creative decisions throughout the editing workflow.

Project Setup represents the ideal fusion of API automation and creative control. By handling the technical groundwork programmatically, you enable your creative team to focus on the nuanced decisions that determine final quality, while ensuring consistent, professional results across your entire content pipeline.


# Create Story
Source: https://docs.camb.ai/api-reference/endpoint/create-story

post /story
Creates a story based on the content provided in a text file (`.txt`) or Word document (`.docx`)

Transform your written content into engaging narrated stories with our story creation endpoint. This powerful service takes your text documents and processes them into compelling stories with professional narration. The system handles the entire process from parsing your document to generating a professionally narrated version, making storytelling accessible.

## The Story Creation Process

When you submit a story creation request, our system begins a multi-stage workflow:

<Steps>
  <Step title="Document Processing">
    Your uploaded text file or Word document is processed and prepared for narration. Our system extracts and analyzes the content, ensuring proper formatting and structure.
  </Step>

  <Step title="Voice Selection">
    Your chosen AI narrator voice is applied to the story, bringing your content to life with natural-sounding speech patterns and appropriate emotional delivery.
  </Step>

  <Step title="Audio Production">
    The narration is finalized with professional audio quality enhancements, ensuring clarity and engagement.
  </Step>
</Steps>

Throughout this process, you can check on your task's progress using the [`/story/{task_id}`](get-story-status) endpoint with the `task_id` provided in your initial response.

## Supported Document Formats

Our story creation service accepts two popular document formats to accommodate your workflow:

| Document Type  | Supported Formats |
| :------------- | :---------------- |
| Text Files     | .txt              |
| Word Documents | .docx             |

This flexibility allows you to work with your preferred writing tools without conversion hassles.

## Language Configuration

Specifying the correct source language is crucial for successful story creation. To find the appropriate language identifier:

1. Query the [`/source-languages`](get-source-languages) endpoint for a complete list of supported languages.
2. Pass the locale tag (e.g. `"en-us"`) in your request. Numeric language IDs still work but are deprecated.

## Creating Your First Story

Let's look at how to initiate a story creation task with 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
}

# Define your story parameters
title = "The Midnight Garden"
description = "A mysterious tale of discovery and wonder"
source_language = "en-us"  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated. See /source-languages.
narrator_voice_id = 147320  # Example

# Function to submit a story creation request
def create_story(file_path, title, description, source_language, narrator_voice_id):
    """
    Submits a new story creation task and returns the task ID for tracking.

    Parameters:
    - file_path: Path to the .txt or .docx file containing story content
    - title: Title of the story
    - description: Brief description of the story
    - source_language: Locale tag (e.g. "en-us") for the story content; numeric IDs still work but are deprecated
    - narrator_voice_id: ID of the voice that will narrate the story
    """
    try:
        # Prepare the multipart form data
        files = {
            'file': (file_path.split('/')[-1], open(file_path, 'rb'))
        }

        data = {
            'title': title,
            'description': description,
            'source_language': source_language,
            'narrator_voice_id': narrator_voice_id
        }

        # Submit the request
        response = requests.post(
            "https://client.camb.ai/apis/story",
            headers=headers,
            files=files,
            data=data
        )

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

    except requests.exceptions.RequestException as e:
        print(f"Error submitting story creation task: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None
    finally:
        # Make sure to close the file
        if 'files' in locals() and 'file' in files:
            files['file'][1].close()

# Call the function with your story file
file_path = "path/to/your/story.docx"  # Replace with your actual file path
task_id = create_story(file_path, title, description, source_language, narrator_voice_id)
```

## Monitoring Your Story Creation Progress

After submission, your content enters our processing pipeline. The time required depends on the length and complexity of your document. You can check progress by polling the status endpoint:

```python [expandable] theme={null}
def check_story_status(task_id):
    """
    Checks the status of a story creation task.
    Returns the current status and any available result information.

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

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

        return status_data

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

# Check the status of your story creation task
status_info = check_story_status(task_id)
```

## Best Practices for Optimal Results

To get the most from our story creation service, consider these professional tips:

1. **Document Quality**: Ensure your document is well-formatted with proper grammar and punctuation for better narration results.

2. **Voice Selection**: Choose a narrator voice that matches the tone and style of your story content.

3. **Language Accuracy**: Double-check that your source language is correctly specified to ensure proper pronunciation and pacing.

4. **Content Length**: While our system can handle documents of various lengths, consider breaking very long works into logical segments for optimal processing.

5. **File Format**: Use .docx format when you need to preserve complex formatting, and .txt for simpler text-based stories.

## Practical Applications

Our story creation functionality opens exciting possibilities across industries:

* **Education**: Transform educational content into engaging audio lessons for diverse learning styles.
* **Publishing**: Quickly create audio versions of books, articles, and short stories.
* **Content Creation**: Convert blog posts and articles into narrated content for podcasts or audio platforms.
* **Accessibility**: Make written content accessible to visually impaired audiences or those who prefer audio content.
* **Entertainment**: Bring original stories to life with professional-quality narration.

By integrating this API into your workflow, you can efficiently transform written content into engaging audio stories, dramatically reducing the time and expense traditionally associated with professional narration while maintaining impressive quality.


# Setup Story
Source: https://docs.camb.ai/api-reference/endpoint/create-story-setup

post /story-setup
Initialize audiobook projects through the API for seamless editing and management in CAMB.AI Studio. This endpoint creates the foundation for your stories workflow by analyzing source text and establishing optimal narration parameters.

Transform your written content into professional audiobook projects with our Story Setup endpoint. This intelligent service bridges the gap between automated project initialization and creative audiobook production, allowing you to programmatically create story projects that seamlessly integrate with CAMB.AI Studio for detailed narration refinement and management.

Story Setup differs from direct story creation by building a project workspace rather than producing immediate results. Think of it as preparing a professional editing suite where creative teams can adjust pacing, refine pronunciation, and enhance overall audiobook quality.

## How it Works

Story Setup handles the technical foundation while preserving creative control. Your API request processes text analysis, configures narrator settings, and creates a Studio workspace with all preparation complete. Creative teams receive a ready-to-edit project rather than starting from raw text files.
The workflow naturally divides responsibilities between automated setup and creative refinement, enabling consistent project initialization while maintaining the flexibility needed for high-quality audiobook production.

## Quick Implementation

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

headers = {"x-api-key": "your-api-key"}

def create_audiobook_project(file_path, title, description, source_language, narrator_voice_id):
    """Creates audiobook project workspace in CAMB.AI Studio"""

    files = {'file': open(file_path, "rb")}
    data = {
        'title': title,
        'description': description,
        'source_language': source_language,
        'narrator_voice_id': narrator_voice_id
    }

    try:
        response = requests.post(
            "https://client.camb.ai/apis/story-setup",
            headers=headers, files=files, data=data
        )
        response.raise_for_status()
        result = response.json()

        print(f"Project created! Studio URL: {result.get('story_details', {}).get('studio_url')}")
        return result.get("run_id")

    except requests.exceptions.RequestException as e:
        print(f"Creation failed: {e}")
        return None
    finally:
        files['file'].close()

# Example usage
run_id = create_audiobook_project(
    "story.docx", # Replace with your local file path you are uploading.
    "My Audiobook Project",
    "Adventure story requiring dramatic narration",
    1,  # English
    147320
)
```

## Essential Configuration

Use clear project names and detailed descriptions to help Studio editors understand your content context and narration requirements. Verify language settings using the source languages endpoint and select narrator voices that match your content's tone and target audience.

Prepare documents with proper formatting and structure, as chapter organization and text quality directly impact the editing workflow. For specialized content with unique terminology, consider preparing pronunciation dictionaries to ensure consistent narration.

## When to Choose Story Setup

Use Story Setup for collaborative audiobook projects requiring creative refinement, quality control, or complex narration requirements. This endpoint excels when audiobook quality and team collaboration matter more than immediate results.

For simple, immediate narrated content without extensive editing needs, consider direct story creation instead. Story Setup provides the foundation for professional audiobook production where creative control and collaborative workflows drive the final quality.


# Create Subtitle
Source: https://docs.camb.ai/api-reference/endpoint/create-subtitle

post /sub
Creates a task to generate subtitle-ready segments from a media URL, in the source language and any number of target languages. Send a JSON body with a publicly accessible or signed media URL.

## Generating Subtitles Across Languages

Our subtitle service turns spoken media into cue-ready text. It transcribes the source language, translates into any target languages you request, and, when you ask for it, segments every language into cues sized for on-screen display. This endpoint initiates a subtitle task from a media URL and returns a unique identifier that allows you to track and retrieve your results.

## Understanding Subtitle Generation

Subtitle generation builds on the same speech recognition and translation technology behind our Transcription and Translation services, chained together for you in a single request:

1. Analyzes the media to identify speech segments in the source language
2. Translates the recognized speech into each requested target language
3. When `formatting_options` is provided, segments every language's text into cues that respect subtitle timing and length limits

This lets you go from a raw recording to subtitles in several languages without orchestrating transcription, translation, and segmentation as separate calls.

## Language Selection

Subtitle generation needs `source_language` and a non-empty `target_languages` array in the JSON body:

* **`source_language`**: the language spoken in your media. Locale tag (e.g. `en-us`) or numeric ID.
* **`target_languages`**: one or more output languages. Pass a single-item array when you only need one language (for example `["es-es"]`), the same pattern as end-to-end dubbing.

Include the source language itself in `target_languages` if you also want same-language, subtitle-ready cues for the original speech.

<Card icon="languages" href="get-target-languages">
  For a complete list of supported languages and their locale tags, see [source languages](get-source-languages) and [target languages](get-target-languages).
</Card>

### Supported Media Formats

Provide a publicly accessible or signed `media_url`. For optimal results, we recommend using high-quality media with clear speech and minimal background noise. Our service accepts the following media formats:

* MP3 (`.mp3`)
* WAV (`.wav`)
* AAC (`.aac`)
* FLAC (`.flac`)
* MP4 (`.mp4`)
* MOV (`.mov`)
* MXF (`.mxf`)

<Info>
  Please note that MXF format support is exclusively available to customers on our Enterprise plan, offering professional broadcast-quality media handling for organizations with advanced needs.
</Info>

## Transcription Mode

The optional `transcription_mode` field controls the transcription pass used for the source media:

* **`fast`** (default): returns a result more quickly while maintaining quality.
* **`slow`**: takes longer and may produce a more accurate transcript through a more thorough pass.

Omit the field to use `fast`.

## Subtitle Formatting

By default, subtitle generation translates the source speech into each target language but leaves the text unsegmented, the same speech-boundary segments you'd get from Translation, not subtitle-length cues. To get cues sized for on-screen subtitles, pass the optional `formatting_options` object in the JSON body. When provided, subtitle segmentation runs for every requested language:

* **`max_segment_duration_in_seconds`** (default: `7.0`): the longest a single cue may stay on screen.
* **`min_segment_duration_in_seconds`** (default: `1.0`): the shortest a single cue may stay on screen.
* **`max_characters_in_segment`** (default: `42`): the maximum number of characters allowed in one cue.

Omit `formatting_options` if you just need translated dialogue without subtitle timing rules.

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/sub" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_language": "en-us",
    "media_url": "https://example.com/interview.mp4",
    "target_languages": ["es-es", "fr-fr"],
    "transcription_mode": "fast",
    "formatting_options": {
      "max_segment_duration_in_seconds": 7,
      "min_segment_duration_in_seconds": 1,
      "max_characters_in_segment": 42
    }
  }'
```

## Request Example

Create a subtitle task by sending a JSON body with a media URL. Here's how to request subtitles in multiple target languages using Python with the `requests` library:

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

def create_subtitle_task(
    api_key,
    media_url,
    source_language="en-us",
    target_languages=None,
    formatting_options=None,
):
    """
    Initiates a subtitle task from a media URL.

    Args:
        api_key (str): API authentication key
        media_url (str): Public or signed URL of the media resource
        source_language (str): Locale tag like "en-us"; numeric IDs still work but are deprecated
        target_languages (list[str]): Locale tags for one or more target languages
        formatting_options (dict, optional): Subtitle segmentation rules, e.g.
            {"max_segment_duration_in_seconds": 7, "min_segment_duration_in_seconds": 1, "max_characters_in_segment": 42}

    Returns:
        dict: Response containing task_id for status tracking
    """
    url = "https://client.camb.ai/apis/sub"
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
    }
    payload = {
        "source_language": source_language,
        "media_url": media_url,
        "target_languages": target_languages or [],
        "transcription_mode": "fast",
    }
    if formatting_options:
        payload["formatting_options"] = formatting_options

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

    if response.ok:
        return response.json()
    print(f"Error {response.status_code}: {response.text}")
    return None

# Request subtitles in Spanish and French, with subtitle-ready cues
result = create_subtitle_task(
    api_key="your_api_key",
    source_language="en-us",
    target_languages=["es-es", "fr-fr"],
    media_url="https://storage.example.com/interview.mp3",
    formatting_options={
        "max_segment_duration_in_seconds": 7,
        "min_segment_duration_in_seconds": 1,
        "max_characters_in_segment": 42,
    },
)
```

Optional body fields include `project_name`, `project_description`, and `folder_id`.

## Next Steps: Monitoring Your Subtitle Task

After submitting your subtitle request, you'll want to monitor its progress and retrieve the results once processing completes:

1. Use the [`/sub/{task-id}`](poll-subtitle-result) endpoint to check your task's status
2. Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
3. Once the status shows as `SUCCESS`, retrieve your subtitles from [`/sub-result/{run_id}`](get-subtitle-run-result) (every language; optional `format_type`/`data_type` export) or [`/sub-result/{run_id}/{language}`](get-subtitle-result-for-language) for one language

<Info>
  Need a plain transcript in a single language instead of translated, multi-language subtitles? Use [Create Transcription](create-transcription). It shares the same `formatting_options` field for subtitle-ready cues.
</Info>


# Create Sound and Music
Source: https://docs.camb.ai/api-reference/endpoint/create-text-to-sound

post /text-to-sound
Creates a task to generate an audio file—either music or sound effects—from a given text prompt

Turn descriptive text into expressive music or sound effects. This endpoint generates either structured musical audio (melodies, harmonies, beats) or non-musical SFX (foley, UI beeps, ambience, impacts) based on your prompt and selected `audio_type`.

## The Generation Process

<Steps>
  <Step title="Task Creation">
    Your request is registered and a processing task is created. The response includes a unique `task_id` you’ll use to track progress and retrieve results (via the returned `run_id`).
  </Step>

  <Step title="Text Analysis">
    We analyze your prompt to identify sonic intent—musical attributes (tempo, instrumentation, groove) for `music`, or acoustic characteristics (materials, space, motion) for `sound`.
  </Step>

  <Step title="Audio Synthesis">
    Specialized models synthesize the audio to match your description and requested `duration`.
  </Step>
</Steps>

<Note>
  * **Music `duration` behavior:**
    When `audio_type` is set to `music`, the `duration` parameter is **not enforced**. Music generations currently return a fixed-length clip depending on the prompt provided. If you need a precise length for music, trim, loop, or stitch the result in post-production. The `duration` parameter continues to apply to `sound` (SFX) requests.
</Note>

<Warning>
  Maximum duration per request is **10 seconds**. The default duration is **8.0 seconds**.
</Warning>

Throughout this process, you can monitor the status of your generation task by polling the [`/text-to-sound/{task_id}`](get-text-to-sound-status) endpoint with the `task_id` provided in your initial response.

## Creating Your First Request

Let's examine how to initiate a sound generation task using Python:

```python [expandable] theme={null}
import requests
import json
from typing import Literal

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

def create_text_to_sound(prompt: str, audio_type: Literal["sound", "music"], duration=8.0):
    """
    Submits a new text-to-sound generation task and returns the task ID for tracking.

    Parameters:
    - prompt: A descriptive text explaining the sound to generate
    - duration: The desired length of the audio in seconds (default: 8.0)
    """
    try:
        # Prepare the request body
        payload = {
            "prompt": prompt,
            "duration": duration,
            "audio_type": audio_type
        }

        # Submit the generation request
        response = requests.post(
            "https://client.camb.ai/apis/text-to-sound",
            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"Sound generation task submitted successfully! Task ID: {task_id}")
        return task_id

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

# SFX example
prompt = "A gentle rainfall on a tin roof that swells briefly with a distant thunder roll"
task_id = create_text_to_audio(prompt, audio_type="sound", duration=10.0)

# Music example
prompt = "Warm lo-fi beat at 80 BPM with soft piano chords, vinyl crackle, and mellow bass"
task_id = create_text_to_audio(prompt, audio_type="music")
```

## Monitoring Your Sound Generation Progress

After submission, your sound generation task enters our processing pipeline. You can monitor the progress by polling the status endpoint:

```python [expandable] theme={null}
def check_sound_generation_status(task_id):
    """
    Checks the status of a text-to-sound generation task.
    Returns the current status and any available result information.

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

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/text-to-sound/{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 generation is complete, display the results
        if status_data['status'] == "SUCCESS":
            print("Sound generation completed successfully!")
            print(f"Audio URL: {status_data.get('audio_url')}")

        return status_data

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

# Check the status of your generation task
status_info = check_sound_generation_status(task_id)
```

## Prompting Tips

The quality of your generated audio depends significantly on how well you craft your text prompts. Here are some professional recommendations for creating effective descriptions:

1. **Be Specific**:
   * **Music**: “Upbeat indie rock with clean electric guitars, driving drums, and a catchy 4-bar hook.”
   * **SFX**: “Single metal door slam in a concrete hallway, short decay, slight echo.”

2. **Include Context**:
   * **Music**: “Mellow coffee-shop background loop, no vocals, relaxed vibe.”
   * **SFX**: “Footsteps on wet gravel at night, occasional splashes.”

3. **Describe Dynamics**:
   * **Music**: “8-second loop, soft intro hit, steady groove, light ending tail.”
   * **SFX**: “Starts distant, approaches quickly, then passes left to right.”

4. **Mention Emotional Qualities**:
   * **Music**: “Dreamy and nostalgic, lo-fi texture, gentle swing.”
   * **SFX**: “Eerie, tense drone with subtle mechanical whir.”

5. **Reference Familiar Sounds**:
   * **Music**: “Similar to a chillhop beat with muted trumpet accents.”
   * **SFX**: “Like a UI success chime with a soft shimmer tail.”


# Create Voice from Description
Source: https://docs.camb.ai/api-reference/endpoint/create-text-to-voice

post /text-to-voice
Submits a request to initiate a task for creating a human-like voice from a given text prompt.

This endpoint enables you to generate custom, human-like synthetic voices based on your descriptive text prompts. Rather than selecting from pre-defined voice options, this innovative approach allows you to craft voices tailored to your specific needs by simply describing the voice characteristics you want. The endpoint initiates an asynchronous process, returning a task\_id that you can use to monitor the generation progress and eventually retrieve your custom voice.

<Note>A description consisting of at least 18 words (100+ characters) is required for voice generation. Requests with shorter prompts will not be processed successfully.</Note>

## How Voice Generation Works

The voice generation process follows these steps:

1. You submit a detailed description of the voice you want to create, along with sample text for the voice to speak.
2. The system analyzes your description and generates two sample voices matching those characteristics for you to choose from.
3. The system returns a `task_id` that you can use to track the generation process.
4. You periodically check the status using the [`/text-to-voice/{task_id}`](get-text-to-voice-status) endpoint.
5. Once complete, you can access and use the generated voice in your applications.

## Creating Effective Voice Descriptions

The quality and specificity of your voice description directly impacts the resulting voice. When crafting your description, consider including details about:

* **Gender and age range**: "A middle-aged woman" or "An elderly man"
* **Accent and regional characteristics**: "With a mild Scottish accent" or "Speaking American English with Southern inflections"
* **Emotional qualities**: "A warm, nurturing tone" or "An authoritative, confident delivery"
* **Speaking style**: "Who speaks slowly and deliberately" or "With an energetic, rapid-fire delivery"
* **Cultural context**: "A voice that would be at home narrating documentaries" or "Like a friendly teacher explaining concepts"
* **Vocal characteristics**: "With a slightly raspy quality" or "With a deep, resonant tone"

The more detailed and vivid your description, the more precisely the system can match your desired voice characteristics. Remember that your description must contain at least 18 words (100+ characters) to provide sufficient guidance for the voice generation system.

## Example Request

```json theme={null}
{
  "text": "Welcome to our application. I'll be your guide through all the features and capabilities available to you.",
  "voice_description": "A warm and friendly middle-aged woman with a slight British accent. She speaks clearly and articulately, with a soothing tone that conveys expertise and trustworthiness. Her voice has a natural musical quality without being overly dramatic."
}
```

## Response

Upon successful submission, the endpoint returns a `task_id` that you can use to check the status of your voice generation task:

```json theme={null}
{
  "task_id": "your_task_id"
  "status": "PENDING"
}
```

## Monitoring Generation Progress

Voice generation is a computationally intensive process that typically takes some time to complete. To check the status of your generation task, periodically poll the [`/text-to-voice/{task_id}`](get-text-to-voice-status) endpoint using the `task_id` received in the initial response.

## Best Practices

1. **Be specific in your descriptions**: The more detailed your voice description, the better the system can match your expectations.
2. **Consider the context**: Tailor your voice to match the content and audience of your application.
3. **Start with longer descriptions**: While 18 words is the minimum, starting with more detailed descriptions (30-50 words) often yields better results.
4. **Test variations**: If your first voice isn't exactly what you need, try adjusting specific aspects of your description to refine the results.
5. **Include emotional context**: Describing the emotional quality of the voice significantly improves the naturalness of the generated speech.

## Limitations

* Voice descriptions must be at least 18 words (100+ characters) long.
* Very unusual or contradictory voice descriptions may yield unpredictable results.

By leveraging this endpoint effectively, you can create custom voices that perfectly match your brand identity, content needs, and user expectations, all without the need for professional voice talent or recording studios.


# Create Transcription
Source: https://docs.camb.ai/api-reference/endpoint/create-transcription

post /transcribe
Creates a task to process speech into readable text. Submit either a media file or a publicly accessible media URL. Optionally request subtitle-ready segmentation on the resulting transcript.

## Converting Speech to Text with Precision

Our transcription service transforms spoken content into accurate, readable text, enabling you to make your media content searchable, accessible, and analytically valuable. This endpoint initiates a transcription task, processing your media file and returning a unique identifier that allows you to track and retrieve your results.

## Understanding Speech Transcription

Speech transcription technology analyzes media recordings of human speech or video that contains speech and converts them into written text. This process employs sophisticated machine learning models trained on diverse speech patterns, accents, and linguistic contexts to deliver high-quality text outputs. Our system handles various media formats and speaking situations, from clear studio recordings to more challenging environments with background noise.

When you submit a media file for transcription, our system:

1. Analyzes the audio signal to identify speech segments
2. Processes these segments through advanced recognition models
3. Applies language-specific rules and context awareness
4. Generates a readable text transcript that captures the spoken content

This transformation creates valuable text assets from your media content, enabling new ways to search, analyze, and repurpose your spoken material.

### Supported Languages

Our transcription service supports a wide range of languages. Some of the most commonly used include:

* English (`en-us`)
* Spanish (`es-es`)
* French (`fr-fr`)
* German (`de-de`)
* Mandarin Chinese (`zh-cn`)
* Japanese (`ja-jp`)
* Arabic (`ar-sa`)

<Card icon="languages" href="get-source-languages">
  For a complete list of supported languages and their respective language codes, refer to our Language Support Documentation
</Card>

### Supported media Formats

For optimal transcription quality, we recommend using high-quality media with clear speech and minimal background noise. Our service accepts the following media formats:

* MP3 (`.mp3`)
* WAV (`.wav`)
* AAC (`.aac`)
* FLAC (`.flac`)
* MP4 (`.mp4`)
* MOV (`.mov`)
* MXF (`.mxf`)

<Info>
  Please note that MXF format support is exclusively available to customers on our Enterprise plan, offering professional broadcast-quality media handling for organizations with advanced needs.
</Info>

## Transcription Mode

The optional `transcription_mode` form field controls the transcription pass used for the source media:

* **`fast`** (default): returns a transcript more quickly while maintaining quality.
* **`slow`**: takes longer and may produce a more accurate transcript through a more thorough pass.

Omit the field to use `fast`.

## Keeping Music in the Foreground

The optional `include_music_in_fg` form field controls how background music is handled during source separation:

* **`true`** (default): music is preserved in the foreground audio alongside speech.
* **`false`**: music is stripped out of the foreground, isolating speech.

Omit the field to keep the default behaviour of retaining music.

## Subtitle-Ready Segmentation

By default, a transcript is segmented by natural speech patterns rather than by subtitle-length rules. If you're planning to export the transcript as `srt`/`vtt`, or just need shorter, screen-friendly cues, pass the optional `formatting_options` form field. It's a JSON string on the multipart request. When provided, subtitle segmentation also runs on the completed transcript, in the same language:

* **`max_segment_duration_in_seconds`** (default: `7.0`): the longest a single segment may stay on screen.
* **`min_segment_duration_in_seconds`** (default: `1.0`): the shortest a single segment may stay on screen.
* **`max_characters_in_segment`** (default: `42`): the maximum number of characters allowed in one segment.

Omit `formatting_options` for a standard, speech-boundary transcript.

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "language=en-us" \
  -F "media_url=https://example.com/interview.mp4" \
  -F 'formatting_options={"max_segment_duration_in_seconds": 7, "min_segment_duration_in_seconds": 1, "max_characters_in_segment": 42}'
```

<Info>
  Need subtitles in languages other than the source, or want to fetch cues per target language? Use the dedicated [Create Subtitle](create-subtitle) endpoint instead. It runs the same segmentation on translated output for one or more target languages.
</Info>

## Request Example

You can create a transcription task by either uploading a media file or providing a URL to a media resource. Here are examples using cURL:

* Using a local media file:

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "language=en-us" \
  -F "include_music_in_fg=true" \
  -F "media_file=@/path/to/your/media_file.mp3"
```

* Using a remote media URL:

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "language=en-us" \
  -F "media_url=https://example.com/media_file.mp3"
```

Here's how to handle both scenarios in Python with the `requests` library:

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

def create_transcription_task(api_key, language="en-us", media_file_path=None, media_url=None):
    """
    Initiates a transcription task using either a media file or URL.

    Args:
        api_key (str): API authentication key
        language (str): Locale tag like "en-us"; numeric IDs (e.g. 1) still work but are deprecated
        media_file_path (str, optional): Path to local media file
        media_url (str, optional): URL of remote media resource

    Returns:
        dict: Response containing task_id for status tracking
    """
    url = "https://client.camb.ai/apis/transcribe"
    headers = {"x-api-key": api_key}
    data = {"language": language, "transcription_mode": "fast"}
    files = None

    # Validate input
    if not (media_file_path or media_url):
        raise ValueError("Must provide either media_file_path or media_url")
        if media_file_path and media_url:
        raise ValueError("Provide only one of media_file_path or media_url")

    # Prepare request components
    if media_file_path:
        with open(media_file_path, "rb") as media_file:
            files = {"media_file": (media_file_path.split("/")[-1], media_file)}
    else:
        data["media_url"] = media_url

    # Execute request
    response = requests.post(url, headers=headers, files=files, data=data)

    if response.ok:
        return response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

# Example with file upload
file_result = create_transcription_task(
    api_key="your_api_key",
    media_file_path="meeting_recording.mp3",
    language="en-us"  
)

# Example with media URL
url_result = create_transcription_task(
    api_key="your_api_key",
    media_url="https://storage.example.com/interview.mp3",
    language="es-es"
)
```

## Processing Time Considerations

Transcription processing time depends on several factors:

* **Media Duration**: Longer files naturally take more time to process
* **Media Quality**: Clear, high-quality recordings process more efficiently
* **Language Complexity**: Some languages may require more processing time
* **System Load**: Processing time can vary based on current system demand

## Next Steps: Monitoring Your Transcription Task

After submitting your transcription request, you'll want to monitor its progress and retrieve the results once processing completes. To do this:

1. Use the [`/transcribe/{task-id}`](poll-transcription-result) endpoint to check your task's status
2. Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
3. Once the status shows as `SUCCESS`, you can retrieve your full transcript

## Best Practices for Optimal Results

To get the most accurate transcriptions from our service:

1. **Use High-Quality Media**: Whenever possible, use media recorded in quiet environments with minimal background noise.

2. **Appropriate Media Format**: Submit uncompressed media formats like WAV or FLAC for best quality, or high-bitrate MP3s if file size is a concern.

3. **Speaker Clarity**: Encourage clear speaking with moderate pace for best recognition accuracy.

4. **Specify the Correct Language**: Always provide the correct language parameter to ensure our models apply the right language patterns.

5. **Segment Longer Content**: For very long recordings (over 2 hours), consider splitting into multiple smaller files for more efficient processing.

## Handling Common Issues

If you encounter problems with your transcription tasks, these troubleshooting steps may help:

### Rejected File Uploads

**Problem**: Your request returns an error about the file upload.

**Potential Solutions**:

* Verify your file is in one of our supported formats (`.mp3`, `.wav`, `.aac`, `.flac`, `.mp4`, `.mov`, `.mxf`)
* Check that your file isn't corrupted or empty
* Ensure your file doesn't exceed our size limit (20 MB)

### Incorrect Language Specification

**Problem**: Transcription results appear inaccurate or contain many errors.

**Potential Solutions**:

* Verify you specified the correct language code
* For multilingual content, choose the predominant language

## Taking Your Transcriptions Further

Once you've successfully transcribed your media content, consider these next steps:

1. **Semantic Analysis**: Extract key topics, sentiments, and entities from your transcribed text
2. **Content Indexing**: Make your media searchable by indexing the transcript content
3. **Accessibility Compliance**: Use transcripts to make your media content accessible to all users
4. **Translation**: Convert your transcript into other languages for global reach
5. **Summary Generation**: Create concise summaries of longer transcribed content


# Create Translated Story
Source: https://docs.camb.ai/api-reference/endpoint/create-translated-story

post /translated-story/{run_id}
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. Pass the locale tag (e.g. `"es-es"`, `"fr-fr"`) in your request. Numeric language IDs still work but are deprecated.
2. For the complete list of supported languages, query the [`/target-languages`](get-target-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: Locale tag of the target language (e.g. "es-es"); numeric IDs still work but are deprecated
    """
    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 = "es-es" 
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.


# Create Translated Text-to-Speech
Source: https://docs.camb.ai/api-reference/endpoint/create-translated-tts

post /translated-tts
Creates a task to translate input text and generate corresponding speech audio

Transform written content across language barriers with our powerful translated text-to-speech system. This innovative endpoint enables you to seamlessly convert text from one language into spoken audio in another language in a single streamlined process. Whether you're creating multilingual content, developing educational materials, building accessible applications, or expanding your global reach, this capability allows you to quickly generate localized audio content while maintaining natural pronunciation and intonation specific to the target language.

<Note>
  Once the task is complete, the outputs can be retrieved using these endpoints:

  * [`/translation-result/{run_id}`](get-translation-run-result): Returns the translated text.
  * [`/tts-result/{run_id}`](get-tts-result): Returns the generated voiceover audio
</Note>

## How It Works

When you submit a request to this endpoint, our system processes your input text through a streamlined workflow:

* First, the system creates a dedicated task and returns a unique `task_id` for tracking.
* Your source text is then accurately translated to the target language using advanced neural machine translation models that preserve meaning andn context.
* Finally, the translated text is converted into natural-sounding speech using language-specific voice models that capture the appropriate pronunciation and intonation of the target language.
* You can monitor the status of your request by polling the [`/translated-tts/{task_id}`](poll-translated-tts-result) endpoint until processing is complete.

## Creating Your First Translated Text-to-Speech Request

Let's examine how to initiate a translated text-to-speech 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"
}

def create_translated_tts(text, source_language, target_language, voice_id=None):
    """
    Submits a new translated text-to-speech task and returns the task ID for tracking.

    Parameters:
    - text: The source text to be translated and converted to speech
    - source_language: Locale tag of the input text (e.g., "en-us"); numeric IDs (e.g. 1) still work but are deprecated
    - target_language: Locale tag for the desired output (e.g., "es-es")
    - voice_id: Optional specific voice to use for the target language
    """
    try:
        # Prepare the request body
        payload = {
            "text": text,
            "source_language": source_language,
            "target_language": target_language
        }

        # Add voice_id if specified
        if voice_id:
            payload["voice_id"] = voice_id

        # Submit the request
        response = requests.post(
            "https://client.camb.ai/apis/translated-tts",
            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")
        run_id = result.get("run_id")

        print(f"Translated TTS task submitted successfully! Task ID: {task_id}")
        print(f"Run ID for retrieving results: {run_id}")
        return task_id, run_id

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

# Example usage
source_text = "Welcome to our global product demonstration. We're excited to share these new features with you."
task_id, run_id = create_translated_tts(
    text=source_text,
    source_language="en-us",  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    target_language="ja-jp"
)
```

## Monitoring Your Translation and Speech Generation Progress

After submission, your task enters our processing pipeline. You can monitor the progress by polling the status endpoint:

```python [expandable] theme={null}
def check_translated_tts_status(task_id):
    """
    Checks the status of a translated text-to-speech task.
    Returns the current status and any available result information.

    Parameters:
    - task_id: The ID of the 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-tts/{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 task is complete, show how to access results
        if status_data['status'] == "SUCCESS":
            print("Translation and speech generation completed successfully!")
            print(f"Use the run_id to retrieve your results.")
            print(f"- Translation: GET /translation-result/{status_data.get('run_id')}")
            print(f"- Audio: GET /tts-result/{status_data.get('run_id')}")

        return status_data

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

# Check the status of your task
status_info = check_translated_tts_status(task_id)
```

## Retrieving Your Results

Once your task is complete, you can retrieve both the translated text and the generated audio using the provided run\_id:

```python [expandable] theme={null}
def get_translation_result(run_id):
    """
    Retrieves the translated text result.

    Parameters:
    - run_id: The run ID returned from the initial request
    """
    try:
        response = requests.get(
            f"https://client.camb.ai/apis/translation-result/{run_id}",
            headers=headers
        )

        response.raise_for_status()
        result = response.json()

        print(f"Translation successful!")
        print(f"Translated text: {result.get('translated_text')}")
        return result

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

def get_tts_result(run_id):
    """
    Retrieves the generated audio file.

    Parameters:
    - run_id: The run ID returned from the initial request
    """
    try:
        response = requests.get(
            f"https://client.camb.ai/apis/tts-result/{run_id}",
            headers=headers
        )

        response.raise_for_status()
        result = response.json()

        print(f"Audio retrieval successful!")
        print(f"Audio URL: {result.get('audio_url')}")
        return result

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving audio: {e}")
        return None

# Retrieve your results
translation = get_translation_result(run_id)
audio = get_tts_result(run_id)
```

## Best Practices for Translated Text-to-Speech

To achieve the highest quality results for your multilingual audio content:

1. **Provide Clear Source Text**: Ensure your source text is free of grammatical errors, unusual abbreviations, or ambiguous phrases to improve translation accuracy.

2. **Consider Cultural Context**: Be mindful of cultural references that may not translate effectively across languages, and adapt your content accordingly.

3. **Use Appropriate Sentence Length**: For optimal speech generation, break long, complex sentences into shorter ones, especially for languages that differ structurally from the source.

## Supported Languages & Voices

Our system supports a wide range of language pairs for translation and speech synthesis. The quality and naturalness of speech may vary depending on the specific language combinations. Checkout the [`/target-languages`](get-target-languages) endpoint for a list of supported languages and [`/list-voices`](list-voices) endpoint for a list of available voices which includes public voices and your own custom voices.


# Create Translation
Source: https://docs.camb.ai/api-reference/endpoint/create-translation

post /translate
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": "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.


# Create Translation Stream
Source: https://docs.camb.ai/api-reference/endpoint/create-translation-stream

post /translation/stream
Deprecated: Convert text between languages in real-time with contextual adaptations, delivering translated content as it's generated for immediate use in conversational interfaces and live applications.

<Warning>
  This endpoint is deprecated. For new integrations, use the standard translation task flow with [`POST /translation`](create-translation), then poll task status and fetch the completed result.
</Warning>

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     |

### Language Support

* Configure your translation pipeline using:

  * [`/source-languages`](get-source-languages) - Supported input languages

  * [`/target-languages`](get-target-langauages) - Available output languages

## Implementation Guide

Streaming Translation Workflow:

<CodeGroup>
  ```python Streaming using Sync Python [expandable] theme={null}
  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)
  ```

  ```python Streaming using Async Python [expandable] theme={null}
  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())
  ```
</CodeGroup>

<Tip title="Implementation Choice">
  **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
</Tip>

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


# Create Text-to-Speech
Source: https://docs.camb.ai/api-reference/endpoint/create-tts

post /tts
Deprecated: Convert text to natural-sounding speech with customizable voice settings, allowing you to generate audio files for playback in your applications.

<Card icon="lightbulb" href="create-tts-stream">
  The asynchronous `POST /tts` flow is deprecated. If you’re starting a new integration, use `POST /tts-stream` instead—you receive audio as it’s generated, without juggling task status, run IDs, and separate download calls.
</Card>

This endpoint transforms your written text into remarkably natural speech, opening up possibilities for narration, accessibility features, and interactive experiences in your applications. When you provide text along with voice preferences, our Model creates an audio file that captures the nuances and natural flow of human speech.

## Personalizing Your Voice

### Voice Personalization Options

You can shape the character of your generated voice by specifying these key attributes:

* **Gender**: Select the voice gender with a simple numeric code:

* **Age**: Add in the voice age to reflect the intended audience or context.

### Selecting Your Voice

Our platform offers two approaches to finding the perfect voice:

* **Choose from our voice library:** Browse our collection of ready-to-use voices through the [`/list-voices`](list-voices) endpoint to find the perfect match for your project.

* **Use your signature voice:** Utilize the [`/create-custom-voice`](create-custom-voice) endpoint to clone an audio recording containing your signature voice.

### Language Support

Our technology supports numerous languages and dialects for global reach. 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.

## How the Process Works

This endpoint uses an asynchronous workflow, which means your application can keep doing other things while the speech is being generated. Here's how it works, step-by-step:

<Steps>
  <Step title="Submit Your Request">
    Start by sending in your text, along with voice preferences such as language, age, and gender. You can also specify a voice from our library or a custom voice you've created.
  </Step>

  <Step title="Receive Your `task_id`">
    Once your request is received, our system instantly returns a unique `task_id`. This lets you check back later to see how things are going—just like tracking a package.
  </Step>

  <Step title="Track Progress of Your Speech Generation">
    Use your `task_id` to check the current status of your request by calling the [`/tts/{task_id}`](get-tts-result) endpoint. You’ll know whether your audio is still being generated, completed, or if something went wrong.
  </Step>

  <Step title="Retrieve the Final Audio File">
    When your task is marked as complete (`SUCCESS`), you'll get a `run_id`. Use this ID to download your final audio file from the [`/tts-result/{run_id}`](get-tts-result) endpoint.
  </Step>
</Steps>

This approach works particularly well for longer passages or when processing multiple requests simultaneously.

## Example: Creating Your First Audio

Here's a practical example showing how to generate speech about Mars:

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

# Define the text and voice characteristics
tts_payload = {
    "text": "Mars, the red planet, captivates our imagination with its rusty landscape, ancient river valleys, and massive polar ice caps. Its thin atmosphere whispers of a warmer, wetter past that scientists are eager to understand.",
    "voice_id": 147320,    # Replace with your chosen voice ID
    "language": "en-us",   # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "gender": 1,        # Male voice
    "age": 30           # Adult voice characteristic
}

# 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 text-to-speech request
response = requests.post(
    "https://client.camb.ai/apis/tts",
    json=tts_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"Speech task created! Task ID: {task_id}")

# Step 2: Check progress until complete
while True:
    status_response = requests.get(
        f"https://client.camb.ai/apis/tts/{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 == "FAILED":
        print("Task failed!")
        break

    # Wait before checking again
    time.sleep(2)

# Step 3: Download your audio file
if status == "SUCCESS":
    print(f"Speech ready! Run ID: {run_id}")
    audio_response = requests.get(
        f"https://client.camb.ai/apis/tts-result/{run_id}",
        headers=headers,
        stream=True
    )

    # Save the audio file
    with open("speech.wav", "wb") as audio_file:
        for chunk in audio_response.iter_content(chunk_size=1024):
            if chunk:
                audio_file.write(chunk)

    print("✨ Generated speech was saved as 'speech.wav'")
```

With this approach, you can create engaging audio content that brings your text to life while your application continues performing other tasks during processing.


# Stream Text-to-Speech Audio
Source: https://docs.camb.ai/api-reference/endpoint/create-tts-stream

post /tts-stream
Convert text to speech in real-time with customizable voice characteristics, delivering audio content as it's generated for immediate playback in your applications.

[Camb AI Python SDK Examples](https://github.com/camb-ai/cambai-python-sdk/tree/main/examples/async_tts_call.py)

[Link To Detailed Models Overview](/models)

## How the Streaming Process Works

Our streaming service is designed for simplicity and speed. Here’s how it works from request to playback:

<Steps>
  <Step title="Submit Your Text & Configuration">
    Send a POST request containing your text and desired audio configuration, including the voice, language, and output format.
  </Step>

  <Step title="Receive the Audio Stream">
    The server immediately begins processing and sends audio data back in chunks over the same connection. Your application can start playing the audio as soon as the first chunk arrives.
  </Step>

  <Step title="Manage Playback & Usage">
    Continue reading the byte stream until the connection closes, which signals the end of the audio. You can also monitor real-time usage via the `X-Credits-Required` header included in the response.
  </Step>
</Steps>

### Language Support

The `language` field takes a **BCP-47 locale code** (e.g. `en-us`, `hi-in`, `zh-cn`). It controls the accent and pronunciation of the generated speech — the model does **not** translate the input text, so the text you supply should already be written in the target language.

#### Coverage by model

| Speech model                               | Locales supported |
| :----------------------------------------- | :---------------- |
| `mars-flash`, `mars-pro`                   | 33                |
| `mars-8.1-flash-beta`, `mars-8.1-pro-beta` | 312               |
| `mars-instruct`                            | 142               |

See the full per-model locale list in [Language Support](/language-support).

<Note>
  Haryanvi (`bgc-in`) and Bhojpuri (`bho-in`) are supported only by
  `mars-instruct`. Set `speech_model` explicitly to `mars-instruct` when using
  either locale; the endpoint otherwise defaults to `mars-pro`, which rejects
  them with HTTP 422.
</Note>

#### Choosing a locale

* Use the most specific regional variant available for the accent you want. For example, prefer `es-mx` over `es-es` for a Mexican Spanish accent, or `zh-cn-sichuan` over `zh-cn` for a Sichuan-flavored Mandarin.
* For best results on the MARS 8.1 beta models, supply a **reference voice in the same language and accent** as the target locale.
* Codes are case-sensitive lowercase (e.g. `pt-br`, not `pt-BR`).

#### Validation behavior

If the requested `language` is not supported by the selected `speech_model`, the API responds with **HTTP 422** and a `ValidationError` body that lists the allowed locales for that model. Example:

```json theme={null}
{
  "detail": [{
    "loc": ["body"],
    "msg": "Value error, Language 'zh-tw' is not supported for speech model 'mars-flash'. Allowed languages are: ['en-us', 'en-in', 'zh-cn', ...]"
  }]
}
```

### Advanced Customization

Fine-tune the audio with additional parameters to control the performance, style, and quality of the generated speech. These are sent in the same JSON payload.

* **`speech_model`**: Specify the model for synthesis. Available values include `mars-8.1-flash-beta`, `mars-8.1-pro-beta`, `mars-flash`, `mars-pro`, and `mars-instruct`.
* **`user_instructions`**: Guide the voice's overall delivery (e.g., "Warm, clear, and conversational"). Only send this when `speech_model` is `mars-instruct`.
* **Expressive text tags**: With `mars-instruct`, you can also embed delivery tags directly in the `text` field (for example, emotion tags or SSML-style pauses) to shape pacing and tone around specific lines.
* **`output_configuration`**: Set the audio format (`wav`, `mp3`), sample rate, and toggle output enhancement.
  * `apply_enhancement` (boolean, optional): Applies output audio enhancement (loudness, denoising, polish). Defaults to `true` for most models, `false` for the speed-oriented `mars-flash` and `mars-8.1-flash-beta` models. Set explicitly to override.
* **`voice_settings`**: Enhance reference audio quality, maintain the source accent, or adjust the speaking rate.
* **`inference_options`**: Adjust stability, temperature, and speaker similarity for unique results.

<Note>
  `user_instructions` is only supported when `speech_model` is set to `mars-instruct`.
</Note>

<Note>
  The `mars-8.1-flash-beta` and `mars-8.1-pro-beta` models do not support the following parameters:

  * `acoustic_quality_boost`
  * `temperature`
  * `speaker_similarity`
  * `maintain_source_accent`
  * `stability`
  * `output_enhancement`
  * `enhance_named_entities_pronunciation`
  * `localize_speaker_weight`
</Note>

### MARS 8.1 Beta Text Controls

The `mars-8.1-flash-beta` and `mars-8.1-pro-beta` models support inline controls for English pronunciation and expressive non-verbal sounds. Add these controls directly in the `text` field.

#### Pronunciation Control (English)

Use CMU pronunciation dictionary phonemes in uppercase, wrapped in brackets, to override default English pronunciations.

```python theme={null}
payload = {
    "text": "He plays the [B EY1 S] guitar while catching a [B AE1 S] fish.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-8.1-flash-beta"
}
```

#### Non-verbal Symbols

Insert supported tags directly in the text to add expressive non-verbal sounds.

```python theme={null}
payload = {
    "text": "[laughter] You really got me. I didn't see that coming at all.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-8.1-flash-beta"
}
```

Supported tags: `[laughter]`, `[sigh]`, `[confirmation]`, `[question]`, `[surprise]`, `[dissatisfaction]`.

### Expressive Text Tags (`mars-instruct`)

You can directly convey expression in the input text by adding short tags for delivery. For a deeper guide to emotion tag intensity, see the [Emotion Tag Gradation Guide](/tutorials/emotional-voice-control#emotion-tag-gradation-guide).

* `[speaking slowly] You need to understand this. It is very important. We should do this the right way.`
* `[angry] You need to understand this! It is very important, we should do this the right way!`
* `[gentle, reassuring] Take a deep breath. You're doing well. Let's go step by step.`
* `Please pause here <break time="500ms"/> then continue in a calm, clear tone.`

Keep tags short and place them near the sentence you want to influence.

<Note>
  For comprehensive examples and best practices, see the [Emotional Voice Control tutorial](/tutorials/emotional-voice-control).
</Note>

### Tips For Best Results:

* For texts with numbers expand the numbers to words. For example, instead of "123" to "one hundred twenty three" or "one two three" as you need.
* For code-switched sentences, perform transliteration to convert the text to your chosen TTS language.
  Both of above could be done by a small LLM.
* To adjust pacing or approximate length, use `voice_settings.speaking_rate`. The streaming TTS endpoint does not support a duration parameter.

### Output format support by model

Supported `output_configuration.format` values depend on the selected `speech_model`:

| Speech Model          | Supported output formats                                                                                   |
| :-------------------- | :--------------------------------------------------------------------------------------------------------- |
| `mars-8.1-flash-beta` | `wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be` |
| `mars-8.1-pro-beta`   | `wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be` |
| `mars-flash`          | `wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be` |
| `mars-pro`            | `wav`, `mp3`, `flac`, `adts`, `pcm_s16le`, `pcm_s16be`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be` |
| `mars-instruct`       | `wav`, `flac`, `adts`, `pcm_s16le`, `pcm_s32be`, `pcm_s32le`, `pcm_f32le`, `pcm_f32be`                     |

## Example: Real-time Audio Streaming

This example shows how to call the endpoint and save the incoming audio stream to a file.

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

payload = {
    "text": "Jupiter, the largest planet in our solar system, is a gas giant with swirling storms like the iconic Great Red Spot.",
    "language": "en-us",
    "voice_id": 147320,
    "speech_model": "mars-instruct",
    "user_instructions": "Warm, clear, and conversational.",
    "enhance_named_entities_pronunciation": True,
    "output_configuration": {
        "format": "wav"
    },
    "voice_settings": {
        "enhance_reference_audio_quality": False,
        "maintain_source_accent": False,
        "speaking_rate": 1.0
    },
    "inference_options": {
        "inference_steps": 60,
    }
}

headers = {
    "x-api-key": "your-api-key"
}

response = requests.post(
    "https://client.camb.ai/apis/tts-stream",
    json=payload,
    headers=headers,
    stream=True
)

response.raise_for_status()

with open("output.wav", "wb") as audio_file:
    for chunk in response.iter_content(chunk_size=1024):
        if chunk:
            audio_file.write(chunk)

print("✨ Stream complete. Audio saved to output.wav")
```

## SDK Example: Async Streaming

```python theme={null}
import asyncio
from camb.client import AsyncCambAI, save_async_stream_to_file
from camb.types.stream_tts_output_configuration import StreamTtsOutputConfiguration
from camb.types.stream_tts_voice_settings import StreamTtsVoiceSettings

# Initialize the async client
client = AsyncCambAI(api_key="your-api-key")

async def main():
    # Stream the TTS generation
    response = client.text_to_speech.tts(
        text="Experience high quality realistic sounds with Camb AI.",
        language="en-us",
        speech_model="mars-8.1-flash-beta",
        voice_id=<voice_id>,
        voice_settings=StreamTtsVoiceSettings(
            speaking_rate=1.0
        ),
        output_configuration=StreamTtsOutputConfiguration(
            format="wav"
        )
    )
    
    # Save the stream to a file (or process chunks as they arrive)
    await save_async_stream_to_file(response, "async_stream_output.wav")
    print("Audio stream saved to async_stream_output.wav")

if __name__ == "__main__":
    asyncio.run(main())
```

## Streaming vs. Asynchronous: Which to Choose?

Select the right tool for your job by understanding the key differences between our TTS endpoints.

<CardGroup>
  <Card title="Use Streaming" icon="bolt">
    Ideal for real-time, interactive experiences where immediate audio feedback is crucial.
  </Card>

  <Card title="Use Asynchronous" icon="clock">
    Perfect for non-real-time tasks, long-form content, or when you need to retrieve a complete audio file later.
  </Card>
</CardGroup>


# Delete a Dictionary
Source: https://docs.camb.ai/api-reference/endpoint/delete-dictionary

delete /dictionaries/{dictionary_id}
Permanently removes a dictionary and all its associated terms and translations from the system. This irreversible action completely eliminates the dictionary's data and cannot be undone.

## Overview

Deleting a dictionary represents one of the most consequential operations you can perform in a dictionary management system. Unlike updating or retrieving information, deletion is permanent and irreversible, making it essential to understand both the technical mechanics and the broader implications of this action before implementing it in your applications.
When you delete a dictionary, you're not simply removing a reference or hiding the content from view. Instead, you're instructing the system to completely eliminate the dictionary and everything it contains from the database. This includes not only the dictionary's identifying information and metadata, but also every single term-translation pair that was stored within it.

## Understanding the Permanence of Deletion

The irreversible nature of dictionary deletion serves important purposes in data management, but it also creates significant responsibilities for developers and users. From a system perspective, permanent deletion helps maintain database efficiency by truly removing unused data rather than simply marking it as inactive. This approach prevents the accumulation of obsolete records that could slow down queries and consume storage space unnecessarily.
However, this permanence also means that any applications, workflows, or users that depend on the deleted dictionary will immediately lose access to that data. References to the dictionary will become invalid, translation lookups will fail, and any cached content based on that dictionary may become inconsistent with the system state. Understanding these cascading effects helps you design better error handling and user communication around deletion operations.


# Delete a Term in Dictionary
Source: https://docs.camb.ai/api-reference/endpoint/delete-term-in-dictionary

delete /dictionaries/term/{dictionary_id}/{term_id}
Permanently removes a specific term and all its associated translations from a dictionary, providing precise control over dictionary content while maintaining the integrity of remaining terms.

Deleting individual terms from dictionaries represents a fundamentally different operation from deleting entire dictionaries, though both share the characteristic of permanent data removal. When you delete a term, you're performing linguistic surgery - carefully removing specific content while preserving the broader dictionary structure and all other terms that users and applications depend upon.

## The Architecture of Precise Removal

The endpoint's design emphasizes surgical precision through its dual-parameter approach, requiring you to specify both the dictionary context and the exact term to be removed. This two-level targeting system prevents the kind of broad, accidental deletions that could damage valuable linguistic resources while ensuring that removal operations affect exactly the content you intend to eliminate.

## The Permanence Factor in Term Deletion

Like dictionary deletion, term deletion is permanent and irreversible, but the scope of impact differs significantly. When you delete a term, you're removing not just the source language entry, but all associated translations, usage examples, metadata, and any other linguistic information connected to that term concept. This comprehensive removal ensures that no orphaned data remains in the system, but it also means that recovery requires rebuilding the entire term entry from scratch.

## Quality Considerations in Term Removal

Consider how term deletion might affect users who have grown accustomed to finding specific terminology in your dictionary. Applications that cache dictionary content might need updates to reflect the removal, and any bookmarks or saved references to the deleted term will become invalid. Understanding these downstream effects helps you plan term deletion operations as part of broader dictionary maintenance strategies rather than isolated removal actions.


# Delete a Voice
Source: https://docs.camb.ai/api-reference/endpoint/delete-voice

delete /delete-voice/{voice_id}
Permanently deletes a custom voice from your workspace using its voice ID.

## Overview

Use this endpoint to remove a custom voice you no longer need. You can delete only voices you created, and you must use an API key from the workspace that owns the voice.
This is a permanent action, so make sure the voice is not used by any active workflows before deleting it.

## Path Parameter

* `voice_id`: The numeric ID of the voice to delete (for example, `9013`).

## Example Request

```bash theme={null}
curl -X DELETE "https://client.camb.ai/apis/delete-voice/9013" \
  -H "x-api-key: YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "status": "ok"
}
```


# End to End Dubbing
Source: https://docs.camb.ai/api-reference/endpoint/end-to-end-dubbing

post /dub
Initiate a full end to end dubbing task.

Transform your media content for global audiences with our comprehensive dubbing solution. This powerful endpoint automates the entire dubbing process, taking your original media and producing a version that speaks naturally in your target language. The system handles everything from transcription to voice synthesis, delivering professional-quality results without requiring specialized audio engineering knowledge.

## The Dubbing Process

When you submit a dubbing request, our system begins a multi-stage workflow:

<Steps>
  <Step title="Project Setup">
    Our intelligent system works its magic behind the scenes to prepare your content for flawless localization.
  </Step>

  <Step title="Translation">
    The transcribed text is expertly translated to your target language using our proprietary translation engine [BOLI](https://www.camb.ai/#Research).
  </Step>

  <Step title="Voiceover Generation">
    Voiceovers are created using natural-sounding synthetic voices using our in-house novel speech model [MARS](https://www.camb.ai/#Research).
  </Step>

  <Step title="Final Assembly">
    Everything is combined into a seamless final product.
  </Step>
</Steps>

Throughout this process, you can check on your task's progress using the [`/dub/{task_id}`](get-end-to-end-dubbing-status) endpoint with the `task_id` provided in your initial response.

## Compatible Media Sources

Our dubbing service accommodates various media sources to fit your workflow needs. The `video_url` parameter in your request can point to any of the following:

### Online Platforms

Use content directly from popular content platforms:

* **YouTube videos**: Simply provide the standard YouTube video URL.
* **Google Drive**: Link to media files stored in Google Drive (ensure they're publicly accessible).
* **Direct URLs**: Any direct link to a media file that doesn't require authentication.

### Supported File Formats

Our system processes a wide range of professional and consumer media formats:

| Media Type  | Supported Formats   |
| :---------- | :------------------ |
| Video Files | MP4, MOV, MXF       |
| Audio Files | MP3, FLAC, WAV, AAC |

This flexibility allows you to work with both broadcast-quality content and consumer-grade media without conversion hassles.

<Info>Please note that MXF format support is exclusively available to customers on our Enterprise plan, offering professional broadcast-quality media handling for organizations with advanced needs.</Info>

## Language Configuration

Specifying the right languages is crucial for successful dubbing. Your request needs to include:

* **Source Language**: The original language spoken in your media.
* **Target Language(s)**: The language(s) you want your content to be dubbed into.

Both parameters require specific language identifiers from our system. To find the correct IDs:

1. Query the [`/source-languages`](get-source-languages) endpoint for available source language options.
2. Check the [`/target-languages`](get-target-languages) endpoint for supported target languages.

Using these official IDs ensures our system correctly processes your content.

## Transcription Mode

The optional `transcription_mode` request field controls the transcription pass used before dubbing:

* **`fast`** (default): returns a transcript more quickly while maintaining quality.
* **`slow`**: takes longer and may produce a more accurate transcript through a more thorough pass.

Omit the field to use `fast`.

## Keeping Music in the Foreground

The optional `include_music_in_fg` parameter controls how background music is handled during source separation:

* **`true`** (default): music is preserved in the foreground audio alongside speech.
* **`false`**: music is stripped out of the foreground, isolating speech.

Omit the parameter to keep the default behaviour of retaining music.

## Creating Your First Dubbing request

Let's look at how to initiate a dubbing task with Python:

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

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

# Define your dubbing request parameters
dubbing_request = {
    "video_url": "https://www.youtube.com/watch?v=exampleVideo",  # Your media URL
    "source_language": "en-us",      # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    "target_languages": ["es-es"],
    "transcription_mode": "fast",
    "include_music_in_fg": True,     # keep music in the foreground audio (default); set False to strip it
}

# Submit the dubbing request
def submit_dubbing_task(payload):
    """
    Submits a new dubbing task and returns the task ID for tracking.
    """
    try:
        response = requests.post(
            "https://client.camb.ai/apis/dub",
            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"Dubbing task submitted successfully! Task ID: {task_id}")
        return task_id

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

# Call the function to submit your dubbing task
task_id = submit_dubbing_task(dubbing_request)
```

## Monitoring Your Dubbing Progress

After submission, your content enters our processing pipeline. The time required depends on the length and complexity of your media. You can check progress by polling the status endpoint:

```python [expandable] theme={null}
def check_dubbing_status(task_id):
    """
    Checks the status of a dubbing task.
    Returns the current status and any available result information.
    """
    if not task_id:
        print("No task ID provided.")
        return None

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/dub/{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']}")

        return status_data

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

# Check the status of your task
status_info = check_dubbing_status(task_id)
```

## Use Your Own Transcript or Translation

You can include SRT file contents directly in the JSON body of `POST /dub`:

* `source_transcript`: an optional transcript in `source_language`.
* `target_transcripts`: optional translations, each with a `language` matching one
  of your requested target languages. Supply at most one SRT per language.

Each script takes `content` containing the SRT text and an optional `format`, whose
only supported value is `srt`. Read the file as UTF-8; do not send a filename, URL,
base64 string, multipart upload, or an array of segments.

```python theme={null}
from pathlib import Path
import requests

payload = {
    "video_url": "https://example.com/video.mp4",
    "source_language": "en-us",
    "target_languages": ["es-es", "fr-fr"],
    "source_transcript": {
        "format": "srt",
        "content": Path("original.srt").read_text(encoding="utf-8"),
    },
    "target_transcripts": [
        {
            "language": "es-es",
            "format": "srt",
            "content": Path("spanish.srt").read_text(encoding="utf-8"),
        }
    ],
}
response = requests.post(
    "https://client.camb.ai/apis/dub",
    headers={"x-api-key": "your-api-key"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["task_id"]
```

This example supplies the original transcript and Spanish translation; French is
translated automatically. You can also send only `source_transcript`, only
`target_transcripts`, or neither. If you have the original transcript, include it
alongside your translations to provide source-language context. Requests without
these fields retain the existing automatic workflow. The task ID, polling, and
result endpoints are unchanged.

The API stores supplied scripts as temporary `.srt` objects under `temp/` in your
workspace's configured storage before passing them to the dubbing pipeline.

An SRT `content` string looks like this in JSON:

```json theme={null}
{
  "format": "srt",
  "content": "1\n00:00:00,500 --> 00:00:02,800\nWelcome back.\n"
}
```

### Validation and limits

* Maximum **2 MiB of UTF-8 text per script**; **10 MiB combined**
  across the original and translations, with at most 100 target scripts.
* Scripts must contain at least one cue parseable by the `srt` library.
  Standard SRT uses `HH:MM:SS,mmm --> HH:MM:SS,mmm` and blank lines between cues.
  Parsing uses the `srt` library with parse errors enabled; its supported
  variations, including dot-separated milliseconds, are also accepted.
* Overlapping and out-of-order cues are accepted. No additional cue-count,
  numbering, timing, control-character, or dialogue-content checks are imposed
  beyond the parser. UTF-8 BOM and Windows/Mac line endings are normalized.
* Target scripts must use supported languages selected in `target_languages`
  (or the legacy `target_language`). Language aliases are normalized before
  checking for duplicates. Unknown properties inside a script are rejected.

Invalid scripts return **HTTP 422** before script storage or dubbing submission.
Errors identify the input field. Unparseable SRT returns
`SRT content could not be parsed; check cue numbers and timestamps`.

Use timestamps relative to the original media and scripts that match that media.
Request validation checks SRT structure; it does not download the media to check
its duration or verify the language of your text. Supplied scripts use the existing
dubbing pipeline's timing and speech processing; this option does not introduce
an exact-wording or exact-timing output mode.

## Best Practices for Optimal Results

To get the most from our dubbing service, consider these professional tips:

1. **Source Quality Matters**: Higher quality original media yields better dubbing results.
2. **Language Selection**: Choose the right language for your audience to ensure clarity and authenticity.

## Practical Applications

Our end-to-end dubbing functionality opens exciting possibilities across industries:

* **E-Learning**: Make educational content accessible to global learners.
* **Marketing**: Localize promotional videos for international markets.
* **Entertainment**: Bring films and shows to new language audiences.
* **Corporate Communications**: Ensure company messages reach multilingual teams.
* **Social Media**: Expand your content's reach across language barriers.

By integrating this API into your workflow, you can dramatically reduce the time and expense traditionally associated with professional dubbing while maintaining impressive quality.


# Get Audio Separation Run Results (Bulk)
Source: https://docs.camb.ai/api-reference/endpoint/fetch-audio-separation-run-info-results

post /audio-separation-results
Retrieve separated audio components for multiple completed Audio Separation tasks using multiple run IDs.

# Accessing Multiple Separated Audio Collections

This endpoint enables you to retrieve the results from multiple completed audio separation tasks in a single, efficient request. Instead of making individual requests for each audio separation result, you can fetch foreground and background audio components from several processing runs simultaneously, streamlining your workflow when dealing with batch audio operations.

Each audio separation task produces two distinct audio tracks from your original recording: a **foreground** track containing primary audio elements (speech, vocals, or main instruments) and a **background** track with supporting elements (ambient sounds, musical accompaniment, or secondary audio). This bulk endpoint allows you to collect these separated components from multiple runs at once, making it ideal for applications processing audio libraries, podcast batches, or large-scale content analysis projects.

## How Bulk Audio Separation Retrieval Works

The bulk retrieval system operates on a simple principle: you provide an array of run IDs corresponding to your completed audio separation tasks, and the system returns organized results for each requested separation. This approach offers significant advantages over individual retrieval requests:

**Efficiency Benefits:**

* Reduces network overhead by consolidating multiple requests into one
* Minimizes latency when retrieving results from several audio separation tasks
* Simplifies client-side code for handling multiple audio file collections
* Provides better performance for batch audio processing workflows

**Practical Applications:**

* Processing results from multiple podcast episodes or music tracks
* Building audio libraries with separated components
* Batch operations for content creators working with multiple recordings
* Automated workflows that separate audio from video content in bulk

## Request Format

The endpoint expects a JSON payload containing an array of run IDs that identify the audio separation tasks you want to retrieve results for:

```json theme={null}
{
  "run_ids": [
    "12345",
    "45678",
    "112233"
  ]
}
```

Each run ID should correspond to a previously initiated audio separation task. The system processes all provided run IDs and returns results for those that have completed successfully.

## Response Structure

The response contains an array of results, where each item corresponds to one of the requested run IDs. For successful separations, each result includes both foreground and background audio URLs:

```json theme={null}
  [
    12345: {
      "foreground_audio_url": "https://storage.example.com/audio/12345_foreground.wav",
      "background_audio_url": "https://storage.example.com/audio/12345_background.wav"
    },
    45678: {
      "foreground_audio_url": "https://storage.example.com/audio/45678_foreground.wav",
      "background_audio_url": "https://storage.example.com/audio/45678_background.wav"
    }
  ]
```

**Understanding the Response Fields:**

* **run\_id**: The original run ID you provided in the request
* **status**: Current status of the separation task (completed, failed, processing)
* **foreground\_audio\_url**: Direct download URL for the isolated foreground audio components
* **background\_audio\_url**: Direct download URL for the isolated background audio components
* **error**: Error message explaining why a separation task failed (only present for failed tasks)

## Understanding Separated Audio Components

Each successful audio separation produces two complementary audio files that work together to reconstruct your original recording:

**Foreground Audio Components:**

* Contain dominant audio elements like vocals, speech, or lead instruments
* Represent the primary focus of the recording
* Ideal for creating karaoke tracks, enhancing speech clarity, or isolating musical performances
* Typically contain the most prominent frequency ranges and temporal patterns

**Background Audio Components:**

* Contain ambient sounds, musical accompaniment, or secondary audio elements
* Provide context and support to the foreground elements
* Perfect for creating instrumental tracks, ambient soundscapes, or removing unwanted background noise
* Include the supporting audio texture that gives recordings their full character

### Organizing Separated Audio Collections

```python [expandable] theme={null}
import requests
import os
from typing import List, Dict, Optional


def download_audio(url: str, filepath: str) -> bool:
    """
    Download audio file from URL to specified filepath
    """
    try:
        response = requests.get(url, stream=True)
        response.raise_for_status()

        with open(filepath, "wb") as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)

        print(f"Downloaded: {filepath}")
        return True
    except requests.exceptions.RequestException as e:
        print(f"Failed to download {url}: {e}")
        return False


def organize_separation_results(run_ids: List[int], output_dir: str) -> Optional[Dict]:
    """
    Retrieve and organize multiple audio separation results
    Args:
        run_ids: List of run IDs to fetch results for
        output_dir: Directory to save organized results
    Returns:
        Dictionary containing organized results or None if request fails
    """
    try:
        # Make API request
        response = requests.post(
            "https://client.camb.ai/apis/audio-separation-results",
            headers={"x-api-key": "YOUR_API_KEY_HERE", "Content-Type": "application/json"},
            json={"run_ids": run_ids},
        )
        response.raise_for_status()
        results = response.json()

        # Create main output directory
        os.makedirs(output_dir, exist_ok=True)

        organized_results = {}

        # Process each result (key is run_id as string, value is the result data)
        for run_id_str, result_data in results.items():
            run_id = int(run_id_str)

            # Create directory for this separation
            run_dir = os.path.join(output_dir, f"run_{run_id}")
            os.makedirs(run_dir, exist_ok=True)

            # Download foreground audio
            foreground_url = result_data["foreground_audio_url"]
            foreground_path = os.path.join(run_dir, "foreground.flac")
            foreground_success = download_audio(foreground_url, foreground_path)

            # Download background audio
            background_url = result_data["background_audio_url"]
            background_path = os.path.join(run_dir, "background.flac")
            background_success = download_audio(background_url, background_path)

            # Store organized result info
            organized_results[run_id] = {
                "directory": run_dir,
                "foreground_url": foreground_url,
                "background_url": background_url,
                "foreground_path": foreground_path if foreground_success else None,
                "background_path": background_path if background_success else None,
                "download_success": foreground_success and background_success,
            }

            status = "✓" if organized_results[run_id]["download_success"] else "✗"
            print(f"{status} Organized separation results for run_id {run_id}")

        print(f"\nProcessed {len(organized_results)} separation results")
        print(f"Results saved to: {output_dir}")

        return organized_results

    except requests.exceptions.HTTPError as e:
        print(f"HTTP Error {e.response.status_code}: {e.response.text}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None
    except Exception as e:
        print(f"Unexpected error: {e}")
        return None


def print_summary(organized_results: Dict) -> None:
    """
    Print a summary of organized results
    """
    print("\n" + "=" * 50)
    print("AUDIO SEPARATION RESULTS SUMMARY")
    print("=" * 50)

    successful_downloads = 0
    failed_downloads = 0

    for run_id, result in organized_results.items():
        status = "SUCCESS" if result["download_success"] else "FAILED"
        print(f"Run ID {run_id}: {status}")
        print(f"  Directory: {result['directory']}")

        if result["download_success"]:
            successful_downloads += 1
            print(f"  Foreground: {result['foreground_path']}")
            print(f"  Background: {result['background_path']}")
        else:
            failed_downloads += 1
            print("Download failed for one or both audio files")
        print()

    print(f"Total: {len(organized_results)} results")
    print(f"Successful: {successful_downloads}")
    print(f"Failed: {failed_downloads}")


# Example usage
if __name__ == "__main__":
    # Example run IDs from your response
    run_ids_to_process = [112233, 456789]
    output_directory = "./audio_separation_results"

    # Organize the results
    results = organize_separation_results(run_ids_to_process, output_directory)

    if results:
        print_summary(results)

        # Example: Get all foreground audio paths for further processing
        foreground_paths = [
            result["foreground_path"]
            for result in results.values()
            if result["foreground_path"]
        ]

        if foreground_paths:
            print("\nForeground audio files ready for processing:")
            for path in foreground_paths:
                print(f"  - {path}")

```

## Status Management and Error Handling

When working with bulk audio separation results, individual tasks within your batch may have different statuses. The endpoint returns results for all requested run IDs, but some may not be ready yet or may have encountered processing errors.

**Common Status Scenarios:**

* **Mixed Status Results**: Some separations completed while others are still processing
* **Invalid Run IDs**: Non-existent run IDs will be marked with appropriate error status
* **Processing Failures**: Some audio files may fail separation due to format issues or processing errors
* **Expired URLs**: Older completed separations may have expired download URLs

**Best Practices for Status Management:**

1. Always check the status field before attempting to download audio files
2. Implement retry logic for tasks that are still processing
3. Handle failed separations gracefully with appropriate user feedback
4. Store successful results promptly as download URLs may expire
5. Log processing errors for debugging and quality improvement

## Audio Processing Workflow Integration

This bulk endpoint integrates seamlessly into larger audio processing workflows. Consider this typical pattern for handling multiple audio files:

1. **Submit Multiple Separations**: Upload several audio files for separation processing
2. **Collect Run IDs**: Store all returned run IDs from your separation requests
3. **Batch Status Checking**: Use this bulk endpoint to check the status of multiple separations simultaneously
4. **Process Completed Separations**: Download and organize foreground and background audio files
5. **Handle Incomplete Tasks**: Retry processing for failed separations or wait for still-processing tasks

This workflow is particularly effective for:

* **Podcast Production**: Separating speech from background music across multiple episodes
* **Music Production**: Isolating vocals and instruments from multiple tracks
* **Content Analysis**: Processing large audio libraries for machine learning or analysis
* **Accessibility Enhancement**: Creating separate audio tracks for improved accessibility

## Technical Considerations

**Audio Format and Quality:**
The separated audio files are typically delivered in high-quality formats suitable for professional audio editing. Both foreground and background components maintain the original audio quality while providing clean separation between different audio elements.

**File Size and Storage:**
Since each original audio file produces two separate output files (foreground and background), consider storage requirements when processing large batches. The combined size of separated files will be larger than the original due to the dual-track output.

**Download URL Expiration:**
The presigned URLs returned in the response are temporary and will expire after a certain period. Implement prompt download and storage strategies to ensure you don't lose access to your separated audio files.

**Processing Time Considerations:**
Audio separation is a computationally intensive process. When submitting multiple files, processing times can vary based on audio length, complexity, and current system load. The bulk results endpoint helps you efficiently monitor multiple separations without overwhelming the system with frequent individual status checks.

**Quality Optimization:**
The effectiveness of audio separation depends on the characteristics of your original audio. Files with clear distinction between foreground and background elements (like speech over music) typically produce better separation results than complex multi-layered audio with overlapping frequency ranges.

By leveraging this bulk audio separation results endpoint, you can build sophisticated audio processing applications that handle multiple separations efficiently, enabling creative workflows that scale with your audio production needs while maintaining professional quality standards.


# Fetch Dubbing Results in Bulk
Source: https://docs.camb.ai/api-reference/endpoint/fetch-dubbed-runs-info

post /dubbing-results
Retrieves the results of multiple dubbing runs simultaneously using an array of `run_id` values

Efficiently retrieve the results of multiple dubbing tasks in a single API call. This bulk endpoint allows you to fetch completed dubbing results for multiple runs at once, making it ideal for applications that need to process large volumes of content or manage multiple dubbing projects simultaneously.

## Understanding Bulk Dubbing Results

When you request the results of multiple completed dubbing tasks, our system returns a comprehensive collection of results, with each entry containing:

* **Dubbed Video**: A complete video file with the original visuals and newly generated voiceover in your target language.
* **Dubbed Audio**: An isolated audio track containing only the synthesized speech in your target language.
* **Complete Transcript**: A detailed, time-coded transcript of the dubbed content with speaker identification.

This bulk approach significantly reduces the number of API calls needed when working with multiple dubbing projects, improving efficiency and reducing latency in your applications.

## Accessing Multiple Dubbed Results

To retrieve results for multiple dubbing tasks, you'll need to provide an array of `run_id` values in the request payload. Each `run_id` uniquely identifies a specific dubbing task that was created through our dubbing pipeline.

### Request Payload Structure

The request body should contain an array of run IDs:

```json theme={null}
{
  "run_ids": [12345, 67890, 24680, 13579]
}
```

## Example Request with Python

Here's how to fetch multiple dubbing results using Python:

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

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


def get_bulk_dubbing_results(run_ids):
    """
    Retrieves the results of multiple dubbing tasks in a single request.
    Returns a collection of dubbing results with media URLs and transcripts.
    """
    payload = {"run_ids": run_ids}

    try:
        response = requests.post(
            "https://client.camb.ai/apis/dubbing-results",
            headers=headers,
            json=payload,
        )

        # Verify the request was successful
        response.raise_for_status()

        # Extract the bulk dubbing results
        results_data = response.json()

        print(f"Successfully retrieved results for {len(results_data)} dubbing runs")

        # Process each result
        for key in results_data:
            print(f"Run ID: {key}")
            print(f"\nVideo URL: {results_data.get(key, {}).get('video_url')}")
            print(f"\nAudio URL: {results_data.get(key, {}).get('audio_url')}")
            print(f"\nTranscript entries: {len(results_data.get(key, {}).get('transcript', []))}")

        return results_data

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving bulk dubbing results: {e}")
        if hasattr(e, "response") and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None


# Example usage with multiple run IDs
run_ids = [41707, 40413]  # Replace with your actual run IDs
bulk_results = get_bulk_dubbing_results(run_ids)

# Process successful results
if bulk_results:
    print(f"\n{len(bulk_results)} runs completed successfully:")

    for result in bulk_results:
        run_id = result
        transcript = bulk_results.get(run_id, {}).get("transcript", [])

        if transcript:
            print(f"\nRun ID {run_id} - Transcript Preview:")
            for i, dialogue in enumerate(transcript[:2]):  # Show first 2 entries
                speaker = dialogue.get("speaker", "Unknown")
                text = dialogue.get("text", "")
                start = dialogue.get("start", "")
                end = dialogue.get("end", "")
                print(f"  Speaker {speaker}: {text} [{start} - {end}]")

            if len(transcript) > 2:
                print(f"  ... and {len(transcript) - 2} more dialogue entries")
```

## Response Handling

The bulk endpoint returns results for all requested run IDs, including those that may still be processing or have failed. Each result in the response includes:

* `video_url`: URL to the dubbed video (if completed)
* `audio_url`: URL to the dubbed audio (if completed)
* `transcript`: Complete transcript with timing information (if completed)

## Best Practices

When using the bulk dubbing results endpoint:

* **Batch Size**: Limit your requests to reasonable batch sizes (recommended: 50-100 run IDs per request) to ensure optimal performance
* **Status Checking**: Always check the status of each result before attempting to access media URLs or transcripts
* **Error Handling**: Implement proper error handling for individual failed runs within the bulk response

This bulk approach streamlines your workflow when managing multiple dubbing projects, reducing API overhead and improving the efficiency of your content localization pipeline.


# Fetch Project Setup Results
Source: https://docs.camb.ai/api-reference/endpoint/fetch-project-setup-runs-results

post /project-setup-results
Retrieve comprehensive setup results for multiple localization projects in a single API call, streamlining project management in CAMB.AI Studio.

## Overview

he **Get Bulk Project Setup Results** endpoint is your go-to tool for managing multiple content localization projects with ease. By retrieving comprehensive setup results for multiple projects in a single API call, this endpoint empowers project managers, content creators, and automation workflows to stay on top of large-scale localization efforts in [CAMB.AI Studio](https://studio.camb.ai).

With this endpoint, you can:

* Retrieve detailed setup results for multiple projects simultaneously.
* Gain insights into project readiness, including status, duration, and language configurations.

<Info>
  **Why Use This Endpoint?**
  This endpoint is a game-changer for teams managing multiple localization projects. It provides a unified view of your project portfolio, helping you coordinate tasks, allocate resources efficiently, and make data-driven decisions to keep your content pipeline on track.
</Info>

```python [expandable] theme={null}
import requests
from typing import Any


def fetch_bulk_story_results(run_ids: list[int]) -> dict[str, Any] | None:
    """
    Retrieves multiple story conversion outputs in a single request

    Args:
        run_ids: List of unique run identifiers from story processing tasks

    Returns:
        List of story result dictionaries, or None if request fails
    """
    headers = {
        "x-api-key": "your-api-key-here",
        "Content-Type": "application/json",
    }

    payload = {"run_ids": run_ids}

    try:
        response = requests.post(
            "https://client.camb.ai/apis/stories-results",
            headers=headers,
            json=payload,
        )
        response.raise_for_status()

        results = response.json()
        print(f"Retrieved {len(results)} story results successfully")

        return results

    except requests.exceptions.HTTPError as e:
        print(f"Error {e.response.status_code}: {e.response.text}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None


def process_bulk_results(results: dict[str, Any]) -> None:
    """
    Process and display bulk story results

    Args:
        results: List of story result dictionaries
    """
    for i, run_id_key in enumerate(results, start=1):
        print(f"\n--- Story {i} ---")
        print(f"Main Audio: {results.get(run_id_key, {}).get('audio_url')}")
        print(f"Dialogue Track: {results.get(run_id_key, {}).get('dialogue_url')}")

        transcription = results.get(run_id_key, {}).get("transcription", {})
        if transcription:
            print(f"Transcript entries: {len(transcription)}")
            first_entry = transcription[0]
            print(
                f"First line: [{first_entry['start']}-{first_entry['end']}ms] "
                f"{first_entry['speaker']}: {first_entry['text'][:50]}..."
            )


# Example usage with multiple run IDs
run_ids_to_fetch = [9872, 9873, 9874, 9875, 9876]

bulk_results = fetch_bulk_story_results(run_ids_to_fetch)

if bulk_results:
    process_bulk_results(bulk_results)

    # Example: Save audio URLs for batch download
    audio_urls = [
        bulk_results.get(result, {}).get("audio_url") for result in bulk_results
    ]
    print(f"\nExtracted {len(audio_urls)} audio URLs for batch processing")
```

## Best Practices for Effective Use

To maximize the value of this endpoint, consider these strategies:

1. **Group Projects Strategically**: Organize `run_ids` by priority, language pairs, or deadlines to align with your team's workflow.
2. **Batch Efficiently**: Balance the number of `run_ids` in each request to ensure fast response times and manageable data processing.


# Fetch Stories Results in Bulk
Source: https://docs.camb.ai/api-reference/endpoint/fetch-stories-runs-info

post /stories-results
Efficiently retrieve multiple story conversion outputs simultaneously using a collection of run identifiers

Streamline your workflow by retrieving results from multiple story conversion tasks in a single API call. This bulk endpoint eliminates the need for individual requests when managing large batches of story processing jobs, making it ideal for content management systems, automated publishing workflows, or analytics dashboards that need to aggregate story conversion results.

## Bulk Processing Benefits

This endpoint provides several operational advantages:

* **Reduced API Calls**: Fetch multiple story results with one request
* **Consistent Data Structure**: Uniform response format across all stories
* **Efficient Resource Usage**: Optimized for high-volume story retrieval
* **Batch Processing Support**: Perfect for automated content pipelines

### Request Structure

The endpoint accepts a JSON payload containing an array of run IDs from your story conversion tasks. Each run ID corresponds to a previously submitted story processing job.

<Note>
  All run IDs in the request must be valid and belong to completed story conversion tasks
</Note>

### Response Format

The API returns an array of story result objects, each containing the same structure as the individual story result endpoint:

* **Full Audio Narration**: Complete audiobook-style recording (`audio_url`)
* **Dialogue-Only Track**: Isolated character conversations (`dialogue_url`)
* **Time-Coded Transcript**: Narrative transcript with speaker attribution (`transcript`)

<Warning title="URL Expiration Notice">All retrieved audio links become inaccessible after 24 hours</Warning>

## Example Python Implementation

Here's how to fetch multiple story results efficiently using Python:

```python [expandable] theme={null}
import requests
from typing import List, Dict, Optional

def fetch_bulk_story_results(run_ids: List[int]) -> Optional[List[Dict]]:
    """
    Retrieves multiple story conversion outputs in a single request

    Args:
        run_ids: List of unique run identifiers from story processing tasks

    Returns:
        List of story result dictionaries, or None if request fails
    """
    headers = {
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    payload = {
        "run_ids": run_ids
    }

    try:
        response = requests.post(
            "https://client.camb.ai/apis/stories-results",
            headers=headers,
            json=payload
        )
        response.raise_for_status()

        results = response.json()
        print(f"Retrieved {len(results)} story results successfully")

        return results

    except requests.exceptions.HTTPError as e:
        print(f"Error {e.response.status_code}: {e.response.text}")
        return None
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

def process_bulk_results(results: List[Dict]) -> None:
    """
    Process and display bulk story results

    Args:
        results: List of story result dictionaries
    """
    for i, story in enumerate(results, 1):
        print(story)
        print(f"\n--- Story {i} ---")
        print(f"Main Audio: {results[story]['audio_url']}")
        print(f"Dialogue Track: {results[story]['dialogue_url']}")

        if results[story].get('transcript'):
            print(f"Transcript entries: {len(results[story]['transcript'])}")
            # Preview first dialogue entry
            if results[story]['transcript']:
                first_entry = results[story]['transcript'][0]
                print(f"First line: [{first_entry['start']}-{first_entry['end']}ms] "
                      f"{first_entry['speaker']}: {first_entry['text'][:50]}...")

# Example usage with multiple run IDs
run_ids_to_fetch = [240320, 242604]

bulk_results = fetch_bulk_story_results(run_ids_to_fetch)

if bulk_results:
    process_bulk_results(bulk_results)

    # Example: Save audio URLs for batch download
    audio_urls = [bulk_results[story]['audio_url'] for story in bulk_results]
    print(f"\nExtracted {len(audio_urls)} audio URLs for batch processing")
```

## Use Cases

This bulk endpoint is particularly valuable for:

* **Content Management Systems**: Retrieving story assets for publication workflows
* **Analytics Dashboards**: Aggregating conversion results for reporting
* **Automated Publishing**: Batch processing completed stories for distribution
* **Quality Assurance**: Bulk validation of story conversion outputs
* **Archive Management**: Collecting completed story assets for long-term storage


# Fetch Subtitle Results
Source: https://docs.camb.ai/api-reference/endpoint/fetch-subtitles-runs-results

post /sub-results
Retrieves the results of multiple subtitle runs using the provided run IDs in the request body.

Fetches subtitle results for several runs in one request. Each run's value matches [Get Subtitle Result](get-subtitle-run-result): structured JSON by default, or exported `srt`/`vtt`/`txt` when you pass `format_type` and/or `data_type`.

* **By default** (no query params) each run returns structured JSON: one language → `{ "transcript": [ ... ] }`; many → object keyed by language ID.
* **When you pass `format_type` and/or `data_type`**, each run is exported the same way as [Get Subtitle Result](get-subtitle-run-result): one language → `{ "transcript": <url|text> }`; many → `{ "<lang_id>": { "transcript": <url|text> }, ... }`.

## Choosing your output

| Parameter            | Values                                                  | Behaviour                              |
| :------------------- | :------------------------------------------------------ | :------------------------------------- |
| *(none)*             | n/a                                                     | Per run: structured JSON transcript(s) |
| `data_type=file`     | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | Per run: presigned file URL(s)         |
| `data_type=raw_data` | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | Per run: rendered text inline          |

Same `format_type` / `data_type` values as [Get Transcription Result](get-transcription-run-result) and [Get Subtitle Result](get-subtitle-run-result).

## Request

```json theme={null}
{
  "run_ids": [12345, 12346, 12347, 12348]
}
```

## Response Structure

The API returns an object keyed by `run_id`.

### Default (no export params)

```json [expandable] theme={null}
{
  "12345": {
    "transcript": [
      { "start": 0.0, "end": 2.5, "speaker": "SPEAKER_0", "text": "Welcome to our discussion on AI." }
    ]
  },
  "12346": {
    "1": {
      "transcript": [
        { "start": 0.0, "end": 2.5, "speaker": "SPEAKER_0", "text": "Welcome to our discussion on AI." }
      ]
    },
    "23": {
      "transcript": [
        { "start": 0.0, "end": 2.7, "speaker": "SPEAKER_0", "text": "Bienvenidos a nuestra discusión sobre IA." }
      ]
    }
  }
}
```

| Field     | Description                             |
| :-------- | :-------------------------------------- |
| `start`   | Start time of the segment (seconds)     |
| `end`     | End time of the segment (seconds)       |
| `text`    | Text for this segment, in that language |
| `speaker` | Speaker identifier                      |

### Export (`format_type` / `data_type`)

```json theme={null}
{
  "12345": { "transcript": "https://storage.example.com/.../output_transcript.srt?..." },
  "12346": {
    "1":  { "transcript": "https://storage.example.com/.../en_us/output_transcript.srt?..." },
    "23": { "transcript": "https://storage.example.com/.../es_es/output_transcript.srt?..." }
  }
}
```

<Info>Presigned file URLs expire after 24 hours.</Info>

## Implementation Example

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

headers = {
    "x-api-key": "your-api-key",
    "Content-Type": "application/json",
}

API_URL = "https://client.camb.ai/apis/sub-results"
run_ids = [12345, 12346, 12347, 12348]

# Default: structured JSON per run
bulk = requests.post(API_URL, headers=headers, json={"run_ids": run_ids}).json()
for run_id, run_result in bulk.items():
    if "transcript" in run_result:
        print(f"Run {run_id}: {len(run_result['transcript'])} segments")
    else:
        for language_id, payload in run_result.items():
            print(f"Run {run_id} / lang {language_id}: {len(payload['transcript'])} segments")

# Export: SRT file URLs for every language on every run
srt_bulk = requests.post(
    API_URL,
    headers=headers,
    params={"format_type": "srt", "data_type": "file"},
    json={"run_ids": run_ids},
).json()
for run_id, run_result in srt_bulk.items():
    if "transcript" in run_result:
        print(f"Run {run_id}: {run_result['transcript']}")
    else:
        for language_id, payload in run_result.items():
            print(f"Run {run_id} / lang {language_id}: {payload['transcript']}")
```

## Best Practices

* **Batch size**: at least 2 and at most 5 `run_id` values per request
* **Larger sets**: split into chunks of 3–5 and process sequentially to avoid rate limits

## Next Steps

1. [Get Subtitle Result](get-subtitle-run-result) for a single run (same export params)
2. [Get Subtitle Result for Language](get-subtitle-result-for-language) when you only need one language
3. [Create Subtitle](create-subtitle) to start a new run


# Fetch Sound and Music Run Results (Bulk)
Source: https://docs.camb.ai/api-reference/endpoint/fetch-text-to-sound-runs-results

post /text-to-sound-results
Retrieve multiple generated audio files for completed Sound and Music tasks using multiple run IDs.

This endpoint retrieves audio outputs generated from multiple previously completed Sound and Music tasks in a single request. It allows you to efficiently fetch results for several text-to-sound generation runs simultaneously, making it ideal for batch processing workflows and applications that need to handle multiple audio files at once.

Unlike the single result endpoint that takes a run ID as a URL parameter, this bulk endpoint accepts multiple run IDs in the request body, providing a more efficient way to retrieve results when working with multiple text-to-sound tasks.

## How It Works

The endpoint processes an array of run IDs and returns corresponding results for each completed task. This batch approach offers several advantages over making individual requests for each result:

**Efficiency Benefits:**

* Reduces the number of HTTP requests needed
* Minimizes network overhead when fetching multiple results
* Simplifies client-side code for handling multiple audio files
* Provides better performance for applications processing many audio generations

**Practical Applications:**

* Batch processing of multiple text-to-sound requests
* Building audio libraries from multiple text prompts
* Creating soundtracks or audio collections
* Processing results from parallel text-to-sound tasks

## Request Format

The endpoint expects a JSON payload containing an array of run IDs that you want to retrieve results for:

```json theme={null}
// Note: Replace with your actual Run IDs
{
  "run_ids": [
    "12345",
    "678910",
    "112233"
  ]
}
```

Each run ID should correspond to a previously initiated and completed text-to-sound task. The endpoint will process all provided run IDs and return results for those that have completed successfully.

## Response Structure

The response contains an array of results, where each item corresponds to one of the requested run IDs. Each result includes a presigned URL that points directly to the generated audio file:

```json theme={null}
[
    12345: {
      "output_url": "https://storage.example.com/audio/12345.wav"
    },
    678910: {
      "output_url": "https://storage.example.com/audio/678910.wav"
    },
    112233: {
      "output_url": "https://storage.example.com/audio/112233.wav"
    }
]

```

## Example Usage

### Basic Bulk Request

```bash theme={null}
curl -X POST "https://client.camb.ai/apis/text-to-sound-results" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_ids": [
    "12345",
    "678910",
    "112233"
  ]
  }'
```

### Processing the Response

```javascript theme={null}
// Example JavaScript code for handling the bulk response
const response = await fetch('/text-to-sound-results', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    run_ids: [
      "12345",
      "678910",
      "112233"
    ]
  })
});

const data = await response.json();

// Process each result
data.results.forEach(result => {
    console.log(`Audio ready for ${result}: ${result.output_url}`);
    // Download or process the audio file
});
```

## Workflow Integration

This bulk endpoint fits naturally into larger audio processing workflows. Consider this typical pattern:

1. **Initiate Multiple Tasks**: Submit several text-to-sound requests using the creation endpoint
2. **Store Run IDs**: Keep track of all returned run IDs from your requests
3. **Process Completed Results**: Download and handle audio files for completed tasks
4. **Retry or Handle Failures**: Manage any failed tasks or retry processing tasks

## Technical Considerations

**File Format and Quality:**
The generated audio files are delivered in WAV format, providing high audio quality suitable for professional applications. Keep in mind that WAV files are larger than compressed formats but offer the best fidelity for your generated sound effects.

**URL Expiration:**
The presigned URLs returned in the response are temporary and will expire after a certain period. Make sure to download and store important audio files promptly to avoid losing access to your generated content.

**Rate Limiting:**
While this endpoint allows bulk retrieval, be mindful of the fact that this endpoint allows providing a maximum of 5 run IDs per request. The bulk approach is more efficient than individual requests, but extremely large batches should be broken down into manageable chunks.

**Memory and Storage:**
When downloading multiple audio files, consider the memory and storage requirements on your system. Implement appropriate streaming or chunked download strategies for large batches to avoid overwhelming your application's resources.

By leveraging this bulk results endpoint, you can build more efficient applications that handle multiple text-to-sound generations seamlessly, enabling creative workflows that scale with your audio production needs.


# Fetch Transcription Results
Source: https://docs.camb.ai/api-reference/endpoint/fetch-transcriptions-runs-results

post /transcription-results
Retrieves the results of multiple transcription runs using the provided run IDs in the request body.

Access multiple transcription results simultaneously through this powerful bulk endpoint. When your transcription processes complete, this API provides comprehensive text representations of your audio or video content with precise timing information and speaker identification for each run. This bulk retrieval capability streamlines workflows for content creators managing multiple transcription projects, enabling efficient processing of large-scale media libraries.

## Efficient Bulk Processing

Managing multiple transcription projects becomes seamless with bulk retrieval functionality. Our system delivers transcriptions for multiple runs that include:

* **Parallel Processing**: Retrieve results from multiple transcription runs in a single request
* **Temporal Precision**: Exact start and end timestamps for each spoken segment across all runs
* **Speaker Differentiation**: Clear identification of different speakers throughout each piece of content
* **Verbatim Text**: Accurate textual representation of all spoken content for each run

This structured approach to bulk transcription retrieval enables content creators, researchers, and educators to efficiently work with multiple audio-visual materials simultaneously, making entire content libraries searchable, analyzable, and more accessible.

## Retrieving Multiple Transcription Results

To access your completed transcriptions in bulk, you'll need the unique `run_id` values that were assigned when you initially submitted your transcription requests. These identifiers allow our system to locate your specific transcription results within our processing infrastructure and return them as a consolidated response.

### Understanding the Request Structure

The bulk transcription endpoint requires a JSON payload containing an array of run IDs. This allows you to specify exactly which transcription results you want to retrieve:

```json theme={null}
{
  "run_ids": [12345, 12346, 12347, 12348]
}
```

### Response Structure

The API returns an array of transcription results, where each element corresponds to one of the requested run IDs. Each transcription result contains an array of dialogue items with detailed timing and speaker information:

| Field     | Description                                                      |
| :-------- | :--------------------------------------------------------------- |
| `start`   | The precise starting point of the speech segment (in seconds)    |
| `end`     | The exact ending point of the speech segment (in seconds)        |
| `text`    | The verbatim transcription of the spoken content in this segment |
| `speaker` | Identifier for the person speaking during this segment           |

Let's explore how to retrieve and work with bulk transcription data using Python:

```python [expandable] theme={null}
"""
Bulk Transcription Analysis Tool

This script helps you:
1. Fetch multiple transcription results from the CAMB.AI API
2. Analyze the transcriptions (duration, speakers, content)
3. Export transcriptions to CSV files
4. Find common speakers and words across all transcriptions

Before running:
- Replace "your-api-key" with your actual API key
- Install required packages: pip install requests
"""

import requests
import csv
from collections import Counter
import re

# ============================================================================
# CONFIGURATION - Update these values before running
# ============================================================================

# Your API authentication details
headers = {
    "x-api-key": "your-api-key",  # 🔑 REPLACE WITH YOUR ACTUAL API KEY
    "Content-Type": "application/json",
}

# The API endpoint for fetching transcription results
API_URL = "https://client.camb.ai/apis/transcription-results"

# ============================================================================
# MAIN FUNCTIONS
# ============================================================================

def get_bulk_transcriptions(run_ids):
    """
    Fetches multiple transcription results from the API in a single request.

    This function sends a list of run IDs to the API and gets back all the
    transcription data for those runs at once, which is much faster than
    making individual requests for each run.

    Parameters:
        run_ids (list): A list of numbers representing the run IDs you want to fetch
                       Example: [12345, 12346, 12347]

    Returns:
        dict: A dictionary where each key is a run ID and each value contains
              the transcription data for that run. Returns None if there's an error.

    Example response structure:
        {
            "12345": {
                "transcript": [
                    {"start": 0.0, "end": 2.5, "speaker": "Speaker_1", "text": "Hello world"},
                    {"start": 2.5, "end": 5.0, "speaker": "Speaker_2", "text": "How are you?"}
                ]
            }
        }
    """
    try:
        # Prepare the data to send to the API
        payload = {"run_ids": run_ids}

        print(f"📡 Requesting transcriptions for {len(run_ids)} runs...")

        # Make the API request
        response = requests.post(
            API_URL,
            headers=headers,
            json=payload,
        )

        # Check if the request was successful (status code 200-299)
        response.raise_for_status()

        # Convert the response from JSON to a Python dictionary
        results = response.json()

        # Show the raw response for debugging (you can comment this out later)
        print("📋 Raw API response:")
        print(results)
        print()

        print(f"✅ Successfully retrieved {len(results)} transcription results")
        return results

    except requests.exceptions.RequestException as e:
        # This handles network errors, API errors, etc.
        print(f"❌ Error retrieving bulk transcriptions: {e}")
        if hasattr(e, "response") and e.response is not None:
            print(f"🔍 Response details: {e.response.text}")
        return None

# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

def format_time(seconds):
    """
    Converts seconds to a readable HH:MM:SS format.

    Parameters:
        seconds (float): Time in seconds (e.g., 3661.5)

    Returns:
        str: Formatted time string (e.g., "01:01:01")
    """
    hours = int(seconds // 3600)      # Get whole hours
    minutes = int((seconds % 3600) // 60)  # Get remaining minutes
    secs = int(seconds % 60)          # Get remaining seconds

    # Format with leading zeros (e.g., "01:05:30" instead of "1:5:30")
    return f"{hours:02d}:{minutes:02d}:{secs:02d}"

def safe_get_transcript(transcription_data):
    """
    Safely extracts the transcript from API response data.

    The API returns nested data, so we need to safely navigate to the transcript.

    Parameters:
        transcription_data (dict): The data for one transcription run

    Returns:
        list: List of transcript segments, or empty list if not found
    """
    if not transcription_data:
        return []

    # Navigate safely: transcription_data -> "transcript" -> list of segments
    return transcription_data.get("transcript", [])

# ============================================================================
# ANALYSIS FUNCTIONS
# ============================================================================

def analyze_single_transcription(transcription, run_id):
    """
    Analyzes a single transcription and prints detailed statistics.

    This function examines one transcription result and shows:
    - How long the audio was
    - How many dialogue segments there are
    - Who the speakers are
    - Sample dialogue from the beginning

    Parameters:
        transcription (list): List of dialogue segments from the API
        run_id (str): The ID of this transcription run (for display purposes)
    """
    # Check if we have any data to analyze
    if not transcription:
        print(f"🔍 Run {run_id}: No transcription data available")
        return

    print(f"📊 Analyzing Run {run_id}:")
    print("=" * 40)

    # Calculate basic statistics
    total_duration = max(segment["end"] for segment in transcription) if transcription else 0
    total_segments = len(transcription)

    # Find all unique speakers in this transcription
    speakers = set()
    for segment in transcription:
        if "speaker" in segment:
            speakers.add(segment["speaker"])
    unique_speakers = len(speakers)

    # Count how many times each speaker appears
    speaker_counts = Counter()
    for segment in transcription:
        if "speaker" in segment:
            speaker_counts[segment["speaker"]] += 1

    # Find who spoke the most
    most_frequent_speaker = speaker_counts.most_common(1)[0][0] if speaker_counts else "Unknown"

    # Print all the statistics
    print(f"  🕐 Total duration: {format_time(total_duration)}")
    print(f"  💬 Total segments: {total_segments}")
    print(f"  👥 Unique speakers: {unique_speakers}")
    print(f"  🎤 Most frequent speaker: {most_frequent_speaker}")

    # Show the first few lines of dialogue as examples
    print("  📝 Sample dialogue:")
    for i, segment in enumerate(transcription[:2]):  # Show first 2 segments only
        start_time = format_time(segment["start"])
        end_time = format_time(segment["end"])
        speaker = segment.get("speaker", "Unknown")

        # Truncate long text to keep output readable
        text = segment.get("text", "")
        if len(text) > 50:
            text = text[:50] + "..."

        print(f"    [{start_time} → {end_time}] {speaker}: {text}")
    print()  # Add blank line for readability

def analyze_bulk_transcriptions(transcription_results):
    """
    Analyzes all transcription results and provides insights for each one.

    This is the main analysis function that processes all the transcriptions
    you fetched from the API.

    Parameters:
        transcription_results (dict): Dictionary of all transcription results from the API
    """
    if not transcription_results:
        print("❌ No transcription results to analyze")
        return

    print(f"\n🔍 Analyzing {len(transcription_results)} transcription results:")
    print("=" * 60)

    # Process each transcription one by one
    for run_id in transcription_results:
        # Safely extract the transcript data
        transcript = safe_get_transcript(transcription_results.get(run_id, {}))

        # Analyze this individual transcription
        analyze_single_transcription(transcript, run_id)

# ============================================================================
# EXPORT FUNCTIONS
# ============================================================================

def export_transcription_to_csv(transcription, filename):
    """
    Export a single transcription to a CSV file for further analysis.

    Creates a CSV file with columns: start, end, speaker, text
    This makes it easy to open in Excel or other spreadsheet programs.

    Parameters:
        transcription (list): List of dialogue segments
        filename (str): Name of the output file (e.g., "transcription_12345.csv")
    """
    if not transcription:
        print(f"⚠️  No data to export for {filename}")
        return

    try:
        # Open the file for writing
        with open(filename, "w", newline="", encoding="utf-8") as csvfile:
            # Define the column headers
            fieldnames = ["start", "end", "speaker", "text"]
            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

            # Write the header row
            writer.writeheader()

            # Write each dialogue segment as a row
            for segment in transcription:
                writer.writerow({
                    "start": segment.get("start", ""),
                    "end": segment.get("end", ""),
                    "speaker": segment.get("speaker", ""),
                    "text": segment.get("text", ""),
                })

        print(f"💾 Exported transcription to {filename}")

    except Exception as e:
        print(f"❌ Error exporting to {filename}: {e}")

# ============================================================================
# CROSS-TRANSCRIPTION ANALYSIS FUNCTIONS
# ============================================================================

def extract_speakers_from_bulk(transcription_results):
    """
    Finds all unique speakers across multiple transcription runs.

    This helps you understand who appears in your audio content overall.

    Parameters:
        transcription_results (dict): Dictionary of all transcription results

    Returns:
        list: List of all unique speaker names found across all transcriptions
    """
    all_speakers = set()  # Use a set to automatically handle duplicates

    # Go through each transcription
    for run_id in transcription_results:
        transcript = safe_get_transcript(transcription_results.get(run_id, {}))

        if transcript:
            # Extract speakers from this transcription
            for segment in transcript:
                if "speaker" in segment:
                    all_speakers.add(segment["speaker"])

    return list(all_speakers)  # Convert back to list

def find_common_words(transcription_results, min_length=5):
    """
    Identifies frequently used words across multiple transcriptions.

    This helps you understand the main topics and themes in your audio content.

    Parameters:
        transcription_results (dict): Dictionary of all transcription results
        min_length (int): Minimum word length to consider (default: 5)
                         This filters out common short words like "the", "and", etc.

    Returns:
        Counter: A Counter object with word frequencies
    """
    all_words = []

    # Go through each transcription
    for run_id in transcription_results:
        transcript = safe_get_transcript(transcription_results.get(run_id, {}))

        if transcript:
            # Extract words from each dialogue segment
            for segment in transcript:
                if "text" in segment:
                    # Convert to lowercase for consistent counting
                    text = segment["text"].lower()

                    # Extract words (letters only, no punctuation)
                    words = re.findall(r"\b\w+\b", text)

                    # Only keep words that are long enough
                    filtered_words = [word for word in words if len(word) >= min_length]
                    all_words.extend(filtered_words)

    # Count how many times each word appears
    word_counts = Counter(all_words)

    # Display the results
    print("\n📈 Most common words across all transcriptions:")
    print("-" * 45)
    for word, count in word_counts.most_common(10):  # Show top 10
        print(f"  {word}: {count} occurrences")

    return word_counts

# ============================================================================
# MAIN EXECUTION
# ============================================================================

if __name__ == "__main__":
    """
    Main execution section - this runs when you execute the script directly.

    Modify the run_ids list below with your actual run IDs.
    """

    print("🚀 Starting Bulk Transcription Analysis Tool")
    print("=" * 50)

    # ⚠️ MODIFY THIS LIST WITH YOUR ACTUAL RUN IDs
    run_ids = [12345, 12346, 12347, 12348]

    print(f"📋 Processing run IDs: {run_ids}")
    print()

    # Step 1: Fetch all transcription results from the API
    print("🔄 Step 1: Fetching transcription results...")
    bulk_results = get_bulk_transcriptions(run_ids)

    if bulk_results:
        print("✅ Successfully fetched results. Starting analysis...")

        # Step 2: Analyze all transcription results
        print("\n🔄 Step 2: Analyzing transcriptions...")
        analyze_bulk_transcriptions(bulk_results)

        # Step 3: Export each transcription to a separate CSV file
        print("\n🔄 Step 3: Exporting transcriptions to CSV files...")
        for run_id in bulk_results:
            transcript = safe_get_transcript(bulk_results.get(run_id, {}))
            if transcript:
                filename = f"transcription_run_{run_id}.csv"
                export_transcription_to_csv(transcript, filename)

        # Step 4: Find all speakers across all transcriptions
        print("\n🔄 Step 4: Finding all speakers...")
        all_speakers = extract_speakers_from_bulk(bulk_results)
        print(f"👥 All speakers across {len(bulk_results)} runs: {all_speakers}")

        # Step 5: Analyze common vocabulary
        print("\n🔄 Step 5: Analyzing common vocabulary...")
        find_common_words(bulk_results)

        print("\n🎉 Analysis complete! Check the CSV files for detailed transcription data.")

    else:
        print("❌ Failed to fetch transcription results. Please check your API key and run IDs.")
```

## Bulk Processing Benefits

The bulk transcription endpoint provides several advantages for managing multiple transcription projects:

### Workflow Efficiency

* **Single Request**: Retrieve multiple transcription results without making separate API calls
* **Reduced Latency**: Minimize network overhead by consolidating requests
* **Batch Processing**: Perfect for processing entire content libraries or project collections

### Content Management

* **Comparative Analysis**: Easily compare transcriptions across multiple runs
* **Consolidated Reporting**: Generate unified reports from multiple transcription sources
* **Quality Assurance**: Streamline review processes for large-scale transcription projects

### Integration Capabilities

* **Database Population**: Efficiently populate content databases with transcription data
* **Search Indexing**: Build comprehensive search indexes across multiple content pieces
* **Analytics Processing**: Perform cross-content analysis and pattern recognition

## Best Practices for Bulk Processing

To maximize the effectiveness of bulk transcription retrieval:

### Request Optimization

* **Batch Size**: Request reasonable batch sizes (typically 3-5 runs per request)
* **Run Grouping**: Group related runs together for more efficient processing
* **Retry Logic**: Implement retry mechanisms for handling temporary failures

### Data Management

* **Result Caching**: Cache frequently accessed transcription results
* **Incremental Processing**: Process new runs while maintaining existing data
* **Storage Strategy**: Implement efficient storage solutions for large transcription datasets

### Performance Considerations

* **Parallel Processing**: Use the bulk endpoint instead of multiple individual requests
* **Memory Management**: Process large result sets in chunks to manage memory usage
* **Rate Limiting**: Respect API rate limits when making frequent bulk requests


# Fetch Translation Results in Bulk
Source: https://docs.camb.ai/api-reference/endpoint/fetch-translation-runs-results

post /translation-results
Retrieves the final translated texts from multiple completed translation tasks using a list of `run_id` values in a single request.

This endpoint delivers the final products of multiple translation processes simultaneously: all your translated texts in one efficient request. Once your translation tasks have completed successfully and you've received multiple `run_id` values, this endpoint allows you to retrieve all the actual translations that were generated. Think of it as the express pickup counter where you collect several finished translation orders at once, rather than making individual trips for each one.

## How to Use This Endpoint

To retrieve multiple sets of translated texts, send a `POST` request to this endpoint with an array of `run_id` values in the request body. Each `run_id` serves as your claim ticket for a finished translation task. You must provide between 2 and 5 `run_id` values per request. The system will respond with a structured object containing all your translated texts, organized by their corresponding `run_id` values.

## Request Format

The request body should contain an array of `run_id` values for the completed translation tasks you want to retrieve. You must provide between 2 and 5 `run_id` values per request:

```json theme={null}
{
  "run_ids": [12345, 12346, 12347, 12348]
}
```

<Note>The `run_ids` array must contain between 2 and 5 values. Requests with fewer than 3 or more than 5 run\_ids will be rejected with a validation error.</Note>

## Understanding the Response

When you call this endpoint, you'll receive a response that includes all your translated content organized by `run_id`:

* **`results`**: An object where each key is a `run_id` and each value contains the translation data for that specific task
* **`texts`**: Within each result, an array of strings containing the translated output texts, maintaining the same order as the original input for that task

The structure of the response follows this format:

```json [expandable] theme={null}
{
    "12345": {
      "texts": [
        "Your first translated text from task 12345",
        "Your second translated text from task 12345"
      ]
    },
    "12346": {
      "texts": [
        "Your first translated text from task 12346",
        "Your second translated text from task 12346",
        "Your third translated text from task 12346"
      ]
    },
    "12347": {
      "texts": [
        "Single translated text from task 12347"
      ]
    },
    "12348": {
      "texts": [
        "First text from task 12348",
        "Second text from task 12348",
        "Third text from task 12348",
        "Fourth text from task 12348"
      ]
    }
}
```

This structured response format makes it simple to process multiple translation tasks while maintaining clear organization. You can easily access translations for any specific task or iterate through all results systematically.

## Working with Bulk Translation Results

There are several effective patterns for handling bulk translation results:

### Direct Processing

For immediate use, you can extract and process all translation results:

```python [expandable] theme={null}
# Welcome to the translation results retriever! 🌍✨
# This script will help you get translation results for multiple tasks from the Camb AI API.
# Make sure you have the requests library installed. If not, run: pip install requests 📦

import requests

# Set up the headers for the API request. This includes your API key and the content type. 🔑
# TODO: Replace 'your-api-key' with your actual API key from Camb AI.
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json",
}

# List of run_ids for the completed translation tasks you want to retrieve. 📋
# TODO: Replace these with your actual run_ids. Must be between 2 and 5 run_ids.
run_ids = [12345, 12346, 12347, 12348]  # Example run_ids


def get_bulk_translation_results(run_ids):
    """
    Retrieves translations for multiple completed tasks in a single request. 🚀

    Args:
        run_ids: List of run_id values for completed translation tasks (must be 3-5 items)

    Returns:
        dict: Dictionary mapping run_ids to their translation results
    """
    # Check if the number of run_ids is between 2 and 5. If not, print an error message and return an empty dictionary. ⚠️
    if len(run_ids) < 2 or len(run_ids) > 5:
        print(
            f"❌ Error: Must provide between 2 and 5 run_ids. You provided {len(run_ids)}."
        )
        return {}

    print(f"🌟 Retrieving translations for {len(run_ids)} completed tasks...")

    # Prepare the payload for the API request. This includes the list of run_ids. 📦
    payload = {"run_ids": run_ids}

    try:
        # Define the API endpoint URL. 🌐
        API_URL = "https://client.camb.ai/apis/translation-results"

        # Make the POST request to the API endpoint to retrieve the translation results. 🚀
        response = requests.post(API_URL, headers=headers, json=payload)

        # Check if the request was successful. If not, an exception will be raised. ✅
        response.raise_for_status()

        # Parse the JSON response to get the translation results. 📄
        results = response.json()

        print(f"🎉 Successfully retrieved translations for {len(results)} tasks!")
        return results

    except requests.exceptions.RequestException as e:
        print(f"😢 Oops! There was an error retrieving the translation results: {e}")
        return {}


# Now, let's retrieve the translation results for the provided run_ids. 🌟
translation_results = get_bulk_translation_results(run_ids)

# Check if any results were retrieved. If not, print a message. 🤔
if not translation_results:
    print(
        "😞 No translation results were retrieved. Please check your run_ids and API key."
    )
else:
    # Process the retrieved translation results and print them. 🖨️
    for run_id in translation_results:
        translations = translation_results.get(run_id, {}).get("texts", [])
        print(f"\n🎉 Run ID {run_id} has {len(translations)} translations:")
        for i, translation in enumerate(translations):
            print(f"  {i+1}. {translation} 🌍")

# What's next? You could save these results to a file or use them in your next project! 🚀

```

## Best Practices

### Request Size Requirements

This endpoint requires a specific batch size for optimal performance and resource management:

* **Minimum**: You must provide at least 2 `run_id` values per request
* **Maximum**: You can provide up to 5 `run_id` values per request
* **Validation**: Requests outside this range will be rejected with a validation error

### Handling Larger Datasets

If you have more than 5 completed translation tasks to retrieve:

* **Split into Multiple Requests**: Divide your `run_id` list into chunks of 3-5 items
* **Sequential Processing**: Process chunks sequentially to avoid rate limiting
* **Batch Management**: Implement logic to group your run\_ids efficiently

```python [expandable] theme={null}
# Example: Processing larger datasets
all_run_ids = [12345, 12346, 12347, 12348, 12349, 12350, 12351, 12352]

# Split into chunks of 3-5 run_ids
def chunk_run_ids(run_ids, chunk_size=5):
    """Split run_ids into chunks of specified size (3-5)."""
    chunks = []
    for i in range(0, len(run_ids), chunk_size):
        chunk = run_ids[i:i + chunk_size]
        if len(chunk) >= 2:  # Ensure minimum chunk size
            chunks.append(chunk)
        elif chunks:  # Add remaining items to last chunk if possible
            chunks[-1].extend(chunk)
    return chunks

# Process in batches
chunks = chunk_run_ids(all_run_ids)
all_results = {}

for i, chunk in enumerate(chunks):
    print(f"Processing batch {i+1}/{len(chunks)}: {len(chunk)} run_ids")
    batch_results, failed_ids = get_bulk_translation_results_with_error_handling(chunk)
    all_results.update(batch_results)
```

### Error Recovery

Always implement proper error handling when working with bulk operations:

* Check response status codes before processing results
* Handle partial failures gracefully (some run\_ids may succeed while others fail)
* Implement retry logic for transient failures
* Log failed run\_ids for later processing

## Next Steps

Once you've retrieved your bulk translation results, you can:

1. **Display them** to your users in organized, task-specific groups
2. **Store them** systematically with proper task organization
3. **Process them further** with additional NLP tools while maintaining task relationships
4. **Use them in your application logic** to enable comprehensive multilingual functionality

The structured response format makes it easy to integrate multiple translation results wherever they're needed in your workflow, whether you're building a multilingual content management system, an educational platform with batch translation capabilities, or an international communication tool that processes multiple conversation threads.

By understanding how to effectively use this bulk endpoint, you can create highly efficient multilingual applications that deliver multiple sets of high-quality translations to your users in a single, streamlined operation.


# Fetch Bulk Text-to-Speech Results
Source: https://docs.camb.ai/api-reference/endpoint/fetch-tts-runs-results

post /tts-results
Retrieves the results of multiple Text-to-Speech runs using a list of `run_id` values in a single request.

<Card icon="lightbulb" href="create-tts-stream">
  Bulk retrieval only helps when you already have run IDs from the deprecated async `POST /tts` workflow. For anything new, stream each piece of speech with `POST /tts-stream` (split longer copy into segments if needed) instead of batching legacy runs.
</Card>

This endpoint streamlines the process of retrieving multiple completed audio files at once, perfect for applications that process batches of text-to-speech tasks. Instead of making individual requests for each `run_id`, you can efficiently gather all your generated audio files in a single API call.

## How to Use this Endpoint

Retrieving multiple generated audio files is straightforward - make a `POST` request to this endpoint with an array of `run_id` values in the request body. The system will process all your completed tasks and return URLs for each audio file, making it easy to download or reference them in your application.

## Understanding the Response

This endpoint returns a JSON response containing file URLs for each successfully processed run\_id. Each audio file URL in the response corresponds to a completed text-to-speech task, allowing you to efficiently handle multiple audio files without the overhead of individual requests.

The bulk response structure provides:

* **Organized Results:** Each `run_id` is mapped to its corresponding audio file URL.
* **Error Handling:** Clear indication of any failed or unavailable runs.
* **Efficient Processing:** Single request handles multiple audio files.

<Tip>This bulk endpoint is particularly useful for applications that generate multiple audio segments simultaneously, such as creating audiobook chapters, processing multiple language versions, or handling batch content generation.</Tip>

## Request Format

The request body should contain an array of `run_id` values for the completed text-to-speech tasks you want to retrieve:

```json theme={null}
{
  "run_ids": [12345, 12346, 12347, 12348]
}
```

### Response Structure

The response will be a JSON object containing URLs for each successfully processed audio file:

```json theme={null}
{
    "12345": "https://audio-storage.camb.ai/files/audio_12345.flac",
    "12346": "https://audio-storage.camb.ai/files/audio_12346.flac",
    "12347": "https://audio-storage.camb.ai/files/audio_12347.flac",
    "12348": "https://audio-storage.camb.ai/files/audio_12348.flac"
}
```

<Note>File URLs have an expiration time, so download or use them promptly rather than storing them long-term. Plan to process your audio files within a reasonable timeframe after retrieval.</Note>

## Examples

### Retrieving Multiple Audio Files

Here's how to retrieve multiple generated audio files using Python:

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

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

# List of run_ids from your completed TTS tasks (must be between 2-5 run_ids)
run_ids = [12345, 12346, 12347, 12348]  # Replace with your actual run_ids


def get_bulk_audio_results(run_ids):
    """
    Retrieves URLs for multiple completed TTS tasks in a single request.

    Args:
        run_ids: List of run_id values for completed TTS tasks (must be 2-5 items)

    Returns:
        dict: Dictionary mapping run_ids to their audio file URLs
    """
    # Validate the number of run_ids
    if len(run_ids) < 2 or len(run_ids) > 5:
        print(
            f"Error: Must provide between 2 and 5 run_ids. You provided {len(run_ids)}."
        )
        return {}

    print(f"Retrieving audio URLs for {len(run_ids)} completed tasks...")

    # Prepare the request payload
    payload = {"run_ids": run_ids}

    try:
        # Make the POST request
        response = requests.post(
            "https://client.camb.ai/apis/tts-results",
            headers=headers,
            json=payload,
        )

        # Check if the request was successful
        response.raise_for_status()

        # Parse the response
        results = response.json()

        print(f"Successfully retrieved {len(results)} audio file URLs!")
        return results

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving bulk audio results: {e}")
        return {}


# Retrieve all audio URLs
audio_urls = get_bulk_audio_results(run_ids)

# Process the results
for run_id, output_json in audio_urls.items():
    print(f"Run ID {run_id}: {output_json.get('output_url')}")
```

## Best Practices

### Request Size Requirements

This endpoint requires a specific batch size for optimal performance and resource management:

* **Minimum**: You must provide at least 2 `run_id` values per request
* **Maximum**: You can provide up to 5 `run_id` values per request
* **Validation**: Requests outside this range will be rejected with a validation error

### Handling Larger Datasets

If you have more than 5 completed TTS tasks to retrieve:

* **Split into Multiple Requests**: Divide your `run_id` list into chunks of 2-5 items
* **Sequential Processing**: Process chunks sequentially to avoid rate limiting
* **Batch Management**: Implement logic to group your run\_ids efficiently

## Next Steps

With your bulk audio retrieval capabilities in place, you can:

1. **Build Efficient Workflows**: Process multiple audio files simultaneously in your applications
2. **Create Batch Processing Systems**: Handle large-scale content generation with minimal API overhead
3. **Implement Robust Error Handling**: Ensure your application gracefully handles partial failures
4. **Optimize Resource Usage**: Reduce API calls and improve application performance

This bulk endpoint provides the foundation for scalable voice applications that can handle multiple audio files efficiently and reliably.


# Get Audio Separation Result
Source: https://docs.camb.ai/api-reference/endpoint/get-audio-separation-run-info

get /audio-separation-result/{run_id}
Retrieves detail information about a specific audio separation run using the provided `run_id`.

# Accessing Your Separated Audio Components

Once your audio separation task completes successfully, this endpoint provides immediate access to the isolated audio components. The system divides your original audio into two distinct tracks: a **foreground** track containing primary audio elements (typically speech, vocals or main instruments) and a **background** track with remaining audio elements. These isolated components enable creative flexibility for remixing, enhancing specific audio elements, or removing unwanted sounds from your original recording.

## Understanding Audio Separation Results

* **Foreground Audio**: Contains dominant audio elements, typically vocals, speech, or lead instruments that represent the primary focus of the recording
* **Background Audio**: Contains ambient sounds, musical accompaniment, or secondary audio elements that provide context or support to the foreground elements

Audio separation technology analyzes the spectral and temporal characteristics of your audio file to identify and isolate different sound components. The separation process creates two complementary audio files that, when combined, reconstruct your original recording:

* **Foreground Audio**: Contains dominant audio elements, typically vocals, speech, or lead instruments that represent the primary focus of the recording
* **Background Audio**: Contains ambient sounds, musical accompaniment, or secondary audio elements that provide context or support to the foreground elements

This dual-track approach gives you unprecedented control over your audio content for professional editing, creative remixing, or accessibility enhancements.

## Retrieving Separated Audio Files

After your separation task completes, you'll receive a `run_id` that serves as your access key to the processed audio files. Simply make a GET request to this endpoint using that identifier to retrieve download URLs for both audio components.

### Response Structure

A successful response returns direct download URLs for both the foreground and background audio files:

```json theme={null}
{
  "foreground_audio_url": "<URL_TO_THE_DETECTED_FOREGROUND_AUDIO>",
  "background_audio_url": "<URL_TO_THE_DETECTED_BACKGROUND_AUDIO>"
}
```

Each URL points to a standard audio file that can be downloaded directly or streamed into your application.


# Get Audio Separation Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-audio-separation-status

get /audio-separation/{task_id}
Retrieves the current status of an audio separation task using the specified `task_id`.

When you submit an audio file for separation into its component tracks, our system begins processing your request as a background task. This endpoint serves as your window into that process, allowing you to monitor the progression of your audio separation task from initiation to completion.

## Making Status Requests

To check on your audio separation task's progress, you'll need the unique `task_id` that was provided when you initially submitted your separation request. With this identifier, simply make a GET request to the endpoint:

```
GET https://client.camb.ai/apis/audio-separation/{task_id}
```

## Troubleshooting Common Issues

If you encounter difficulties while checking separation status, consider these common solutions:

1. **Invalid Task ID**: Verify the task ID was correctly stored and passed to the status endpoint. Task IDs are case-sensitive and must be used exactly as provided.

2. **Authentication Problems**: Ensure your API key is valid and correctly included in the request headers.

3. **Network Connectivity**: Implement proper error handling for network issues that might interrupt status checking, including automatic retry logic.

4. **Unexpected Terminal States**: If a separation ends with an error status, examine the error message for specific issues that might be addressed in subsequent separation attempts.

By properly integrating status checking into your application, you can create a seamless separation experience that keeps your users informed throughout the entire process, building confidence in your service and ensuring timely delivery.


# Get Dictionary Full Details
Source: https://docs.camb.ai/api-reference/endpoint/get-dictionary-full-details

get /dictionaries/{dictionary_id}/full-details
Retrieves comprehensive details for a specific dictionary, including all terms and their definitions. Supports optional filtering and pagination to help you find exactly what you need.

## Overview

This endpoint provides you with complete access to a dictionary's content, returning detailed information about the dictionary itself along with all its terms and definitions. Think of this as opening up a physical dictionary and having access to browse through all its entries, but with the added convenience of being able to search for specific terms or limit how many results you see at once.

## Understanding Dictionary Details

When you request full details for a dictionary, you're essentially asking the system to compile a comprehensive view that includes both the dictionary's metadata (information about the dictionary itself) and its complete content. This content consists of all the dictionary's terms along with their corresponding translations or definitions. Think of it as getting both the book's cover information and all the pages inside, delivered together in one complete package.

This comprehensive approach is particularly valuable when you're building multilingual applications, translation tools, or terminology management systems where you need access to both the source terms and their translated equivalents. The full details endpoint delivers this rich content in a structured format that makes it easy to work with term-translation pairs programmatically.

The "full details" approach means you get everything in one request rather than having to make separate calls for dictionary information and then additional calls for each term and its translations. This design helps reduce the number of API calls your application needs to make, which improves performance and simplifies your code while giving you complete access to the dictionary's linguistic content.


# Get Dictionary Summary
Source: https://docs.camb.ai/api-reference/endpoint/get-dictionary-summary

get /dictionaries/{dictionary_id}
Retrieves essential information about a specific dictionary, including its name, description, and metadata. Perfect for getting a quick overview without loading all dictionary terms.

## Overview

Think of this endpoint as looking at the cover and introduction of a book before deciding whether to read the entire thing. When you need to understand what a dictionary contains and when it was created or last modified, but don't need to see all its terms and definitions, this endpoint provides exactly that focused information.
This summary approach serves a fundamentally different purpose than retrieving full dictionary details. While the full details endpoint gives you everything including all terms and definitions, this summary endpoint focuses exclusively on the dictionary's identifying characteristics and metadata. This distinction becomes important when you're building applications that need to display dictionary information efficiently or when you're working with multiple dictionaries and need to present them in lists or selection interfaces.

## Understanding Dictionary Metadata

Every dictionary in the system carries essential information about itself, separate from the actual terms and definitions it contains. This metadata tells the story of the dictionary: what it's called, what it's intended for, when it was created, and when someone last made changes to it. Understanding this information helps you and your users make informed decisions about which dictionaries to work with and whether the content might be current for your needs.
The metadata approach also supports better application architecture. Instead of loading potentially thousands of dictionary terms just to show a user what dictionaries are available, you can quickly retrieve just the summary information for multiple dictionaries, creating responsive user interfaces that load quickly and provide clear choices.


# Get Dubbed Output in Alt Format
Source: https://docs.camb.ai/api-reference/endpoint/get-dub-alt-format

post /dub-alt-format/{run_id}/{language}
Fetches the dubbed output for a specified `run_id` and `language` in the file format that is provided in the request body.

Convert your already-dubbed content into alternative file formats with our specialized endpoint. This powerful feature extends the capabilities of our core dubbing service by allowing you to repurpose completed dubbing projects into different media formats. Whether you need audio-only extracts, format conversions for specific platforms, this endpoint provides the flexibility to meet diverse content delivery requirements.

## Understanding Alternative Format Exports

The alt format endpoint works with content that has already been processed through our [`/dub`](end-to-end-dubbing) service:

<Steps>
  <Step title="Identify Your Content">
    Use the `run_id` from a completed dubbing task and specify which `language` version you want to convert.
  </Step>

  <Step title="Format Selection">
    Specify your desired output format and configuration options in the request body.
  </Step>

  <Step title="Processing">
    Our system will extract and convert the requested dubbed content into the specified format.
  </Step>

  <Step title="Delivery">
    Receive a download URL for your newly converted content, or a task ID to track processing status.
  </Step>
</Steps>

This endpoint complements the main dubbing workflow, giving you additional flexibility in how you deliver your multilingual content across different platforms and use cases.


# Get Dubbed Output in Alt Format Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-dub-alt-format-task-status

get /dub-alt-format/{task_id}
Retrieves the current status of a task exporting dubbed media to alternative file formats using the specified `task_id`.

Monitor the progress of your format conversion tasks with our dedicated status tracking endpoint. This essential companion to our format conversion service lets you check on your media transformation in real-time, providing status information about your content conversion process. By polling this endpoint, you can keep track of your format conversion progress and detect any issues that might arise during processing.

This endpoint works in conjunction with the format conversion functionality of our dubbing service, which provides the `task_id` needed for status checks when requesting alternative output formats.

## Understanding Status Values

The endpoint returns one of these status values:

* **`SUCCESS`**: The format conversion task has completed successfully
* **`PENDING`**: The format conversion task is still in progress
* **`TIMEOUT`**: The format conversion task has timed out
* **`ERROR`**: The format conversion task encountered an error
* **`PAYMENT_REQUIRED`**: Additional payment is needed to complete the task

## Implementing Status Checking

Here's how to implement status checking in your application using Python:

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

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

def check_format_conversion_status(task_id):
    """
    Polls the status endpoint to track a format conversion task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None
        
    # Define terminal states based on the API specification
    terminal_states = ["SUCCESS", "TIMEOUT", "ERROR", "PAYMENT_REQUIRED"]
    current_status = None
    
    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/dub-alt-format/{task_id}",
                headers=headers
            )
            
            # Verify the request was successful
            response.raise_for_status()
            
            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")
            
            # Display current status information
            print(f"Status: {current_status}")
            
            # Handle success state
            if current_status == "SUCCESS":
                print("Format conversion task completed successfully!")
                print(f"Result URL: {status_data.get('result_url')}")
                return status_data
                
            # Handle error states
            if current_status == "ERROR":
                print(f"Format conversion task failed: {status_data.get('error_message')}")
                return status_data
                
            # Handle timeout state
            if current_status == "TIMEOUT":
                print("Format conversion task timed out")
                return status_data
                
            # Handle payment required state
            if current_status == "PAYMENT_REQUIRED":
                print("Additional payment is required to complete this task")
                return status_data
                
            # If still pending, wait before next check
            if current_status == "PENDING":
                print("Task is still in progress")
                # Wait before next check to avoid excessive requests
                time.sleep(10)  # Poll every 10 seconds
            
        except requests.exceptions.RequestException as e:
            print(f"Error checking format conversion status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")
            return None
            
    return None

# Example usage with a task_id from a previous format conversion request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_format_conversion_status(task_id)
```

## Best Practices for Status Monitoring

To efficiently track your format conversion tasks, consider these professional recommendations:

1. **Implement Exponential Backoff**: Start with frequent checks that gradually increase in interval to avoid overloading the API. For example, begin with a 5-second interval, then double it each time until you reach a maximum of 2 minutes between checks.

2. **Handle All Status Codes**: Ensure your implementation has specific handling for each possible status value (`SUCCESS`, `PENDING`, `TIMEOUT`, `ERROR`, and `PAYMENT_REQUIRED`).

3. **Graceful Error Recovery**: If the format conversion fails, implement logic to retry the operation or provide clear feedback to users about the next steps they should take.

4. **User Interface Integration**: Present status updates in a user-friendly way, such as progress indicators or status messages that translate the technical status codes into more accessible language.

5. **Event Logging**: Maintain a detailed log of all status changes to help with troubleshooting if issues arise during the conversion process.

By properly integrating status checking into your application, you can create a seamless media conversion experience that keeps your users informed throughout the entire process and handles both successful and unsuccessful outcomes appropriately.


# Get Dubbing Transcript
Source: https://docs.camb.ai/api-reference/endpoint/get-dub-transcript

get /transcript/{run_id}/{language}
Retrieves the transcript in the specified language of a specific end to end dubbing run using the provided `run_id`.

This endpoint serves as a bridge between your media content and its written representation. When you've completed a dubbing run using Camb.ai's powerful dubbing technology, it gives you access to all that valuable spoken content in text form, unlocking new possibilities for how you can use and share your content.

<Info>
  The `{language}` path parameter is your language selector. It determines which linguistic version of your transcript you'll receive - you can choose either the original source language or any of the target languages you've dubbed your content into.
</Info>

## Understanding Response Options

The transcript endpoint gives you two distinct ways to receive your transcript data, each designed for different implementation scenarios:

* **Direct content delivery** (`data_type=raw_data`): The transcript text comes straight to you as `{ "transcript": "<raw text>" }` in the JSON response body. This immediate delivery is perfect for when you need to process or display the text right away in your application.
* **File-based delivery** (`data_type=file`): You receive `{ "transcript": "<presigned url>" }` linking to a ready-to-download transcript file. This approach works wonderfully when you need to store, share, or download the transcript as a distinct file.

In both cases the value lives under the `transcript` key — read it with `response.json()["transcript"]`. Your choice between these options depends on your workflow and how you intend to use the transcript data in your application.

## Choosing the Right Format for Your Needs

Transcripts come in three carefully designed formats, each optimized for different applications:

| Format          | Description                                         | Ideal Applications                                                                      |
| :-------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `txt` (default) | Clean, simple plain text without timing information | Content analysis, text extraction, SEO optimization, and general reading                |
| `srt`           | SubRip Subtitle format with precise timestamps      | Professional video editing software, most desktop video players, and subtitle embedding |
| `vtt`           | WebVTT format optimized for web environments        | HTML5 video players, web applications, and accessibility compliance on websites         |

The format you choose should align with how you plan to use the transcript. For example, if you're adding subtitles to a web video player, WebVTT (`vtt`) would be your best choice because of its native support in HTML5 environments. If you're editing in professional software like Adobe Premiere, the `srt` format would integrate more seamlessly with your workflow.

## Implementation Example: Bringing It All Together

Let's walk through a complete example of how you might implement transcript retrieval in your application. This Python code sample demonstrates the process from request to application:

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

# Your authentication and identification details
API_KEY = "your_api_key_here"
RUN_ID = 12345  
LANGUAGE = 1  # Language ID (e.g., `1` for English-United States)

# Set up your request parameters
url = f"https://client.camb.ai/apis/transcript/{RUN_ID}/{LANGUAGE}"
headers = {"x-api-key": API_KEY}
params = {
    "format_type": "vtt",  # Choosing WebVTT for web video integration
    "data_type": "file"    # Getting a downloadable file
}

# Make the request to the Camb.ai API
response = requests.get(url, headers=headers, params=params)

# Process the response based on its status
if response.status_code == 200:
    if params["data_type"] == "file":
        # Extract the file URL from the response
        file_url = response.json()["transcript"]
        print(f"Success! Transcript file available at: {file_url}")
        
        # Download the transcript file to your local environment
        transcript_response = requests.get(file_url)
        
        # Save the file with appropriate naming
        filename = f"transcript_{RUN_ID}_{LANGUAGE}.{params['format_type']}"
        with open(filename, "wb") as f:
            f.write(transcript_response.content)
            
        print(f"Transcript downloaded and saved as {filename}")
    else:
        # For direct content, the transcript text is under the "transcript" key
        transcript = response.json()["transcript"]
        print("Transcript content retrieved successfully:")

        # Here you might process the text further, such as:
        # - Storing in a database
        # - Analyzing for keywords
        # - Displaying in your application interface

        # For this example, we'll just show the first 150 characters
        preview = transcript[:150] + "..." if len(transcript) > 150 else transcript
        print(f"Preview: {preview}")
else:
    # Handle any errors that might occur
    print(f"Error {response.status_code}: Could not retrieve transcript")
    print(f"Details: {response.text}")
```

This code not only retrieves your transcript but also demonstrates proper error handling and different processing paths based on your chosen response type. Notice how we create a meaningful filename that includes both the run ID and language - this kind of attention to detail helps keep your transcripts organized when working with multiple videos or languages.

## Building a Complete Workflow

The transcript endpoint works best as part of a complete content processing workflow. Consider how it connects with these related endpoints:

* [Create Dubbing Run](end-to-end-dubbing) - Start the process by submitting your video for dubbing
* [Check Dubbing Status](get-end-to-end-dubbing-status) - Monitor progress and determine when your transcript will be available
* [Get Dubbed Media](get-dubbed-run-info) - Retrieve the dubbed media that corresponds to your transcript

By combining these endpoints, you can create powerful automation workflows that transform, translate, and repurpose your content with minimal manual intervention.


# Get Dubbing Result
Source: https://docs.camb.ai/api-reference/endpoint/get-dubbed-run-info

get /dub-result/{run_id}
Retrieves the result of a specific end to end dubbing run using the provided `run_id`.

Retrieve the completed results of your dubbing process with this endpoint. Once your dubbing task has finished processing, this API call provides access to the final dubbed media files along with a detailed transcript of the content. This allows you to seamlessly integrate the dubbed content into your applications, content management systems, or distribution platforms without requiring additional processing.

## Understanding Dubbing Results

When you request the results of a completed dubbing task, our system returns a comprehensive package including:

* **Dubbed Video**: A complete video file with the original visuals and newly generated voiceover in your target language.
* **Dubbed Audio**:  An isolated audio track containing only the synthesized speech in your target language.
* **Complete Transcript**: A detailed, time-coded transcript of the dubbed content with speaker identification.

This multi-format approach gives you flexibility in how you utilize and distribute your newly localized content across various platforms and use cases.

## Accessing You Dubbed content

To retrieve your dubbing results, you'll need the `run_id` that was provided when during the polling of your dubbing task. This identifier uniquely tracks your specific dubbing task through our processing pipeline.

### Example Request with Python

Here's how to fetch your completed dubbing results 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"
}

def get_dubbing_result(run_id):
    """
    Retrieves the complete results of a finished dubbing task.
    Returns URLs to the final media files and a detailed transcript.
    """
    try:
        response = requests.get(
            f"https://client.camb.ai/apis/dub-result/{run_id}",
            headers=headers
        )

        # Verify the request was successful
        response.raise_for_status()

        # Extract the dubbing results
        result_data = response.json()

        print(f"Successfully retrieved dubbing results for Run ID: {run_id}")
        print(f"Video URL: {result_data['output_video_url']}")
        print(f"Audio URL: {result_data['output_audio_url']}")
        print(f"Transcript contains {len(result_data['transcript'])} dialogue entries")

        return result_data

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

run_id = 12345 # Replace with your actual `run_id` from the dubbing request
dubbing_results = get_dubbing_result(run_id)

# Process the transcript if results were successfully retrieved
if dubbing_results and 'transcript' in dubbing_results:
    print("\nTranscript Preview:")
    for i, dialogue in enumerate(dubbing_results['transcript'][:3]):  # Show first 3 entries
        print(f"Speaker {dialogue['speaker']}: {dialogue['text']} [{dialogue['start']} - {dialogue['end']}]")

    if len(dubbing_results['transcript']) > 3:
        print("... and more dialogue entries")
```


# Get End to End Dubbing Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-end-to-end-dubbing-status

get /dub/{task_id}
Retrieves the current status of a Dubbing task using the specified `task_id`.

Monitor the progress of your dubbing tasks with our status tracking endpoint. This essential companion to our dubbing service lets you check on your media transformation in real-time, providing detailed information about which stage of the process your content has reached. By polling this endpoint, you can keep track of your dubbing tasks progress and detect any issues that might arise during processing.

This endpoint works in conjunction with the main [`/dub`](end-to-end-dubbing) endpoint, which initiates the dubbing process and provides the `task_id` needed for status checks.

## Implementing Status Checking

Here's how to implement status checking in your application using Python:

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

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

def check_dubbing_status(task_id):
    """
    Polls the status endpoint to track a dubbing task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    terminal_states = ["SUCCESS", "ERROR"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/dub/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")
            if current_status == "PENDING":
                time.sleep(15)
                continue

            # Handle completed state
            if current_status == "SUCCESS":
                print("Dubbing task completed successfully!")
                return status_data

            # Handle failed state
            if current_status == "ERROR":
                print(f"Dubbing task failed: {status_data.get('message')}")
                return status_data

            # Wait before next check to avoid excessive requests
            time.sleep(30)  # Poll every 30 seconds

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

    return None

# Example usage with a task_id from a previous dubbing request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_dubbing_status(task_id)
```

## Best Practices for Status Monitoring

To efficiently track your dubbing tasks, consider these professional recommendations:

1. **Implement Exponential Backoff**: Start with frequent checks that gradually increase in interval to avoid overloading the API.
2. **Handle Terminal States**: Always implement proper handling for both successful completion and failure cases.

By properly integrating status checking into your application, you can create a seamless dubbing experience that keeps your users informed throughout the entire process.


# Get Project Setup Result
Source: https://docs.camb.ai/api-reference/endpoint/get-project-setup-run-result

get /project-setup-result/{run_id}
Retrieves the comprehensive results of a completed project setup process, providing detailed information about your prepared project and its readiness for editing in CAMB.AI Studio.

Access the complete details of your finished project setup with this essential endpoint. Once your project setup task has completed its preparation process, this API call delivers comprehensive information about your newly configured project, including all the analysis results, configuration details, and metadata that make your content ready for creative editing in CAMB.AI Studio. Think of this as receiving your project's complete preparation report, telling you everything the system discovered and configured during the setup process.

## Understanding Project Setup Results

When you request the results of a completed project setup task, the system returns a comprehensive package that serves multiple important purposes in your content workflow. The response contains detailed information about your project's current state, the analysis results that informed the setup process, and the configuration parameters that will guide editing work in CAMB.AI Studio.

The run details section provides the foundational information that helps teams coordinate their work effectively. This includes the descriptive information you provided during setup, such as the project name and description that help identify and contextualize the work. You'll also find timing information that tracks when the project was created, which proves valuable for project management and workflow coordination. The language configuration details confirm exactly which source and target languages were configured, ensuring that everyone understands the scope of the localization work ahead.

## Accessing Your Project Setup Results

To retrieve your project setup results, you'll need the `run_id` that becomes available once your project setup task has completed successfully. This identifier serves as your unique key to access all the detailed information about your prepared project. Think of the `run_id` as your project's passport, providing access to everything the system learned and configured during the preparation process.

### Example Request with Python

Here's how to retrieve your completed project setup results using Python, with detailed explanations of what each part of the process accomplishes:

```python [expandable] theme={null}
import requests
import json
from datetime import datetime

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


def get_project_setup_result(run_id):
    """
    Retrieves the comprehensive results of a finished project setup task.
    This function accesses all the detailed information about your prepared project,
    including analysis results and configuration details that inform Studio editing.

    The returned data provides everything your creative team needs to understand
    the project structure and begin effective editing work.
    """
    try:
        # Make the API request to retrieve setup results
        response = requests.get(
            f"https://client.camb.ai/apis/project-setup-result/{run_id}",
            headers=headers,
        )

        # Verify that the request completed successfully
        response.raise_for_status()

        # Parse the comprehensive project setup results
        result_data = response.json()

        # Extract key project information for workflow coordination
        run_details = result_data.get("run_details")

        return run_details

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving project setup results: {e}")
        if hasattr(e, "response") and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None


# Replace with your actual run_id from the completed setup task
run_id = 12345
project_results = get_project_setup_result(run_id)

# Process and display detailed project information if results were retrieved successfully
if project_results:
    project_name = project_results.get("project_name", "Unnamed Project")
    description = project_results.get("project_description")
    creation_time = project_results.get("created_at")
    duration = project_results.get("duration")
    source_language = project_results.get("source_language")
    target_languages = project_results.get("target_languages", [])
    studio_url = project_results.get("studio_url", None)

    print("\n--- Detailed Project Analysis ---")

    print(f"Run ID: {run_id}")

    print(f"Successfully retrieved setup results for: {project_name}")

    # Show project description for context understanding
    if description:
        print(f"Project description: {description}")

    # Display timing information for project management
    if creation_time:
        # Convert ISO timestamp to readable format for team coordination
        created = datetime.fromisoformat(creation_time.replace("Z", "+00:00"))
        print(f"Project created: {created.strftime('%Y-%m-%d %H:%M:%S UTC')}")

    # Display duration information for resource planning
    if duration:
        # Convert seconds to minutes and seconds for easier understanding
        minutes = int(duration // 60)
        seconds = int(duration % 60)
        print(f"Media duration: {minutes}m {seconds}s ({duration:.1f} seconds)")

    # Display organizational information for team coordination
    if team_id:
        print(f"Team ID: {team_id}")

    # Show language configuration that determines dubbing scope
    print(f"Source language: {source_language}")

    # Show target language details for localization planning
    print(f"Target languages: {len(target_languages)} configured")
    print("This project will create dubbed versions in each configured language")

    print("\nProject is ready for creative editing in CAMB.AI Studio")
    if studio_url:
        print(f"Your team can now access this project to begin detailed dubbing work using this URL: {studio_url}")
```

## Planning Your Next Steps

Understanding your project setup results helps you make informed decisions about the creative editing phase that follows. The information provides essential context for planning editing time, coordinating team resources, and setting realistic expectations for project completion.

The duration and complexity information helps you estimate how much creative editing time will be required to achieve your quality goals. Projects with longer duration or more complex audio structures typically require more detailed attention during the editing process, while simpler projects might progress more quickly through creative refinement.

The language configuration details help you plan resource allocation across different target languages, particularly when working with languages that have different characteristics or when your team has varying expertise across different languages. Understanding the full scope of language work ahead enables better planning for review processes and quality assurance approaches.


# Get Project Setup Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-project-setup-status

get /project-setup/{task_id}
Monitor the progress and completion status of your project setup tasks. This endpoint provides real-time insights into the preparation process, helping you understand when your project becomes ready for editing in CAMB.AI Studio.

Understanding the status of your project setup process is crucial for coordinating workflows between technical teams and creative editors. This endpoint transforms the uncertainty of background processing into clear, actionable information about your project's readiness for Studio editing. Think of it as your project's progress dashboard, providing the visibility needed to plan next steps and coordinate team handoffs effectively.

When you initiate a project setup through the API, the system begins a sophisticated analysis and preparation process that happens behind the scenes. Rather than leaving you wondering about progress, this status endpoint provides detailed insights into each stage of preparation, helping you understand not just whether your project is ready, but what specific work has been completed and what remains in progress.

## Understanding Project Setup Progress

Project setup involves multiple complex operations that must complete successfully before your project becomes available in CAMB.AI Studio. Each operation contributes essential components to the final project workspace, and understanding this progression helps you better coordinate your content workflows.

The setup process begins with comprehensive media analysis, where our system examines your source content to understand its characteristics, audio structure, and optimal processing parameters. This analysis phase determines how the system will approach transcription, translation, and voice synthesis for your specific content. The status endpoint reveals insights from this analysis, helping you understand what the system discovered about your media and how it plans to optimize the dubbing process.

## The Task ID Connection

The task ID serves as your unique identifier for tracking project setup progress from initiation through completion. This identifier creates a direct link between your API-initiated project and the resulting Studio workspace, enabling seamless coordination between technical and creative workflows.

When you submit a project setup request, the system immediately returns a task ID that becomes your tracking reference throughout the preparation process. This ID remains constant and unique, allowing you to query status information at any time without ambiguity about which project you're monitoring. The same task ID that tracks setup progress will also identify your project within CAMB.AI Studio once preparation complete

## Monitoring Implementation

Let's examine how to effectively monitor project setup progress using Python. This implementation demonstrates both basic status checking and more sophisticated monitoring patterns that integrate well with broader workflow automation.

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

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

def check_project_setup_status(task_id):
    """
    Polls the status endpoint to track a project setup task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    terminal_states = ["SUCCESS", "ERROR"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/project-setup/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")
            if current_status == "PENDING":
                time.sleep(15)
                continue

            # Handle completed state
            if current_status == "SUCCESS":
                print("Project setup completed successfully!")
                return status_data

            # Handle failed state
            if current_status == "ERROR":
                print(f"Project setup task failed: {status_data.get('message')}")
                return status_data

            # Wait before next check to avoid excessive requests
            time.sleep(30)  # Poll every 30 seconds

        except requests.exceptions.RequestException as e:
            print(f"Error checking project setup status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")
            return None

    return None

# Example usage with a task_id from a previous dubbing request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_project_setup_status(task_id)
print(f"Project Setup Task Status: {final_status}")
```

## Best Practices for Status Monitoring

To efficiently track your project setup tasks, consider these professional recommendations:

1. Implement Exponential Backoff: Start with frequent checks that gradually increase in interval to avoid overloading the API.
2. Handle Terminal States: Always implement proper handling for both successful completion and failure cases.

By properly integrating status checking into your application, you can create a seamless dubbing experience that keeps your users informed throughout the entire process.


# Get all Source Languages
Source: https://docs.camb.ai/api-reference/endpoint/get-source-languages

get /source-languages
Retrieves a comprehensive list of all source languages supported by the platform, including their unique identifiers, language names, and corresponding short names.

This endpoint serves as your gateway to the multilingual capabilities of our platform, providing a complete catalog of all languages that can be used as source languages in translation, text-to-speech, and other language processing operations. By querying this endpoint, you'll receive detailed information about each supported language, enabling you to make informed choices when implementing multilingual features in your applications.

## Understanding Source Languages

Source languages represent the starting point in language transformation processes. When you translate content, convert text to speech, or perform other language operations, the source language is the original language of your content. Having accurate information about available source languages is fundamental to ensuring your application correctly processes user input.

## How to Use This Endpoint

To retrieve the list of supported source languages, simply send a `GET` request to this endpoint. No parameters are required, as the response will include all available source languages. The system will respond with an array containing detailed information about each language.

## Understanding Language Identifiers

The language identifiers returned by this endpoint are crucial for other API operations. When you make requests to endpoints like [`/translate`](create-translation), [`/tts`](create-tts), or other language-processing endpoints, you'll need to specify the source language using the `id` value. This creates a consistent system for language identification across the entire API.

Here's how the language identifiers connect different parts of the API ecosystem:

1. **Fetch available languages** using the [`/source-languages`](get-source-languages) endpoint.
2. **Present choices** to your users in a meaningful way using the `language` property.
3. **Submit requests** to other endpoints using the `id` property as the language identifier.

This workflow ensures that your application always uses valid language values that the API can understand and process correctly.

## Relationship with Target Languages

It's important to understand the distinction between source languages (provided by this endpoint) and target languages (provided by the [`/target-languages`](get-target-languages) endpoint):

* **Source languages** are languages that your content starts in.
* **Target languages** are languages that your content can be translated into.

While there is often significant overlap between these sets, they are not always identical. Some languages may be available as source languages but not as target languages, or vice versa. For comprehensive multilingual applications, you should check both endpoints to understand the full range of language transformations available to you.

## Best Practices

When working with the `/source-languages` endpoint, consider these recommendations:

1. **Cache the results**: Since language lists change infrequently, store the response locally and refresh it periodically (e.g., once a day) rather than making a request every time a user interacts with your application.

2. **Sort languages appropriately**: In user interfaces, consider sorting languages alphabetically or by relevance to your user base.

3. **Use appropriate identifiers**: Always use the `id` field when making API requests, rather than the language name or short name.

4. **Provide search functionality**: For applications with many language options, implement search or filtering to help users quickly find their desired language.

5. **Consider language variants**: Be aware that some languages may have multiple variants (e.g., American English vs. British English) that could be listed separately.

By leveraging this endpoint effectively, you can create truly global applications that serve users in their preferred languages, enhancing accessibility and user experience across diverse audiences.


# Retrieve Story Results
Source: https://docs.camb.ai/api-reference/endpoint/get-story-run-info

get /story-result/{run_id}
Access completed story conversion outputs and transcripts using the unique run identifier

Obtain the final products of your story conversion process through this endpoint. When a story generation task completes successfully, this endpoint provides direct access to the produced audio files and optional textual transcript - enabling immediate integration into audiobook platforms, content management systems, or interactive storytelling applications.

## Story Conversion Outputs

Successful requests return three core components:

* **Full Audio Narration**: Complete audiobook-style recording (`audio_url`)

* **Dialogue-Only Track**: Isolated character conversations (`dialogue_url`)

* **Time-Coded Transcript**: Optional narrative transcript with speaker attribution

<Info>Transcripts require explicit request via the `include_transcript` query parameter</Info>

<Warning title="URL Expiration Notice">Retrieved audio links become inaccessible after 24 hours</Warning>

## Example Python Implementation

Here’s how to fetch your completed story results using Python:

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

def fetch_story_assets(run_id, include_transcript=False):
    """
    Retrieves story conversion outputs with optional transcript

    Args:
        run_id: Unique identifier from story processing task
        include_transcript: Whether to return narrative transcript

    Returns:
        Dict containing audio URLs and optional transcript
    """
    headers = {
        "x-api-key": "your-api-key",
        "Content-Type": "application/json"
    }

    params = {"include_transcript": str(include_transcript).lower()}

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/story-result/{run_id}",
            headers=headers,
            params=params
        )
        response.raise_for_status()

        result = response.json()
        print(f"Retrieved story assets for Run ID: {run_id}")

        return result

    except requests.exceptions.HTTPError as e:
        print(f"Error {e.response.status_code}: {e.response.text}")
        return None

# Example usage with transcript request
story_data = fetch_story_assets(
    run_id=9872, # Replace with your actual run ID.
    include_transcript=True
)

if story_data:
    print(f"Main Audio: {story_data['audio_url']}")
    print(f"Dialogue Track: {story_data['dialogue_url']}")

    if story_data.get('transcript'):
        print(f"\nTranscript Preview:")
        for entry in story_data['transcript'][:2]:
            print(f"[{entry['start']}-{entry['end']}ms] {entry['speaker']}: {entry['text']}")
```


# Get Story Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-story-status

get /story/{task_id}
Retrieves the current status of a story task using the specified `task_id`.

Track the progression of your story creation process through systematic status checks. This endpoint provides granular visibility into each processing stage, enabling precise workflow management for time-sensitive applications.

This endpoint works in conjunction with the main [`/story`](create-story) endpoint, which initiates the dubbing process and provides the `task_id` needed for status checks.

## Checking Your Story Status

Let's explore how to effectively monitor your generation task using Python:

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

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

def check_story_status(task_id, polling_interval=5):
    """
    Monitors the status of a story generation task until completion.

    Parameters:
    - task_id: The unique identifier for your generation task
    - polling_interval: How frequently to check status (in seconds)

    Returns:
    - The final status response upon completion or failure
    """
    print(f"Beginning status monitoring for task: {task_id}")

    # Initialize tracking variables
    start_time = datetime.now()
    last_status = None

    while True:
        try:
            # Request the current status
            response = requests.get(
                f"https://client.camb.ai/apis/story/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Parse the status information
            status_data = response.json()
            current_status = status_data.get('status')

            # Track status changes for informative updates
            if current_status != last_status:
                elapsed_time = (datetime.now() - start_time).total_seconds()
                print(f"[{elapsed_time:.1f}s] Status: {current_status}")

                # Update our tracking variables
                last_status = current_status
                last_substatus = current_substatus

            # Check if the process has completed or failed
            if current_status == "SUCCESS":
                print("\n✓ Sound generation completed successfully!")
                print(f"Run ID : {status_data.get('run_id')}")
                return status_data
            elif current_status == "FAILED":
                print(f"\n✗ Sound generation failed: {status_data.get('message', 'Unknown error')}")
                return status_data


            # Wait before checking again
            time.sleep(polling_interval)

        except requests.exceptions.RequestException as e:
            print(f"Error checking generation status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")

            # Brief pause before retry after error
            time.sleep(polling_interval)

# Example usage with intelligent polling
task_id = "your_task_id"  # Replace with your actual task_id
final_status = check_story_status(task_id, polling_interval=3)

# Process the completed result
if final_status and final_status.get('status') == "SUCCESS":
    print(f"Processing completed audio from: {audio_url}")

    # Download the generated audio
    audio_response = requests.get(audio_url)
    if audio_response.status_code == 200:
        print(f"Task completed successfully!, run ID {status_data.get('run_id')}")
```

## Best Practices for Status Monitoring

To efficiently track your dubbing tasks, consider these professional recommendations:

1. **Implement Exponential Backoff**: Start with frequent checks that gradually increase in interval to avoid overloading the API.
2. **Handle Terminal States**: Always implement proper handling for both successful completion and failure cases.

By properly integrating status checking into your application, you can create a seamless dubbing experience that keeps your users informed throughout the entire process.


# Get Subtitle Result for Language
Source: https://docs.camb.ai/api-reference/endpoint/get-subtitle-result-for-language

get /sub-result/{run_id}/{language}
Retrieves the transcript in a specific language of a completed subtitle run using the provided `run_id`, with optional export to `srt`/`vtt`/`txt`.

Fetches subtitles for **one language** of a completed subtitle run.

* **By default** (no query params) you get the **structured JSON transcript** for that language: `{ "transcript": [ {start, end, text, speaker}, ... ] }`.
* **When you pass `format_type` and/or `data_type`**, the transcript is exported and returned as `{ "transcript": <presigned url | raw text> }`, the same parameter values and response shape as [Get Transcription Result](get-transcription-run-result).

<Info>
  The `{language}` path parameter must be the run's source language or one of the target languages from [Create Subtitle](create-subtitle). Pass a locale tag (`es-es`, `fr-fr`); numeric IDs still work but are deprecated.
</Info>

If the run was created with `formatting_options` on [Create Subtitle](create-subtitle), the segments already follow subtitle timing and length rules.

## Choosing your output

| Parameter            | Values                                                  | Behaviour                                                                            |
| :------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------- |
| *(none)*             | n/a                                                     | Structured JSON transcript: `{ "transcript": [ {start, end, text, speaker}, ... ] }` |
| `data_type=file`     | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | `{ "transcript": "<presigned url>" }`: a downloadable file                           |
| `data_type=raw_data` | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | `{ "transcript": "<raw text>" }`: the rendered text inline                           |

`format_type` (`srt`/`vtt`/`txt`) and `data_type` (`raw_data`/`file`) use the exact same values as [Get Transcription Result](get-transcription-run-result). Need every language at once? Use [Get Subtitle Result](get-subtitle-run-result) — it supports the same export params for all languages in one call.

## Implementation Example

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

API_KEY = "your_api_key_here"
RUN_ID = 12345
LANGUAGE = "es-es"  # Locale tag; numeric IDs (e.g. 23) still work but are deprecated

url = f"https://client.camb.ai/apis/sub-result/{RUN_ID}/{LANGUAGE}"
headers = {"x-api-key": API_KEY}

# 1) Default: structured JSON transcript for this language
result = requests.get(url, headers=headers).json()
for segment in result["transcript"]:
    print(f"[{segment['start']} - {segment['end']}] {segment['speaker']}: {segment['text']}")

# 2) Export: presigned URL to an SRT file
srt = requests.get(
    url, headers=headers, params={"format_type": "srt", "data_type": "file"}
).json()
print(f"SRT file: {srt['transcript']}")

# 3) Export: raw VTT text inline
vtt = requests.get(
    url, headers=headers, params={"format_type": "vtt", "data_type": "raw_data"}
).json()
print(vtt["transcript"][:150])
```

## Understanding the Response Structure

The response is always a JSON object with a single `transcript` field. Its value depends on the parameters.

### Default: structured transcript (no params)

```json theme={null}
{
  "transcript": [
    { "start": 5.0,  "end": 12.0, "text": "Bienvenidos a nuestra discusión sobre IA.", "speaker": "SPEAKER_0" },
    { "start": 13.0, "end": 18.0, "text": "Gracias por invitarme.",                    "speaker": "SPEAKER_1" }
  ]
}
```

| Field     | Description                            |
| :-------- | :------------------------------------- |
| `start`   | Start time of the segment (seconds)    |
| `end`     | End time of the segment (seconds)      |
| `text`    | Text for the segment, in that language |
| `speaker` | Speaker identifier                     |

### Export: file (`data_type=file`)

```json theme={null}
{ "transcript": "https://storage.example.com/.../output_transcript.srt?..." }
```

`transcript` is a presigned URL to the rendered file. The file content matches your `format_type`:

#### TXT (`format_type=txt`)

```
[00:00:05 - 00:00:12] SPEAKER_0: Bienvenidos a nuestra discusión sobre IA.
[00:00:13 - 00:00:18] SPEAKER_1: Gracias por invitarme.
```

#### SRT (`format_type=srt`)

```
1
00:00:05,000 --> 00:00:12,000
SPEAKER_0: Bienvenidos a nuestra discusión sobre IA.

2
00:00:13,000 --> 00:00:18,000
SPEAKER_1: Gracias por invitarme.
```

#### VTT (`format_type=vtt`)

```
WEBVTT

00:00:05.000 --> 00:00:12.000
SPEAKER_0: Bienvenidos a nuestra discusión sobre IA.

00:00:13.000 --> 00:00:18.000
SPEAKER_1: Gracias por invitarme.
```

### Export: raw data (`data_type=raw_data`)

The same rendered content is returned inline as a string:

```json theme={null}
{ "transcript": "1\n00:00:05,000 --> 00:00:12,000\nSPEAKER_0: Bienvenidos a nuestra discusión sobre IA.\n\n..." }
```

<Info>The presigned file URL expires after 24 hours, so download your file soon.</Info>

## Building a Complete Workflow

* [Create Subtitle](create-subtitle): submit your media for subtitle generation
* [Get Subtitle Task Status](poll-subtitle-result): determine when your subtitles are ready
* [Get Subtitle Result](get-subtitle-run-result): every language at once (same export params)


# Get Subtitle Result
Source: https://docs.camb.ai/api-reference/endpoint/get-subtitle-run-result

get /sub-result/{run_id}
Retrieves the transcript of a subtitle run using the provided `run_id`, for every language on the run.

Fetches the result of a completed subtitle run: the source language plus each target language from [Create Subtitle](create-subtitle).

* **By default** (no query params) you get the **structured JSON transcript**: one language returns `{ "transcript": [ {start, end, text, speaker}, ... ] }`; multiple languages return an object keyed by language ID with that same shape per language.
* **When you pass `format_type` and/or `data_type`**, every language on the run is exported. One language returns `{ "transcript": <presigned url | raw text> }`; multiple languages return an object keyed by language ID, each value `{ "transcript": <presigned url | raw text> }`. Same parameter values as [Get Transcription Result](get-transcription-run-result).

<Info>
  Use the `run_id` returned when you created the subtitle run. The run must have finished processing and must be a subtitle project.
</Info>

If the run was created with `formatting_options` on [Create Subtitle](create-subtitle), every language's segments already follow subtitle timing and length rules. The response shape stays the same; only where each segment starts and ends differs.

## Choosing your output

| Parameter            | Values                                                  | Behaviour                                                                                                                |
| :------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------- |
| *(none)*             | n/a                                                     | Structured JSON: one language → `{ "transcript": [ ... ] }`; many → `{ "<lang_id>": { "transcript": [ ... ] }, ... }`    |
| `data_type=file`     | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | One language → `{ "transcript": "<presigned url>" }`; many → `{ "<lang_id>": { "transcript": "<presigned url>" }, ... }` |
| `data_type=raw_data` | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | Same shapes as `file`, but each `transcript` value is the rendered text inline                                           |

`format_type` (`srt`/`vtt`/`txt`) and `data_type` (`raw_data`/`file`) use the exact same values as [Get Transcription Result](get-transcription-run-result). For a single language only, use [Get Subtitle Result for Language](get-subtitle-result-for-language).

## Implementation Example

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

API_KEY = "your_api_key_here"
RUN_ID = 12345

url = f"https://client.camb.ai/apis/sub-result/{RUN_ID}"
headers = {"x-api-key": API_KEY}

# 1) Default: structured JSON for every language
result = requests.get(url, headers=headers).json()
if "transcript" in result:
    for segment in result["transcript"]:
        print(f"[{segment['start']} - {segment['end']}] {segment['speaker']}: {segment['text']}")
else:
    for language_id, language_result in result.items():
        print(f"\nLanguage {language_id}:")
        for segment in language_result["transcript"]:
            print(f"  [{segment['start']} - {segment['end']}] {segment['speaker']}: {segment['text']}")

# 2) Export: SRT file URL for every language
srt = requests.get(
    url, headers=headers, params={"format_type": "srt", "data_type": "file"}
).json()
if "transcript" in srt:
    print(f"SRT file: {srt['transcript']}")
else:
    for language_id, payload in srt.items():
        print(f"Language {language_id}: {payload['transcript']}")

# 3) Export: raw VTT text inline for every language
vtt = requests.get(
    url, headers=headers, params={"format_type": "vtt", "data_type": "raw_data"}
).json()
if "transcript" in vtt:
    print(vtt["transcript"][:150])
else:
    for language_id, payload in vtt.items():
        print(f"Language {language_id}:\n{payload['transcript'][:150]}")
```

## Understanding the Response Structure

### Default: structured transcript (no params)

#### Single language on the run

```json theme={null}
{
  "transcript": [
    { "start": 5.0,  "end": 12.0, "text": "Welcome to our discussion on AI.", "speaker": "SPEAKER_0" },
    { "start": 13.0, "end": 18.0, "text": "Thank you for having me.",         "speaker": "SPEAKER_1" }
  ]
}
```

#### Multiple languages on the run

```json [expandable] theme={null}
{
  "1": {
    "transcript": [
      { "start": 5.0, "end": 12.0, "text": "Welcome to our discussion on AI.", "speaker": "SPEAKER_0" }
    ]
  },
  "23": {
    "transcript": [
      { "start": 5.0, "end": 12.5, "text": "Bienvenidos a nuestra discusión sobre IA.", "speaker": "SPEAKER_0" }
    ]
  }
}
```

| Field     | Description                            |
| :-------- | :------------------------------------- |
| `start`   | Start time of the segment (seconds)    |
| `end`     | End time of the segment (seconds)      |
| `text`    | Text for the segment, in that language |
| `speaker` | Speaker identifier                     |

### Export: file (`data_type=file`)

#### Single language

```json theme={null}
{ "transcript": "https://storage.example.com/.../output_transcript.srt?..." }
```

#### Multiple languages

```json theme={null}
{
  "1":  { "transcript": "https://storage.example.com/.../en_us/output_transcript.srt?..." },
  "23": { "transcript": "https://storage.example.com/.../es_es/output_transcript.srt?..." }
}
```

`transcript` is a presigned URL to the rendered file. The file content matches your `format_type`:

#### TXT (`format_type=txt`)

```
[00:00:05 - 00:00:12] SPEAKER_0: Welcome to our discussion on AI.
[00:00:13 - 00:00:18] SPEAKER_1: Thank you for having me.
```

#### SRT (`format_type=srt`)

```
1
00:00:05,000 --> 00:00:12,000
SPEAKER_0: Welcome to our discussion on AI.

2
00:00:13,000 --> 00:00:18,000
SPEAKER_1: Thank you for having me.
```

#### VTT (`format_type=vtt`)

```
WEBVTT

00:00:05.000 --> 00:00:12.000
SPEAKER_0: Welcome to our discussion on AI.

00:00:13.000 --> 00:00:18.000
SPEAKER_1: Thank you for having me.
```

### Export: raw data (`data_type=raw_data`)

The same rendered content is returned inline as a string (flat for one language, keyed by language ID for many):

```json theme={null}
{ "transcript": "1\n00:00:05,000 --> 00:00:12,000\nSPEAKER_0: Welcome to our discussion on AI.\n\n..." }
```

```json theme={null}
{
  "1":  { "transcript": "1\n00:00:05,000 --> 00:00:12,000\nSPEAKER_0: Welcome...\n\n..." },
  "23": { "transcript": "1\n00:00:05,000 --> 00:00:12,500\nSPEAKER_0: Bienvenidos...\n\n..." }
}
```

<Info>The presigned file URL expires after 24 hours, so download your file soon.</Info>

## Fetching Multiple Runs at Once

Need subtitles for several runs? Use [Fetch Subtitle Run Results](fetch-subtitles-runs-results) (`POST /apis/sub-results`). It accepts the same optional `format_type` / `data_type` query params.

## Building a Complete Workflow

* [Create Subtitle](create-subtitle): submit your media for subtitle generation
* [Get Subtitle Task Status](poll-subtitle-result): determine when your subtitles are ready


# Get all Target Languages
Source: https://docs.camb.ai/api-reference/endpoint/get-target-languages

get /target-languages
Retrieves a comprehensive list of all target languages supported by the platform, including their unique identifiers, language names, and corresponding short names.

This endpoint serves as your gateway to the multilingual output capabilities of our platform, providing a complete catalog of all languages that can be used as target languages in translation, text-to-speech, and other language processing operations. By querying this endpoint, you'll receive detailed information about each supported language, enabling you to make informed choices when implementing multilingual features in your applications.

## Understanding Target Languages

Target languages represent the destination in language transformation processes. When you translate content, the target language is the language into which your content will be converted. Having accurate information about available target languages is fundamental to ensuring your application correctly delivers content to your diverse user base.

## How to Use This Endpoint

To retrieve the list of supported target languages, simply send a `GET` request to this endpoint. No parameters are required, as the response will include all available target languages. The system will respond with an array containing detailed information about each language.

## Understanding Language Identifiers

The language identifiers returned by this endpoint are crucial for other API operations. When you make requests to endpoints like [`/translate`](create-translation), you'll need to specify the target language using the `id` value. This creates a consistent system for language identification across the entire API.

Here's how the language identifiers connect different parts of the API ecosystem:

1. **Fetch available languages** using the [`/target-languages`](get-target-languages) endpoint.
2. **Present choices** to your users in a meaningful way using the `language` property.
3. **Submit requests** to other endpoints using the `id` property as the language identifier.

This workflow ensures that your application always uses valid language values that the API can understand and process correctly.

## Relationship with Source Languages

It's important to understand the distinction between target languages (provided by this endpoint) and source languages (provided by the [`/source-languages`](get-source-languages) endpoint):

* **Target languages** are languages that your content can be translated into.
* **Source languages** are languages that your content starts in.

While there is often significant overlap between these sets, they are not always identical. Some languages may be available as target languages but not as source languages, or vice versa. For comprehensive multilingual applications, you should check both endpoints to understand the full range of language transformations available to you.

## Best Practices

When working with the `/target-languages` endpoint, consider these recommendations:

1. **Cache the results**: Since language lists change infrequently, store the response locally and refresh it periodically (e.g., once a day) rather than making a request every time a user interacts with your application.
2. **Sort languages appropriately**: In user interfaces, consider sorting languages alphabetically or by relevance to your user base.
3. **Use appropriate identifiers**: Always use the `id` field when making API requests, rather than the language name or short name.
4. **Provide search functionality**: For applications with many language options, implement search or filtering to help users quickly find their desired language.
5. **Display language variants clearly**: When presenting language options to users, ensure variants of languages (e.g., Brazilian Portuguese vs. European Portuguese) are clearly distinguished.

By leveraging this endpoint effectively, you can create truly global applications that deliver content in users' preferred languages, enhancing accessibility and user experience across diverse audiences.


# Get Sound and Music Run Result
Source: https://docs.camb.ai/api-reference/endpoint/get-text-to-sound-run-result

get /text-to-sound-result/{run_id}
Retrieve the generated audio file for a completed Sound and Music task.

This endpoint retrieves the audio output generated from a previously completed Sound and Music task. It provides access to the audio content that was created based on the text prompt and configuration specified in your original request based on returned `run_id`.

The endpoint supports two different response formats based on your needs:

### Audio Stream (Default)

Returns the raw audio bytes of your generated sound effect in WAV format. This is ideal for:

* Direct playback in browser applications
* Immediately saving the audio to your local system
* Streaming the audio to users in real-time applications

### Download URL

**Content-Type: application/json**

Returns a JSON object containing a URL where the generated audio file can be downloaded:

```json theme={null}
{
  "file_url": "https://storage.example.com/text-to-sound/your-generated-file.wav"
}
```

This option is useful when you prefer to:

* Defer the actual download to a later time
* Share the audio file with others via a link
* Implement custom download behavior in your application

## Example Usage

### Retrieving Audio as a Stream

```bash theme={null}
curl -X GET "https://client.camb.ai.com/text-to-sound-result/run_abc123" \
  -H "x-api-key: YOUR_API_KEY" \
  --output my_sound_effect.wav
```

### Retrieving a Download URL

```bash theme={null}
curl -X GET "https://client.camb.ai.com/text-to-sound-result/run_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "file_url": "https://storage.example.com/sounds/abc123.wav"
}
```

## Best Practices

To get the most from this endpoint:

1. **Check Task Status First**: Only request results for tasks that have completed successfully.
2. **Handle Audio Appropriately**: The returned WAV format is widely compatible but may need conversion for specific use cases.
3. **Download Promptly**: Temporary URLs may expire after a certain period, so download and store important files.

## Technical Considerations

* The generated audio files are delivered in WAV format which provides high quality but larger file sizes.
* If the specified `run_id` doesn't exist or hasn't completed processing, you'll receive an appropriate error response.

By integrating this endpoint with your audio production workflow, you can seamlessly access AI-generated sound effects created from text descriptions, enabling new creative possibilities for your projects.


# Get Sound and Music Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-text-to-sound-status

get /text-to-sound/{task_id}
Checks the current status of a sound and music generation task by querying with the provided `task_id`.

Monitor and track your audio generation journey with our intelligent status tracking system. This essential endpoint serves as your window into the text-to-sound conversion process, providing real-time insights into how your audio creation status. Understanding the status of your generation tasks allows you to build responsive applications that can adapt to the asynchronous nature of complex audio synthesis, creating smoother user experiences and more efficient resource management in your creative workflows.

## Checking Your Sound Generation Status

Let's explore how to effectively monitor your generation task using Python:

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

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

def check_sound_generation_status(task_id, polling_interval=5):
    """
    Monitors the status of a text-to-sound generation task until completion.

    Parameters:
    - task_id: The unique identifier for your generation task
    - polling_interval: How frequently to check status (in seconds)

    Returns:
    - The final status response upon completion or failure
    """
    print(f"Beginning status monitoring for task: {task_id}")

    # Initialize tracking variables
    start_time = datetime.now()
    last_status = None

    while True:
        try:
            # Request the current status
            response = requests.get(
                f"https://client.camb.ai/apis/text-to-sound/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Parse the status information
            status_data = response.json()
            current_status = status_data.get('status')

            # Track status changes for informative updates
            if current_status != last_status:
                elapsed_time = (datetime.now() - start_time).total_seconds()
                print(f"[{elapsed_time:.1f}s] Status: {current_status}")

                # Update our tracking variables
                last_status = current_status
                last_substatus = current_substatus

            # Check if the process has completed or failed
            if current_status == "SUCCESS":
                print("\n✓ Sound generation completed successfully!")
                print(f"Run ID : {status_data.get('run_id')}")
                return status_data
            elif current_status == "FAILED":
                print(f"\n✗ Sound generation failed: {status_data.get('message', 'Unknown error')}")
                return status_data


            # Wait before checking again
            time.sleep(polling_interval)

        except requests.exceptions.RequestException as e:
            print(f"Error checking generation status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")

            # Brief pause before retry after error
            time.sleep(polling_interval)

# Example usage with intelligent polling
task_id = "your_task_id"  # Replace with your actual task_id
final_status = check_sound_generation_status(task_id, polling_interval=3)

# Process the completed result
if final_status and final_status.get('status') == "SUCCESS":
    print(f"Processing completed audio from: {audio_url}")

    # Download the generated audio
    audio_response = requests.get(audio_url)
    if audio_response.status_code == 200:
        print(f"Task completed successfully!, run ID {status_data.get('run_id')}")
```


# Get Voice from Description Result
Source: https://docs.camb.ai/api-reference/endpoint/get-text-to-voice-run-result

get /text-to-voice-result/{run_id}
Retrieve AI-generated voice interpretations and select your preferred vocal style from multiple audio options using `run_id`.

## Understanding Voice Generation Results

This endpoint provides access to the results of your voice generation request after processing has completed. When you submit a text description through the [`/text-to-voice`](create-text-to-voice) endpoint, our system analyzes your parameters and creates not just one, but two distinct voice interpretations based on your description. This approach gives you the opportunity to compare different vocal realizations and select the one that best matches your intended use case.

## How to Access Your Voice Interpretations

To retrieve your voice generation results, you'll need the `run_id` that was provided when you initially submitted your voice generation request. This identifier uniquely references your specific generation task and allows you to access its results once processing is complete.

The endpoint follows this structure:

```
GET /text-to-voice-result/{run_id}
```

Where `{run_id}` should be replaced with your actual run identifier. For example:

```
GET /text-to-voice-result/8827
```

## Understanding the Response

When you call this endpoint, the system returns a JSON object containing URLs to two audio previews. Both previews represent a different interpretation of your voice description, speaking the same text content you provided during submission. These previews have the following characteristics:

### Preview Variations Explained

1. **Preview 1: Primary Interpretation**
   This first interpretation closely adheres to the core parameters of your description. It represents the system's primary understanding of your requested voice characteristics, focusing on the fundamental attributes you specified such as gender, age range, and basic tonal qualities.

2. **Preview 2: Nuanced Alternative**
   The second interpretation explores alternative expressions of your description with modified pacing and emphasis patterns. This version might adjust factors like speaking rate, rhythmic patterns, and the relative emphasis placed on different syllables or words, creating a subtly different feel while still honoring your core description.

Each of these interpretations applies different:

* **Emotional cadence variations**: How emotional qualities rise and fall throughout the speech
* **Prosody adjustments**: Alterations in intonation patterns, rhythm, stress, and tonal qualities
* **Phonetic emphasis patterns**: Changes in how individual sounds are articulated and emphasized

These variations are carefully calibrated to give you meaningful choices rather than random alternatives. By comparing the two interpretations side by side, you can identify which vocal qualities best serve your specific needs.

## From Preview to Permanent Voice

The preview voices you receive are temporary by design, intended to help you evaluate different interpretations of your description. However, you can convert any preview you particularly like into a permanent custom voice that becomes available throughout our speech synthesis ecosystem.

### Creating a Permanent Voice Profile

The process of converting a preview into a permanent voice involves these key steps:

<Steps>
  <Step title="Retrieve and evaluate your preview samples">
    First, call this endpoint to access your two preview options and determine which one best meets your needs.
  </Step>

  <Step title="Create a permanent voice profile">
    Once you've selected your preferred preview, you can use the [`/voices/create-custom-voice`](create-custom-voice) endpoint to establish a permanent voice profile based on that preview.
  </Step>

  <Step title="Integrate your custom voice">
    After creation, your new voice becomes available for use across all compatible speech synthesis services within our platform.
  </Step>
</Steps>

This workflow allows you to move from concept (your text description) to evaluation (the two previews) to implementation (your permanent custom voice) in a streamlined process.

## Implementation Example

The following Python code demonstrates how to retrieve your preview samples and convert your preferred option into a permanent custom voice:

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

BASE_URL = "https://client.camb.ai/apis"

def create_voice_from_preview(run_id, preview_index=0):
    """
    Converts temporary preview into permanent custom voice

    This function performs a complete workflow:
    1. Retrieves the specified preview audio using the run_id
    2. Downloads the selected preview to a local file
    3. Creates a permanent voice clone from this sample

    Parameters:
        run_id (int): The unique identifier of your voice generation task
        preview_index (int): Which preview to use (0 or 1, corresponding to the two previews)

    Returns:
        dict: Response from the custom voice creation API
    """
    # Retrieve preview URL from the results endpoint
    preview_res = requests.get(f"{BASE_URL}/text-to-voice-result/{run_id}")
    preview_url = preview_res.json()['previews'][preview_index]

    # Download the selected audio sample to a local file
    audio_file = requests.get(preview_url).content
    with open("voice_sample.mp3", "wb") as f:
        f.write(audio_file)

    # Create a permanent custom voice using the downloaded sample
    files = {'file': open('voice_sample.mp3', 'rb')}
    data = {
        'voice_name': 'My Campaign Voice',  # Choose a descriptive name for your voice
        'gender': 1,  # Male (matches preview characteristics)
        'age': 35     # Estimated vocal age
    }

    creation_res = requests.post(
        f"{BASE_URL}/create-custom-voice",
        files=files,
        data=data,
        headers={"x-api-key": API_KEY}
    )

    return creation_res.json()

# Example usage
voice_profile = create_voice_from_preview(run_id=8827, preview_index=1)
print(f"New voice ID: {voice_profile['voice_id']}")
```

## Best Practices for Voice Selection

When evaluating your preview options, consider these factors to make the most effective choice:

1. **Content context**: Different voices may be more suitable depending on whether your content is informational, narrative, promotional, or instructional.

2. **Audience expectations**: Consider what vocal qualities would resonate best with your target audience based on their demographic and psychographic characteristics.

3. **Brand alignment**: If the voice will represent your brand, assess which interpretation best embodies your brand personality and values.

4. **Emotional impact**: Listen for how each voice conveys emotional subtext and choose the one that elicits the desired emotional response.

5. **Technical qualities**: Consider practical aspects like clarity, intelligibility across different listening environments, and how well the voice handles specialized vocabulary.

By comparing your two preview options with these considerations in mind, you can select the voice interpretation that will most effectively serve your communication objectives.

<Tip>To ensure the best experience, always verify that your voice generation task has completed successfully before attempting to access the results</Tip>

By understanding the nuances of voice interpretation and making thoughtful selections from your preview options, you can establish voice profiles that authentically convey your message and connect with your audience.


# Get Voice from Description Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-text-to-voice-status

get /text-to-voice/{task_id}
Monitor the progress of your AI-generated voice creation through real-time status updates.

Track every stage of your voice generation process with millisecond precision. This endpoint provides real-time visibility into voice synthesis tasks, enabling seamless integration with time-sensitive applications like live narration systems and interactive voice interfaces.

<Card icon="lightbulb" href="create-text-to-voice">
  This endpoint works in conjunction with the main `/text-to-voice` endpoint, which initiates the voice generation process and provides the essential `task_id` for status monitoring.
</Card>

## Monitoring Your Voice Generation

Implement intelligent status tracking with this Python example:

```python [expandable] theme={null}
def monitor_voice_creation(task_id, poll_interval=5):
    """
    Advanced status tracking with automatic recovery suggestions
    """
    status_guidance = {
        "SUCCESS": {"icon": "✅", "action": "download_voice"},
        "PENDING": {"icon": "⏳", "action": "wait"},
        "TIMEOUT": {"icon": "⏰", "action": "retry_or_contact"},
        "ERROR": {"icon": "❌", "action": "review_inputs"},
        "PAYMENT_REQUIRED": {"icon": "💳", "action": "add_credits"}
    }

    while True:
        response = requests.get(f"/text-to-voice/{task_id}", headers=headers)
        status_data = response.json()
        current_status = status_data.get('status')

        # Get status metadata
        guidance = status_guidance.get(current_status, {})
        print(f"{guidance.get('icon', 'ℹ️')} Status: {current_status}")

        # Handle terminal states
        if current_status in ["SUCCESS", "TIMEOUT", "ERROR", "PAYMENT_REQUIRED"]:
            print(f"Error details: {status_data.get('message', 'Contact support')}")
            print(f"Recommended action: {guidance.get('action', 'contact_support')}")
            if current_status == "SUCCESS":
                print(f"\n🎉 Voice generation completed!")
                print(f"Production ID: {status_data.get('run_id')}")
            return status_data

        time.sleep(poll_interval)
```

This polling mechanism gives you flexibility to build applications that can provide real-time feedback to users about their voice from description creations. You can adjust the polling interval based on your specific needs, checking more frequently for time-sensitive applications or less frequently for background tasks.

## Next Steps

Once your task shows a status of `SUCCESS`, you’ll receive a `run_id` in the response. This `run_id` is your key to accessing the generated sample audio files for the voices. Take this identifier and use it with the [`/text-to-voice-result/{run_id}`](get-text-to-vocie-run-result) endpoint to download your the sample voices, select the one that matches your desired characteristics and put it to work in your application.


# Get Transcription Result
Source: https://docs.camb.ai/api-reference/endpoint/get-transcription-run-result

get /transcription-result/{run_id}
Retrieves the transcript of a transcription run using the provided `run_id`.

Fetches the result of a completed transcription run.

* **By default** (no query params) you get the **structured JSON transcript**: an object whose `transcript` field is an array of `{ start, end, text, speaker }` segments.
* **When you pass `format_type` and/or `data_type`**, the transcript is exported in the requested subtitle format and returned as `{ "transcript": <presigned url | raw text> }`, the same parameter values and response shape as the dubbing [Get Dubbing Transcript](get-dub-transcript) endpoint.

<Info>
  Use the `run_id` returned when you created the transcription run. The run must have finished processing and must be a transcription project.
</Info>

## Choosing your output

| Parameter            | Values                                                  | Behaviour                                                                            |
| :------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------- |
| *(none)*             | n/a                                                     | Structured JSON transcript: `{ "transcript": [ {start, end, text, speaker}, ... ] }` |
| `data_type=file`     | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | `{ "transcript": "<presigned url>" }`: a downloadable file                           |
| `data_type=raw_data` | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | `{ "transcript": "<raw text>" }`: the rendered text inline                           |

`format_type` (`srt`/`vtt`/`txt`) and `data_type` (`raw_data`/`file`) use the exact same values as the dubbing `/transcript` endpoint, and the export responses are identical.

## Implementation Example

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

API_KEY = "your_api_key_here"
RUN_ID = 12345

url = f"https://client.camb.ai/apis/transcription-result/{RUN_ID}"
headers = {"x-api-key": API_KEY}

# 1) Default: structured JSON transcript
result = requests.get(url, headers=headers).json()
for segment in result["transcript"]:
    print(f"[{segment['start']} - {segment['end']}] {segment['speaker']}: {segment['text']}")

# 2) Export: presigned URL to an SRT file
srt = requests.get(
    url, headers=headers, params={"format_type": "srt", "data_type": "file"}
).json()
file_url = srt["transcript"]
print(f"SRT file: {file_url}")

# 3) Export: raw VTT text inline
vtt = requests.get(
    url, headers=headers, params={"format_type": "vtt", "data_type": "raw_data"}
).json()
print(vtt["transcript"][:150])
```

## Understanding the Response Structure

The response is always a JSON object with a single `transcript` field. Its value depends on the parameters.

### Default: structured transcript (no params)

```json theme={null}
{
  "transcript": [
    { "start": 5.0,  "end": 12.0, "text": "Welcome to our discussion on AI.", "speaker": "SPEAKER_0" },
    { "start": 13.0, "end": 18.0, "text": "Thank you for having me.",         "speaker": "SPEAKER_1" }
  ]
}
```

| Field     | Description                         |
| :-------- | :---------------------------------- |
| `start`   | Start time of the segment (seconds) |
| `end`     | End time of the segment (seconds)   |
| `text`    | Transcribed text for the segment    |
| `speaker` | Speaker identifier                  |

### Export: file (`data_type=file`)

```json theme={null}
{ "transcript": "https://storage.example.com/.../output_transcript.srt?..." }
```

`transcript` is a presigned URL to the rendered file. The file content matches your `format_type`:

#### TXT (`format_type=txt`)

```
[00:00:05 - 00:00:12] Speaker 1: Welcome to our discussion on AI.
[00:00:13 - 00:00:18] Speaker 2: Thank you for having me.
```

#### SRT (`format_type=srt`)

```
1
00:00:05,000 --> 00:00:12,000
Speaker 1: Welcome to our discussion on AI.

2
00:00:13,000 --> 00:00:18,000
Speaker 2: Thank you for having me.
```

#### VTT (`format_type=vtt`)

```
WEBVTT

00:00:05.000 --> 00:00:12.000
Speaker 1: Welcome to our discussion on AI.

00:00:13.000 --> 00:00:18.000
Speaker 2: Thank you for having me.
```

### Export: raw data (`data_type=raw_data`)

The same rendered content is returned inline as a string:

```json theme={null}
{ "transcript": "1\n00:00:05,000 --> 00:00:12,000\nSpeaker 1: Welcome to our discussion on AI.\n\n..." }
```

<Info>The presigned file URL expires after 24 hours, so download your file soon.</Info>

## Fetching Multiple Runs at Once

Need transcripts for several runs? Use [Fetch Transcription Run Results](fetch-transcriptions-runs-results) (`POST /apis/transcription-results`). It returns the structured `{ start, end, text, speaker }` transcript per run and does not take `format_type` / `data_type`.

## Building a Complete Workflow

* [Create Transcription](create-transcription): submit your media for transcription
* [Poll Transcription Status](poll-transcription-result): determine when your transcript is ready


# Get Translated Story Result
Source: https://docs.camb.ai/api-reference/endpoint/get-translated-story-run-result

get /translated-story-result/{run_id}/{target_language}
Retrieves detailed results about a specific translated story using the provided `run_id` and `target_language` parameters.

Access the complete results of your story translation process with our comprehensive retrieval endpoint. This powerful interface delivers everything you need to utilize your newly translated content, including professionally synthesized audio, formatted dialogue text, and optional transcription data. The system provides these assets in a well-structured format that makes integration into your applications or content management systems straightforward and efficient.

## Accessing Your First Translated Story Results

Let's examine how to retrieve your completed translation 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"
}

def get_translation_result(run_id, target_language, include_transcript=False):
    """
    Retrieves the complete results of a translated story including audio and text assets.

    Parameters:
    - run_id: The ID of the original story that was translated
    - target_language: The language code of the target language used for translation
    - include_transcript: Boolean indicating whether to include the detailed transcript (default: False)

    Returns:
    - A dictionary containing all available translation assets
    """
    try:
        # Build the request URL with optional query parameter
        base_url = f"https://client.camb.ai/apis/translated-story-result/{run_id}/{target_language}"
        if include_transcript:
            url = f"{base_url}?include_transcript=true"
        else:
            url = base_url

        # Request the translation results
        response = requests.get(
            url,
            headers=headers
        )

        # Verify the request was successful
        response.raise_for_status()

        # Parse the result information
        result_data = response.json()

        # Display information about the retrieved assets
        print("Translation assets successfully retrieved!")
        print(f"Complete Story Audio: {result_data.get('audio_url')}")
        print(f"Dialogue Audio: {result_data.get('dialogue_url')}")

        # Check if transcript was requested and is available
        if include_transcript and 'transcript' in result_data:
            print(f"Transcript entries: {len(result_data.get('transcript'))} dialogue items")

        return result_data

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving translation results: {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 = "fr-fr"  # Locale tag. Numeric IDs (e.g. 76) still work but are deprecated.
translation_result = get_translation_result(run_id, target_language, include_transcript=True)
```

## Integrating Translation Results into Your Workflow

Once you've retrieved your translation results, you can integrate them into your content pipeline in numerous ways:

```python [expandable] theme={null}
def process_translation_assets(result_data, run_id):
    """
    Demonstrates common ways to process and utilize the translation assets.

    Parameters:
    - result_data: The dictionary returned from get_translation_result()
    - run_id: The ID of the translation run for file naming
    """
    if not result_data:
        print("No translation data available to process.")
        return

    # Download the complete story audio file
    if 'audio_url' in result_data:
        audio_response = requests.get(result_data['audio_url'])
        if audio_response.status_code == 200:
            # Save the audio file locally
            with open(f"translated_story_{run_id}.flac", 'wb') as f:
                f.write(audio_response.content)
            print("Complete story audio file downloaded successfully.")

    # Download the dialogue audio file
    if 'dialogue_url' in result_data:
        dialogue_response = requests.get(result_data['dialogue_url'])
        if dialogue_response.status_code == 200:
            # Save the dialogue audio file locally
            with open(f"dialogue_audio_{run_id}.flac", 'wb') as f:
                f.write(dialogue_response.content)
            print("Dialogue audio file downloaded successfully.")

    # Process the transcript if available
    if 'transcript' in result_data and result_data['transcript']:
        # Example: Export the transcript as a formatted text file
        with open(f"transcript_{run_id}.txt", 'w', encoding='utf-8') as f:
            for dialogue_item in result_data['transcript']:
                speaker = dialogue_item.get('speaker', 'Narrator')
                text = dialogue_item.get('text', '')
                f.write(f"{speaker}: {text}\n\n")
        print("Transcript exported successfully.")

        # Example: Count dialogue entries by speaker
        speaker_counts = {}
        for dialogue_item in result_data['transcript']:
            speaker = dialogue_item.get('speaker', 'Narrator')
            speaker_counts[speaker] = speaker_counts.get(speaker, 0) + 1

        print("Dialogue distribution by speaker:")
        for speaker, count in speaker_counts.items():
            print(f"  - {speaker}: {count} lines")

# Process the retrieved translation assets
run_id = 12345  # Use the same run_id from earlier
if translation_result:
    process_translation_assets(translation_result, run_id)
```

## Best Practices for Optimal Results

To maximize the effectiveness of your translated story assets, consider these professional recommendations:

1. **Content Deployment Strategy**: Plan how you'll use both the complete story audio and the separated dialogue audio in your applications. The separate dialogue track enables more sophisticated audio mixing and dynamic content presentation.

2. **Transcript Processing**: When working with the transcript data, consider extracting specific dialogue segments for interactive applications or for creating synchronized subtitles for media players.

3. **Asset Archiving**: Implement a structured archiving system for your translated assets that preserves the relationships between audio files and transcript data across multiple languages.

4. **Quality Assessment**: Review a sample of the translated content against the original to ensure the translation maintains the intended tone and meaning of your story.

5. **Error Handling**: Implement robust error handling in your integration code to gracefully manage situations where certain assets might be temporarily unavailable.


# Get Translated Story Status
Source: https://docs.camb.ai/api-reference/endpoint/get-translated-story-status

get /translated-story/{task_id}
Retrieves the current status of a story translation task using the specified `task_id`.

Monitor the progress of your story translation tasks with our dedicated status tracking endpoint. This essential companion to our translation service lets you check on your story's transformation journey in real-time, providing detailed information about which stage of the process your content has reached. By polling this endpoint, you can keep track of your translation progress and detect any issues that might arise during processing.

This endpoint works in conjunction with the [`/translated-story/{run_id}`](create-translated-story) endpoint, which initiates the translation process and provides the `task_id` needed for status checks.

## Understanding the Translation Pipeline

When you request a story translation, your content moves through several processing stages before completion. The status endpoint provides visibility into this journey, allowing you to:

1. Confirm your translation request was successfully received and is being processed
2. Monitor the progress as your story moves through different translation stages
3. Identify when the translation is complete and ready for use
4. Quickly detect and respond to any issues that might occur during processing

Having this level of insight helps you integrate story translations into your applications more effectively, allowing you to provide accurate progress updates to your users and plan subsequent workflows accordingly.

## Implementing Status Checking

Here's how to implement status checking in your application using Python:

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

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

def check_translation_status(task_id):
    """
    Polls the status endpoint to track a story translation task's progress.
    Continues checking until the task reaches a terminal state.

    Parameters:
    - task_id: The unique identifier returned when the translation request was submitted

    Returns:
    - The final status data when a terminal state is reached, or None if an error occurs
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    # Define the possible final states of a translation task
    terminal_states = ["SUCCESS", "ERROR", "TIMEOUT", "PAYMENT_REQUIRED"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/translated-story/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")

            # Handle different status states
            if current_status == "SUCCESS":
                print("Translation completed successfully!")
                print(f"Translated story URL: {status_data.get('story_url')}")
                return status_data

            elif current_status == "ERROR":
                print(f"Translation failed: {status_data.get('error_message')}")
                return status_data

            elif current_status == "TIMEOUT":
                print("Translation process timed out")
                return status_data

            elif current_status == "PAYMENT_REQUIRED":
                print("Additional payment is required to complete this translation")
                return status_data

            elif current_status == "PENDING":
                # Task is still in progress, wait before checking again
                print("Translation in progress...")
                if status_data.get('progress'):
                    print(f"Progress: {status_data.get('progress')}%")
                if status_data.get('current_stage'):
                    print(f"Current stage: {status_data.get('current_stage')}")

                # Wait before next check to avoid excessive requests
                time.sleep(30)  # Poll every 30 seconds

            else:
                # Unexpected status, wait and try again
                print(f"Received status: {current_status}")
                time.sleep(30)

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

    return status_data

# Example usage with a task_id from a previous translation request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_translation_status(task_id)
```

## Best Practices for Status Monitoring

To efficiently track your translation tasks, consider these professional recommendations:

1. **Implement Exponential Backoff**: Start with frequent checks that gradually increase in interval to avoid overloading the API. For example, begin with a 5-second interval, then double it each time until you reach a maximum of 2 minutes between checks.

2. **Handle All Possible States**: Ensure your code properly handles each possible status response, including unexpected values. This makes your integration robust against future API enhancements.

3. **Set Reasonable Timeouts**: For longer stories, translation may take significant time. Implement appropriate overall timeout periods based on the typical length of your content.

4. **Persist Task IDs**: Store task IDs securely in your database so you can resume status checking even if your application restarts or a user returns later.

5. **Provide Meaningful Feedback**: Translate technical status information into user-friendly messages that set appropriate expectations about completion time and next steps.

## Troubleshooting Common Issues

If you encounter difficulties while checking translation status, consider these common solutions:

1. **Invalid Task ID**: Verify the task ID was correctly stored and passed to the status endpoint. Task IDs are case-sensitive and must be used exactly as provided.

2. **Authentication Problems**: Ensure your API key is valid and correctly included in the request headers.

3. **Network Connectivity**: Implement proper error handling for network issues that might interrupt status checking, including automatic retry logic.

4. **Unexpected Terminal States**: If a translation ends with an error status, examine the error message for specific issues that might be addressed in subsequent translation attempts.

By properly integrating status checking into your application, you can create a seamless translation experience that keeps your users informed throughout the entire process, building confidence in your service and ensuring the timely delivery of translated content.


# Get Translation Result
Source: https://docs.camb.ai/api-reference/endpoint/get-translation-run-result

get /translation-result/{run_id}
Retrieves the final translated texts from a completed translation task using the provided `run_id`.

This endpoint delivers the final product of your translation process: the translated texts themselves. Once your translation task has completed successfully and you've received a `run_id`, this endpoint allows you to retrieve the actual translations that were generated. Think of it as the pickup counter where you collect your finished translations after they've been processed.

## How to Use This Endpoint

To retrieve your translated texts, send a `GET` request to this endpoint with the `run_id` you received when your translation task was marked as completed. This `run_id` serves as your claim ticket for the finished translations. The system will respond with an array containing all your translated texts, preserving the same order as your original input.

## Understanding the Response

When you call this endpoint, you'll receive a response that includes your translated content:

* **`texts`**: An array of strings containing the translated output texts. Each item in this array corresponds to one of the original texts you submitted, maintaining the same order. This makes it easy to match translations with their original content.

The structure of the response follows this format:

```json theme={null}
{
  "texts": [
    "Your first translated text",
    "Your second translated text",
    "Your third translated text"
    // ...and so on for all texts in your original request
  ]
}
```

This straightforward response structure makes it simple to integrate translations into your application workflows. You can directly map each translated text to its corresponding original text by using the same array indices.

## Working with Translation Results

There are several common patterns for handling translation results effectively:

### Direct Integration

For immediate use, you can simply extract the texts array and use the translations in your application:

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

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The run_id from your completed translation task
run_id = 12345  # Replace with your actual run ID

# Retrieve the translations
response = requests.get(
    f"https://client.camb.ai/apis/translation-result/{run_id}",
    headers=headers
)

# Check if the request was successful
response.raise_for_status()

# Extract the translations
result_data = response.json()
translations = result_data["texts"]

# Use the translations in your application
for i, translation in enumerate(translations):
    print(f"Translation {i+1}: {translation}")
```

### Parallel Display

For applications that need to show both original and translated text together, you can zip the arrays:

```python [expandable] theme={null}
# Assuming you've stored your original texts
original_texts = [
    "This is the first sentence to translate.",
    "Here is the second one.",
    "And finally, the third sentence."
]

# And you've retrieved the translations as shown above
translations = result_data["texts"]

# Create parallel display
for original, translated in zip(original_texts, translations):
    print("Original: " + original)
    print("Translated: " + translated)
    print("---")
```

### Saving to Database

For longer-term storage, you might want to save the translation results alongside their originals:

```python [expandable] theme={null}
import sqlite3

# Set up database connection (replace with your actual database logic)
conn = sqlite3.connect("translations.db")
cursor = conn.cursor()

# Create table if it doesn't exist
cursor.execute("""
CREATE TABLE IF NOT EXISTS translations (
    id INTEGER PRIMARY KEY,
    original_text TEXT,
    translated_text TEXT,
    source_language INTEGER,
    target_language INTEGER,
    translation_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
""")

# Insert translations into database
for original, translated in zip(original_texts, translations):
    cursor.execute(
        "INSERT INTO translations (original_text, translated_text, source_language, target_language) VALUES (?, ?, ?, ?)",
        (original, translated, 1, 2)  # Replace with your actual language codes
    )

# Commit the changes
conn.commit()
conn.close()
```

## Next Steps

Once you've retrieved your translations, you can:

1. **Display them** to your users
2. **Store them** for future reference
3. **Process them further** with additional NLP tools
4. **Use them in your application logic** to enable multilingual functionality

The simplicity of the response format makes it easy to integrate translations wherever they're needed in your workflow, whether you're building a multilingual website, an educational app, or an international communication tool.

By understanding how to effectively use this endpoint, you can create smoothly functioning multilingual applications that deliver high-quality translations to your users at exactly the right moment in their journey.


# Get Text-to-Speech Task Status
Source: https://docs.camb.ai/api-reference/endpoint/get-tts-result

get /tts/{task_id}
Retrieves the current status of a Text-to-Speech task using the specified `task_id`.

<Card icon="lightbulb" href="create-tts-stream">
  This route is the legacy status check that pairs with deprecated `POST /tts`. For greenfield work, prefer streaming: call `POST /tts-stream` and let audio flow continuously instead of polling here.
</Card>

This endpoint allows you to check on the progress of your Text-to-Speech tasks. When you submit a text-to-speech request, our system begins processing your audio in the background. This endpoint lets you monitor that process from start to finish, keeping you informed about when your audio will be ready.

## How to Use This Endpoint

To check the status of your Text-to-Speech task, simply send a `GET` request to this endpoint with the `task_id` you received when you submitted your original request. The system will respond with detailed information about where your task stands in the processing pipeline.

## Understanding the Response

When you call this endpoint, you'll receive a status response that includes several key pieces of information:

* **Status Code**: Indicates whether the task is still processing, has completed successfully, or encountered an error.
* **Result Information**: For completed tasks, includes the `run_id` needed to download your finished audio file.

### Status Types Explained

Your text-to-speech task will pass through different states as our system processes it. Understanding these status codes will help you properly handle each situation in your application:

| Status             | Description                                                  | Next Step                                                                                                                                |
| :----------------- | :----------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`          | Your audio generation has completed successfully             | Use the `run_id` to download your finished audio                                                                                         |
| `PENDING`          | Your task is currently being processed by our system.        | Continue polling until completion.                                                                                                       |
| `TIMEOUT`          | The processing time exceeded the allowed limit.              | Consider breaking text into smaller segments.                                                                                            |
| `ERROR`            | Something went wrong during processing.                      | Check error details and try submitting again.                                                                                            |
| `PAYMENT_REQUIRED` | Your account requires additional credits for this operation. | Add credits to your account or upgrade your plan by heading to the [billing page](https://studio.camb.ai/billing) and retry the request. |

## Example Code

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

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The task_id you received when submitting your TTS request
task_id = "your_task_id"  # Replace with your actual task ID

# Function to check status and wait for completion
def check_tts_status(task_id):
    print("Checking task status...")

    # Set up polling interval (in seconds)
    polling_interval = 5

    while True:
        # Make the status request
        response = requests.get(
            f"https://client.camb.ai/apis/tts/{task_id}",
            headers=headers
        )

        # Check if the request was successful
        response.raise_for_status()

        # Parse the response
        status_data = response.json()
        print(f"Current status: {status_data['status']}")

        # Use match-case statement to handle different status types
        match status_data['status']:
            case 'SUCCESS':
                print("Task complete!")
                run_id = status_data['run_id']
                print(f"Your audio is ready for download using run_id: {run_id}")
                return run_id

            case 'PENDING':
                print("Task still processing...")
                # Continue to next iteration of while loop

            case 'TIMEOUT':
                print("Task timed out. Consider using shorter text segments.")
                return None

            case 'ERROR':
                print(f"Task failed with error: {status_data.get('error', 'Unknown error')}")
                return None

            case 'PAYMENT_REQUIRED':
                print("Additional credits required to process this request.")
                return None

            case _:  # Default case for any unexpected status values
                print(f"Unexpected status: {status_data['status']}")
                return None

        # If still pending, wait and check again
        if status_data['status'] == 'PENDING':
            print(f"Task still in progress. Checking again in {polling_interval} seconds...")
            time.sleep(polling_interval)
        else:
            # Exit the loop for non-pending statuses after handling them above
            break

# Call the function to monitor your task
run_id = check_tts_status(task_id)

# If task completed successfully, download the audio
if run_id:
    print("Proceed to download the audio file using the run_id!")
```

This polling mechanism gives you flexibility to build applications that can provide real-time feedback to users about their text-to-speech conversions. You can adjust the polling interval based on your specific needs, checking more frequently for time-sensitive applications or less frequently for background tasks.

## Next Steps

Once your task shows a status of `SUCCESS`, you'll receive a `run_id` in the response. This `run_id` is your key to accessing the generated audio. Take this identifier and use it with the [`/tts-result/{run_id}`](get-tts-run-info) endpoint to download your finished audio file and put it to work in your application.


# Get Text-to-Speech Result
Source: https://docs.camb.ai/api-reference/endpoint/get-tts-run-info

get /tts-result/{run_id}
Retrieves the result of a specific Text-to-Speech run using the provided `run_id`.

<Card icon="lightbulb" href="create-tts-stream">
  You’d reach this step after the old async `POST /tts` job completes. That whole pattern is deprecated—new builds should stream speech with `POST /tts-stream` rather than waiting on a finished run and fetching bytes afterward.
</Card>

This endpoint is the final step in your text-to-speech journey, where you retrieve your completed audio file. Once your task has reached a `SUCCESS` status and you've received a `run_id`, you can use this endpoint to access your generated audio and incorporate it into your application.

## How to Use this Endpoint

Retrieving your generated audio is straightforward - simply make a `GET` request to this endpoint with the `run_id` you received when your task completed. The system will respond by providing your audio in your preferred format.

## Understanding Response Options

This endpoint offers flexibility in how you receive your audio content. You can specify your preference using the `output_type` parameter:

| Output Type | Description                                         | Best For                                      |
| :---------- | :-------------------------------------------------- | :-------------------------------------------- |
| `raw_bytes` | Direct streaming of audio data (default option)     | Immediate playback or saving to local storage |
| `file_url`  | JSON response with a URL to download the audio file | When you need to share or store the audio URL |

### Working with Raw Bytes

When using the default `raw_bytes` output type, the endpoint streams the audio data directly to your application. This approach is ideal when you want to:

1. Save the audio file to your local system
2. Process the audio data immediately in your application
3. Play the audio without storing it permanently

<Tip> The streaming approach is particularly efficient for handling larger audio files as it processes the data in manageable chunks rather than loading everything into memory at once.</Tip>

### Working with File URLs

If you prefer to receive a URL pointing to your audio file instead of the raw data, specify `output_type=file_url`. The response will be a JSON object containing a URL where the audio file can be accessed. This approach is beneficial when:

1. You need to share the audio file with others
2. Embed the audio in web content
3. Handle the download process separately from retrieval

<Note> Note that file URLs have an expiration time, so download or use them promptly rather than storing them long-term.</Note>

## Examples

### Saving Audio to a File

Here's how to retrieve and save your generated audio using Python:

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

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The run_id you received when your task completed successfully
run_id = 12345 # Replace with your actual `run_id`

def download_audio_file(run_id, output_filename="generated_speech.flac"):
    """
    Downloads the generated audio file and saves it to the specified location.

    Args:
        run_id: The unique identifier for the completed TTS task
        output_filename: Where to save the audio file (defaults to 'generated_speech.flac')

    Returns:
        bool: True if successful, False otherwise
    """
    print(f"Downloading audio for run_id: {run_id}")

    try:
        # Make the request with streaming enabled
        # The 'stream=True' parameter is crucial for handling the audio data efficiently
        response = requests.get(
            f"https://client.camb.ai/apis/tts-result/{run_id}",
            headers=headers,
            stream=True  # This enables processing the response in chunks
        )

        # Check if the request was successful
        response.raise_for_status()

        # Save the streaming audio to a file
        with open(output_filename, "wb") as audio_file:
            # Process the response in chunks to handle large audio files efficiently
            # The chunk_size determines how much data to process at once
            for chunk in response.iter_content(chunk_size=1024):
                if chunk:  # Filter out keep-alive chunks
                    audio_file.write(chunk)

        print(f"Audio successfully saved to {output_filename}!")
        return True

    except requests.exceptions.RequestException as e:
        print(f"Error downloading audio: {e}")
        return False

# Call the function to download your audio
success = download_audio_file(run_id)

if success:
    print("You can now use this audio file in your application!")
```

### Getting a File URL

If you prefer to receive a URL to the audio file instead:

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

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The run_id you received when your task completed successfully
run_id = 12345  # Replace with your actual `run_id`

# Request a URL instead of raw bytes
params = {
    "output_type": "file_url"
}

# Make the request
response = requests.get(
    f"https://client.camb.ai/apis/tts-result/{run_id}",
    headers=headers,
    params=params
)

# Check if the request was successful
response.raise_for_status()

# Get the URL from the response
url_data = response.json()
audio_url = url_data.get("output_url")

print(f"Your audio is available at: {audio_url}")
print("You can now share this URL or use it to embed the audio in your application.")
```

## Next Steps

Now that you've successfully retrieved your generated audio, you can:

1. Incorporate it into your applications or websites.
2. Process it further with audio editing tools.
3. Combine multiple audio segments into a cohesive narrative.
4. Share it with your users through your platform.

With these capabilities, you have everything you need to build rich, accessible voice experiences into your applications.


# List Dictionaries
Source: https://docs.camb.ai/api-reference/endpoint/list-dictionaries

get /dictionaries
Retrieve all dictionaries available in the workspace associated with your API key.

<Note>Dictionaries can be created and managed either through the [CAMB.AI Studio](https://studio.camb.ai) interface or programmatically via the CAMB.AI APIs.</Note>

## Understanding Terminology Management in Localization

Dictionaries are centralized repositories for terminology management across languages, essential for maintaining consistent terminology in specialized industries and branded materials. CAMB.AI's dictionary system ensures key terms, product names, and industry jargon remain consistent throughout localized content.

Each dictionary in your workspace contains curated terminology pairs defining how specific terms should be translated across target languages, addressing one of localization's key challenges: consistent and accurate specialized vocabulary.

## The Role of Dictionaries in Your Localization Pipeline

Dictionaries enhance your translation workflows by:

1. **Ensuring Terminology Consistency** across all translations regardless of context
2. **Preserving Domain Expertise** by encoding specialized knowledge
3. **Protecting Brand Language** across multiple languages
4. **Streamlining Quality Control** by establishing pre-approved translations

Within CAMB.AI, dictionaries integrate seamlessly with translation workflows, automatically applying terminology rules during content processing.

## Using This Endpoint

To retrieve all dictionaries in your workspace:

```
GET /dictionaries
```

No parameters required. Authentication occurs via your API key.

## Dictionary Management Workflow

Dictionaries can be created, updated, and deleted through either the CAMB.AI Studio interface or directly via REST API calls. Below is an overview of both approaches:

### 1. Via CAMB.AI Studio

1. **Create dictionaries** via Studio, organized by domain or project or by uploading a file that contains your terms and their translations. Refer to this [page](create-dictionary-from-file) for more details.
2. **Add terminology entries** with source terms and approved translations
3. **Retrieve dictionary information** via API or Studio to identify available dictionaries
4. **Apply dictionaries to translations** by referencing their IDs in requests

### 2. Programmatically via API

The CAMB.AI API now exposes endpoints to fully manage dictionaries and their entries. Use these endpoints to build CI/CD pipelines, integrate with custom tools, or automate bulk imports/exports.

## Integrating Dictionaries into Translation Workflows

Apply dictionaries in two primary ways:

### 1. Direct Application in Translation Requests

Specify dictionary IDs when making translation requests:

```json [expandable] theme={null}
{
  "source_language": "en-us", // Locale tag. Numeric IDs (e.g. "1") still work but are deprecated.
  "target_language": "es-es",
  "text": "The patient's vital signs remained stable throughout the procedure.",
  "dictionaries": [42, 63]  // Apply Medical and Legal dictionaries
}
```

### 2. Dictionary Selection Based on Content Type

Select dictionaries programmatically based on content analysis:

```python [expandable] theme={null}
# Pseudo-code example
def translate_with_appropriate_dictionaries(text, source_lang, target_lang):
    # Get available dictionaries
    dictionaries = requests.get(
        "https://client.camb.ai/apis/dictionaries",
        headers={"x-api-key": API_KEY}
    ).json()['dictionaries']

    # Select dictionaries based on content
    selected_dictionary_ids = []
    if contains_medical_terms(text):
        medical_dict = next((d for d in dictionaries if d['name'] == 'Medical Terminology'), None)
        if medical_dict:
            selected_dictionary_ids.append(medical_dict['id'])

    # Translate with selected dictionaries
    return requests.post(
        "https://client.camb.ai/apis/translate",
        json={
            "source_language": source_lang,
            "target_language": target_lang,
            "text": text,
            "dictionaries": selected_dictionary_ids
        },
        headers={"x-api-key": API_KEY}
    ).json()
```

## Best Practices for Dictionary Management

For effective dictionary implementation:

1. **Maintain Regularly**: Establish review cycles and track updates using the `updated_at` timestamp
2. **Apply Strategically**: Use complementary dictionaries and consider application order when terminologies overlap
3. **Govern Collaboratively**: Establish clear ownership and documentation standards for dictionaries

## Related Endpoints

The `/dictionaries` endpoint works in conjunction with several other endpoints in the CAMB.AI API ecosystem:

<CardGroup>
  <Card title="Integration in Translation" icon="languages" href="create-translation">
    Apply dictionaries during translation to ensure consistent terminology across languages. Custom dictionaries help maintain brand voice and technical accuracy.
  </Card>

  <Card title="Usage in Dubbing" icon="video" href="end-to-end-dubbing">
    Use dictionaries when generating dubbed content to ensure specialized terminology is properly voiced in the target language with appropriate pronunciation.
  </Card>

  <Card title="Maintain Consistency in Stories" icon="book-audio" href="create-story">
    Incorporate dictionaries when creating localized stories to maintain consistent terminology and branding elements across narratives in different languages.
  </Card>

  <Card title="Integration with Text-to-Speech" icon="messages-square" href="create-translated-tts">
    Apply dictionaries during the text-to-speech process after translation to ensure specialized terms are properly pronounced in the generated audio output.
  </Card>
</CardGroup>

This interconnected system provides comprehensive support for terminology management throughout your localization workflow.


# List Folders
Source: https://docs.camb.ai/api-reference/endpoint/list-folders

get /folders
The List Folders endpoint provides comprehensive access to your organizational structure within the CAMB.AI workspace, allowing you to retrieve and explore the folders that serve as containers for your audio processing projects. This endpoint becomes increasingly valuable as your workspace grows, offering powerful filtering capabilities to help you navigate complex project hierarchies efficiently.

## Overview

Understanding how folders work in your CAMB.AI workspace is essential for effective project management. Think of folders as digital filing cabinets that organize related tasks, transcriptions, audio files, and other assets. What makes these folders particularly powerful is their universal nature across the entire CAMB.AI platform - every task you create through any API endpoint, whether it's audio separation, transcription, translation, voice synthesis, or any other processing service, can be organized within these same folder structures.

## When to Use This Endpoint

This endpoint serves multiple strategic purposes in your workflow management. During initial application setup, you might retrieve all folders to populate navigation menus or project selection interfaces. As your workspace evolves, you'll frequently use the search functionality to quickly locate specific project containers without manual browsing through extensive folder collections.

The filtering capabilities make this endpoint particularly powerful for building responsive user interfaces. Rather than overwhelming users with hundreds of folders, you can implement progressive loading strategies using the limit parameter, or provide real-time search functionality that helps users find exactly what they're looking for as they type.

## Key Parameters and Their Strategic Applications

### Limit Parameter: Balancing Performance and Completeness

The limit parameter operates as your primary tool for controlling response size and optimizing application performance. When you specify a limit between 1 and 100, you're making a strategic decision about how much data to retrieve in a single request.

### Search Query: Intelligent Folder Discovery

The search functionality transforms how users interact with large folder collections by implementing intelligent partial matching against folder names. This case-insensitive search mechanism understands that users rarely remember exact folder names, instead supporting natural search patterns that match how people actually think about their projects.

## Integration with Broader Workspace Management

The List Folders endpoint works most effectively when integrated with other workspace management features. Folder information often serves as the foundation for task creation workflows across every API endpoint in the CAMB.AI platform, where users select organizational containers before initiating any type of processing operation, whether that's audio separation, transcription, translation, voice synthesis, or other specialized services.

This cross-service integration creates powerful organizational possibilities. Consider a multimedia localization project where you might use audio separation to isolate speaker tracks, transcription services to generate text, translation APIs to convert content into multiple languages, and voice synthesis to create dubbed audio. All of these interconnected tasks can be organized within a single project folder, creating a comprehensive workspace that tells the complete story of your content transformation journey.


# List all Voices
Source: https://docs.camb.ai/api-reference/endpoint/list-voices

get /list-voices
Retrieves a comprehensive list of all available voices, including public voices, shared voices, and custom-created voices. Each voice entry provides detailed attributes such as a unique identifier, voice name, gender, and age, ensuring precise selection and usability.

## Understanding the Voice Ecosystem

This endpoint serves as your gateway to our platform's complete voice library, providing a unified view of all voices available to your account. The returned collection includes three distinct categories of voices:

1. **Public Voices**: These are system-provided voices available to all users. They offer professional-quality speech synthesis across multiple languages, accents, and demographic characteristics.

2. **Custom Voices**: These are unique voices you've created using our voice cloning technology. Custom voices allow you to maintain brand consistency or create specific character voices for your applications.

3. **Shared Voices**: These are voices created by other users who have chosen to make them available on the marketplace. Shared voices expand your options without requiring you to create custom voices from scratch.

By accessing this comprehensive catalog, you can explore the full range of vocal options before deciding which voice best suits your specific use case.

## Using the Endpoint

To retrieve the list of all available voices, simply send a GET request to this endpoint:

```
GET /list-voices
```

No parameters are required for this request. The system will return an array containing detailed information about each available voice.

### Example Response

```json [expandable] theme={null}
{
  "voices": [
    {
      "id": 20305,
      "voice_name": "Alice",
      "gender": 2,
      "age": 65,
      "language": "en-us",
      "transcript": null,
      "description": "A warm, steady voice with a calm tone and a touch of enthusiastic energy, perfect for engaging narration.",
      "is_published": false
    },
    {
      "id": 147320,
      "voice_name": "Gary",
      "gender": 1,
      "age": 35,
      "language": "en-us",
      "transcript": null,
      "description": "A rich, warm voice brimming with emotion and dynamic expression, perfect for dramatic readings that captivate the listener.",
      "is_published": false
    }
    // Additional voice entries...
  ]
}
```

## Voice Selection Best Practices

When working with the voice catalog, consider these approaches to ensure optimal results:

### 1. Filter Locally for Specific Requirements

Since the endpoint returns all available voices, implement client-side filtering to narrow down options based on your specific requirements. Common filtering criteria include:

* **Gender**: Filter based on whether you need male, female, or gender-neutral voices
* **Age range**: Select voices within specific age brackets to match your target audience
* **Language**: Filter for voices that support the languages your content requires
* **Publication status**: Distinguish between private and publicly shared voices

### 2. Implement Voice Previews

Before committing to a specific voice for your project, provide users with the ability to preview different voices using small audio samples. This can be accomplished by:

1. Selecting a subset of voices from the catalog that match your initial criteria
2. Using the text-to-speech endpoint with a short, consistent text sample for each voice
3. Presenting these samples to users or stakeholders to gather feedback

### 3. Consider Voice Consistency

When building applications with extensive voice interaction:

* Maintain consistency by using the same voice throughout a user journey
* Document your selected voice IDs in your application configuration
* Consider creating backup voice selections in case primary choices become unavailable

### 4. Optimize for Different Content Types

Different voice characteristics work better for different types of content:

* **Informational content**: Clear, measured voices with neutral emotional tones
* **Narrative content**: Expressive voices with good dynamic range
* **Instructional content**: Patient, articulate voices with excellent clarity
* **Conversational interfaces**: Natural, friendly voices with appropriate pacing

## Relationship with Other Endpoints

The `/list-voices` endpoint works in conjunction with several other endpoints in the API:

* Use this endpoint to discover available voices
* Use the [`/tts`](create-tts) endpoint to generate speech with your selected voice
* Use the [`/voices/create-custom-voice`](create-custom-voice) endpoint to add new voices to this list
* Use the [`/text-to-voice`](create-text-to-voice) endpoint to generate voices from text descriptions

This interconnected system of endpoints gives you complete control over voice discovery, creation, and utilization across your applications.


# Get Subtitle Task Status
Source: https://docs.camb.ai/api-reference/endpoint/poll-subtitle-result

get /sub/{task_id}
Retrieves the current status of a subtitle task using the specified `task_id`.

Monitor the progress of your subtitle generation in real-time with our status tracking endpoint. This essential companion to our subtitle service lets you check the current state of your media processing job across every requested language. By polling this endpoint, you can track your subtitle task's lifecycle and handle potential processing issues proactively.

<Card icon="info" href="create-subtitle">
  This endpoint works in conjunction with the main `/sub` endpoint, which initiates the subtitle process and provides the `task_id` required for status checks.
</Card>

## Implementing Status Checking

Here's how to implement subtitle status monitoring in your application using Python:

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

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

def check_subtitle_status(task_id):
    """
    Polls the status endpoint to track a subtitle task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    terminal_states = ["SUCCESS", "ERROR"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/sub/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")
            if current_status == "PENDING":
                time.sleep(15)
                continue

            # Handle completed state
            if current_status == "SUCCESS":
                print("Subtitle generation completed successfully!")
                return status_data

            # Handle failed state
            if current_status == "ERROR":
                print(f"Subtitle generation failed: {status_data.get('message')}")
                return status_data

            # Wait before next check to avoid excessive requests
            time.sleep(15)  # Poll every 15 seconds

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

    return None

# Example usage with a task_id from a subtitle request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_subtitle_status(task_id)
```

## Best Practices for Status Monitoring

Ensure efficient tracking of your subtitle tasks with these professional recommendations:

1. **Optimized Polling Intervals**: Start with 15-second intervals and gradually increase to 60 seconds for long media files
2. **Terminal State Handling**: Implement robust error handling for both success and failure scenarios


# Get Transcription Task Status
Source: https://docs.camb.ai/api-reference/endpoint/poll-transcription-result

get /transcribe/{task_id}
Retrieves the current status of a transcription task using the specified `task_id`.

Monitor the progress of your speech-to-text conversion in real-time with our status tracking endpoint. This essential companion to our transcription service lets you check the current state of your audio processing job and retrieve completed transcripts. By polling this endpoint, you can track your transcription task's lifecycle and handle potential processing issues proactively.

<Card icon="info" href="create-transcription">
  This endpoint works in conjunction with the main `/transcribe` endpoint, which initiates the transcription process and provides the `task_id` required for status checks.
</Card>

## Implementing Status Checking

Here's how to implement transcription status monitoring in your application using Python:

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

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

def check_transcription_status(task_id):
    """
    Polls the status endpoint to track a transcription task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    terminal_states = ["SUCCESS", "ERROR"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/transcribe/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")
            if current_status == "PENDING":
                time.sleep(15)
                continue
                
            # Handle completed state
            if current_status == "SUCCESS":
                print("Transcription completed successfully!")
                return status_data

            # Handle failed state
            if current_status == "ERROR":
                print(f"Transcription failed: {status_data.get('message')}")
                return status_data

            # Wait before next check to avoid excessive requests
            time.sleep(15)  # Poll every 15 seconds

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

    return None

# Example usage with a task_id from transcription request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_transcription_status(task_id)
```

## Best Practices for Status Monitoring

Ensure efficient tracking of your transcription tasks with these professional recommendations:

1. **Optimized Polling Intervals**: Start with 15-second intervals and gradually increase to 60 seconds for long audio files
2. **Terminal State Handling**: Implement robust error handling for both success and failure scenarios


# Get Translated Text-to-Speech Status
Source: https://docs.camb.ai/api-reference/endpoint/poll-translated-tts-result

get /translated-tts/{task_id}
Monitors the progress of a Translated Text-to-Speech task using the provided `task_id`.

This endpoint enables you to track the status of your Translated Text-to-Speech requests. When you submit content for translation and audio generation, our system processes both operations as a unified background task. This endpoint provides detailed visibility into this combined process, allowing you to determine when your translated audio will be ready for use.

## Understanding This Endpoint

To monitor your Translated Text-to-Speech task progression, send a `GET` request to this endpoint with the `task_id` you received during your initial submission. The system will return comprehensive information about the current stage of processing for both the translation and audio generation components.

## Response Structure

When querying this endpoint, you'll receive a detailed status response containing several vital pieces of information:

* **Current Status**: Indicates the overall state of your combined translation and audio generation task.
* **Completion Details**: For successfully completed tasks, includes `run_id` necessary to access your translated text and generated audio file.

### Understanding Status Codes

Your translated text-to-speech request will move through various states during processing. Each status code represents a distinct situation that your application should be prepared to handle:

| Status             | Meaning                                                           | Recommended Action                                                                      |
| :----------------- | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `SUCCESS`          | Both translation and audio generation have completed successfully | Retrieve your translated text and audio using the provided IDs                          |
| `PENDING`          | Your request is actively being processed                          | Continue monitoring at reasonable intervals                                             |
| `TIMEOUT`          | Processing exceeded the maximum allowed duration                  | Consider breaking your content into smaller segments                                    |
| `ERROR`            | A system-level issue occurred during processing                   | Check error details for specific information about what went wrong                      |
| `PAYMENT_REQUIRED` | Your account has insufficient credits for this operation          | Visit your account's [billing page](https://studio.camb.ai/billing) to add more credits |

## Implementation Guidelines

For optimal integration of this endpoint into your applications, consider the following practices:

1. **Implement Progressive Polling**: Start with longer intervals between status checks, then decrease the interval as the task progresses through different states.

2. **Set Reasonable Timeouts**: Most translation and synthesis tasks complete within 2-5 minutes, depending on content length and complexity.

## Example Implementation in JavaScript

```javascript [expandable] theme={null}
// Monitoring a Translated Text-to-Speech task with progressive polling
async function monitorTranslatedTTSTask(taskId, apiKey) {
  console.log("Beginning task monitoring...");

  // Initial configuration
  let pollInterval = 10000; // Start with 10-second intervals
  let attempts = 0;
  const maxAttempts = 30;

  while (attempts < maxAttempts) {
    attempts++;

    try {
      // Request current task status
      const response = await fetch(`https://client.camb.ai/apis/translated-tts/${taskId}`, {
        method: 'GET',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey
        }
      });

      if (!response.ok) {
        throw new Error(`HTTP error ${response.status}`);
      }

      const statusData = await response.json();
      console.log(`Status check #${attempts}: ${statusData.status}`);

      // Adjust polling interval based on current stage
      if (statusData.status === 'PENDING') {
        console.log("Task is in progress...");


      // Handle different status types
      switch (statusData.status) {
        case 'SUCCESS':
          console.log("Task completed successfully!");
          console.log(`Run ID: ${statusData.run_id}`);
          return statusData; // Return the complete status object

        case 'PENDING':
          // Still processing, continue to next poll iteration
          break;


        case 'TIMEOUT':
          console.error("Processing time exceeded. Consider shorter content segments.");
          return null;

        case 'ERROR':
          console.error(`Processing error: ${statusData.error_message}`);
          return null;

        case 'PAYMENT_REQUIRED':
          console.error("Insufficient credits. Please add more credits to your account.");
          return null;

        default:
          console.error(`Unexpected status: ${statusData.status}`);
          return null;
      }

      // Wait before next check
      console.log(`Checking again in ${pollInterval/1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, pollInterval));

    } catch (error) {
      console.error(`Error checking status: ${error.message}`);
      return null;
    }
  }

  console.error("Maximum monitoring attempts reached. Task may still be processing.");
  return null;
}
```

## Performance Considerations

When integrating this status-monitoring endpoint into your applications, keep these performance factors in mind:

* **Request Frequency**: Avoid polling more frequently than every 3-5 seconds to prevent unnecessary load on both client and server.
* **Timeout Handling**: For longer texts, processing may take several minutes. Set appropriate client-side timeout expectations.
* **Error Resilience**: Network interruptions shouldn't affect your task processing; the task continues running server-side regardless of status checks.

## Next Steps

Once your task reaches the `SUCCESS` status, you'll receive a `run_id` for accessing both:

1. The generated audio file through the [`/tts-result/{run_id}`](get-tts-run-info) endpoint.
2. The translated text via the [`/translation-result/{run_id}`](get-translation-run-result) endpoint.

Armed with this identifier, you can integrate both the translation and audio components into your application's workflow, creating a seamless multilingual audio experience for your users.


# Get Translation Task Status
Source: https://docs.camb.ai/api-reference/endpoint/poll-translation-result

get /translate/{task_id}
Monitor the progress of your translation tasks with real-time status updates, enabling you to track completion and retrieve translated content when ready.

This endpoint serves as your window into the translation process, allowing you to monitor the status of tasks you've submitted through the `/translate` endpoint. By providing the unique `task_id` you received when initiating a translation, you can check whether your translation is still being processed, has completed successfully, or encountered an issue. When translation is complete, this endpoint also delivers your translated text.

## Understanding the Translation Lifecycle

When you submit a translation request, it goes through several stages before completion. This endpoint keeps you informed about which stage your task has reached:

### Status Types

The `status` field in the response will contain one of these values:

* **`PENDING`**: Your translation is currently in the processing queue or actively being translated. This indicates that everything is working as expected, but the translation is not yet complete. Continue polling at reasonable intervals.

* **`SUCCESS`**: The translation process has completed successfully. When you receive this status, your `run_id` is returned which the identifier that you would use to fetch your translations by using the [`/translation-result/{run_id}`](get-translation-run-result)

* **`ERROR`**: Something went wrong during the translation process. This could be due to invalid input parameters, server issues, or problems with the translation engine. The response may include additional details about the nature of the error.

* **`TIMEOUT`**: The translation task exceeded the maximum allowed processing time. This typically happens with extremely large translation requests or during periods of high system load. Consider breaking your request into smaller batches.

* **`PAYMENT_REQUIRED`**: Your account does not have sufficient credits or permissions to complete this translation. Please check your subscription status or contact support for assistance.

## Recommended Polling Strategy

Asynchronous operations like translation require a thoughtful approach to status checking:

1. **Start with short intervals**: Initially check every 1-2 seconds for very short translations
2. **Use exponential backoff**: Gradually increase the time between checks (e.g., doubling the wait time after each check)
3. **Set a maximum interval**: Don't let the wait time grow beyond 10-15 seconds
4. **Implement a timeout**: Establish a maximum total wait time for your application

This approach balances responsiveness with server efficiency, ensuring you get your translations promptly without overloading the system with unnecessary requests.

## Example: Monitoring Translation Progress

Here's how you might implement status checking for a translation task:

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

def check_translation_status(task_id, api_key, base_url="https://client.camb.ai/apis"):
    """
    Check the status of a translation task with exponential backoff.

    Parameters:
    -----------
    task_id : str
        The unique identifier for the translation task
    api_key : str
        Your API authentication key
    base_url : str
        The base URL for the API endpoints

    Returns:
    --------
    dict
        The final response containing translations if successful
    """
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }

    # Initial polling parameters
    wait_time = 1  # Start with 1 second
    max_wait_time = 10  # Maximum seconds between polls
    max_total_wait = 300  # Maximum total seconds to wait (5 minutes)
    start_time = time.time()

    while (time.time() - start_time) < max_total_wait:
        # Get current status
        response = requests.get(
            f"{base_url}/translate/{task_id}",
            headers=headers
        )

        # Check for API errors
        if response.status_code != 200:
            print(f"Error checking status: HTTP {response.status_code}")
            return None

        status_data = response.json()
        current_status = status_data.get("status")

        # Handle each possible status
        if current_status == "SUCCESS":
            print("✅ Translation completed successfully!")
            return status_data  # Contains translations

        elif current_status == "PENDING":
            elapsed = round(time.time() - start_time)
            print(f"⏳ Translation in progress... ({elapsed}s elapsed)")

        elif current_status == "ERROR":
            print("❌ Translation failed with an error.")
            return status_data  # May contain error details

        elif current_status == "TIMEOUT":
            print("⏰ Translation timed out on the server.")
            return status_data

        elif current_status == "PAYMENT_REQUIRED":
            print("💰 Additional payment or credits required.")
            return status_data

        # Wait before checking again, with exponential backoff
        time.sleep(wait_time)
        wait_time = min(wait_time * 2, max_wait_time)  # Double wait time but cap it

    # If we've reached here, we've exceeded our maximum wait time
    print("🛑 Client-side timeout: Maximum wait time exceeded")
    return None

# Example usage:
api_key = "your-api-key"  # Replace with your actual API key
task_id = "your_task_id"  # Replace with your actual task ID

result = check_translation_status(task_id, api_key)

if result and result.get("status") == "SUCCESS":
    print(f"Use the Run ID: {result.get('run_id')} to fetch your translated result.")
```

This function demonstrates a robust implementation of status polling with several key features:

1. **Exponential backoff**: The wait time between requests starts small and gradually increases, which is efficient for both short and long-running tasks
2. **Multiple status handling**: Each possible status value is handled appropriately
3. **Error reporting**: Meaningful error messages help diagnose issues
4. **Progress tracking**: The elapsed time is displayed to keep users informed
5. **Timeout protection**: Both client-side and server-side timeouts are accounted for

By implementing a similar approach in your application, you can create a responsive user experience that keeps users informed about translation progress while efficiently managing system resources.

## When to Stop Polling

You should stop polling when you receive one of these definitive statuses:

* **`SUCCESS`**: You've received your translations
* **`ERROR`**: The task failed and won't recover
* **`TIMEOUT`**: The server timed out the request
* **`PAYMENT_REQUIRED`**: Payment issues need to be resolved

Only the **`PENDING`** status indicates that you should continue polling.

With this endpoint, you gain visibility into the translation process, allowing your application to respond appropriately based on real-time status information and retrieve completed translations as soon as they're available.


# Create an SRT Flow
Source: https://docs.camb.ai/api-reference/endpoint/streaming/create-flow

post /flows
Create a stream flow: a standing SRT endpoint you can use as the source or a target of your streams.

## Overview

A **flow** is a standing SRT endpoint hosted by Camb.ai, independent of any
stream. Create one once, and use its URLs as the source or a target of any
number of streams, with no need to expose your own SRT infrastructure.

Flows come in two modes:

<Columns>
  <Card title="Listener" icon="satellite-dish">
    Camb.ai hosts an SRT endpoint your encoder **pushes to**. You get one or
    two `push_urls` (primary/backup) and a `play_url` anyone with the key can
    pull from.
  </Card>

  <Card title="Caller" icon="phone-arrow-up-right">
    Camb.ai **pulls from your** SRT endpoint (`primary_url`) and re-serves it
    on a stable `play_url`, with optional failover to a `backup_url`.
  </Card>
</Columns>

## Using a flow with streams

The returned `play_url` is a normal SRT URL:

* **As a stream source** - set it as `source_stream.url` when
  [creating a stream](create-new-stream). Your encoder pushes to the flow's
  `push_urls`; the stream ingests from the flow.
* **As a stream target** - set it as a `target_streams[].url` with
  `"type": 1` to deliver your processed output to the flow, then distribute
  the flow's `play_url` to viewers or downstream systems.

<Tip>
  Set a `passphrase` (10–79 characters) to encrypt the flow's endpoint. It is
  embedded in the returned URLs and required to connect. To pull from an
  upstream that is itself encrypted (caller mode), append its passphrase to
  `primary_url` as a query parameter: `srt://host:port?passphrase=...`.
</Tip>

## Example: listener flow for a stadium encoder

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/flows" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "label": "stadium-encoder",
      "mode": "listener",
      "failover": true
    }'
  ```

  ```python Python theme={null}
  import requests

  payload = {
      "label": "stadium-encoder",
      "mode": "listener",
      "failover": True,
  }

  response = requests.post(
      "https://client.camb.ai/apis/flows",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )

  response.raise_for_status()
  flow = response.json()
  print(flow["push_urls"])  # give these to your encoder
  print(flow["play_url"])   # use this as source_stream.url
  ```
</CodeGroup>

The response contains everything needed to use the flow:

<CodeGroup>
  ```json Response theme={null}
  {
    "id": 42,
    "label": "stadium-encoder",
    "mode": "listener",
    "failover": true,
    "active": true,
    "team_id": 7,
    "key": "k3yk3yk3yk3yk3yk3yk3yk3yk",
    "play_url": "srt://live.camb.ai:20121?streamid=play/42/k3yk3yk3yk3yk3yk3yk3yk3yk",
    "push_urls": [
      {
        "role": "primary",
        "url": "srt://live.camb.ai:20121?streamid=publish/42-primary/k3yk3yk3yk3yk3yk3yk3yk3yk"
      },
      {
        "role": "backup",
        "url": "srt://live.camb.ai:20121?streamid=publish/42-backup/k3yk3yk3yk3yk3yk3yk3yk3yk"
      }
    ],
    "passphrase": null
  }
  ```
</CodeGroup>

## Validation rules

* `label` must be unique within your team.
* `caller` mode requires `primary_url`; `listener` mode must not set URLs.
* `backup_url` requires `failover: true` (and is required for caller flows
  with failover).

## Errors

* `403` - Your subscription does not include streaming.
* `422` - Validation error (see the rules above).

## Related endpoints

* [List SRT Flows](list-flows)
* [Get an SRT Flow](get-flow)
* [Update an SRT Flow](update-flow)
* [Delete an SRT Flow](delete-flow)


# Create a Stream
Source: https://docs.camb.ai/api-reference/endpoint/streaming/create-new-stream

post /stream
Create a live stream that ingests a source feed, processes it with AI in real time, and publishes dubbed, translated, or transcribed outputs.

## Overview

This endpoint is the entry point of the streaming lifecycle. It takes a source
feed, one or more processing pipelines, and one or more output destinations,
and returns a `stream_id` you use for every other lifecycle operation.

<Info>
  **Supported source protocols:** SRT is supported today. RTMP and HLS ingest
  are coming soon.
</Info>

## How a stream fits together

The request body is built from four blocks that reference each other by `id`:

<Steps>
  <Step title="Source">
    `source_stream` - the live feed to ingest, e.g. `srt://ingest.example.com:9000`.
    You can also use the play URL of a [stream flow](create-flow) here.
  </Step>

  <Step title="Audio selections">
    `audio_selections` - name the audio track(s) of the source you want to
    process and declare their spoken language. Use
    [Probe a Source Stream](probe-stream) to discover tracks, or start with
    `$first_audio`.
  </Step>

  <Step title="Profiles and pipelines">
    `processing_profiles` define *how* audio is processed (demixing,
    transcription, translation, revoicing, each `none`, `best_model`, or
    `fast_model`). `pipelines` connect an audio selection to a profile and
    declare the output assets to produce, each with a language.
  </Step>

  <Step title="Targets">
    `target_streams` - where the processed output goes. At least one is
    required. Push to your own endpoint (SRT/RTMP), or let Camb.ai host the
    output for you (SRT listener or HLS recording).
  </Step>
</Steps>

## Before you start

Collect the IDs the payload references:

* **Language IDs** - [`GET /source-languages`](/api-reference/endpoint/get-source-languages) and
  [`GET /target-languages`](/api-reference/endpoint/get-target-languages). Languages are numeric IDs;
  for example `1` is English (US) and `54` is Spanish (Spain).

<Tip>
  The system handles multilingual inputs. If the source audio mixes several
  languages, set `source_language` to the main one spoken; the others are
  handled automatically.
</Tip>

* **Voice IDs** (optional) - [`GET /list-voices`](/api-reference/endpoint/list-voices). If you pass
  voice IDs, dubbed speech uses those fixed voices. If you leave them out,
  voices are cloned from the speakers in the source audio.
* **Dictionary IDs** (optional) - [`GET /dictionaries`](/api-reference/endpoint/list-dictionaries) for
  custom terminology, up to 5.

<Tip>
  When passing fixed voice IDs, include voices of different genders and tones.
  The system matches each speaker in the source audio to the most suitable
  voice from your list, so a varied list produces better matches.
</Tip>

<Note>
  A pipeline that produces an `audio` output must also declare a `subtitle`
  output in the same pipeline; the transcript drives the dubbing. You do not
  have to route the subtitle asset to a target.
</Note>

## Example: dub a football match into Spanish

The example ingests the SRT feed of a football match, dubs the English
commentary (`1`) into Spanish (`54`), and pushes the dubbed program (original
video plus Spanish commentary) to an SRT destination of your own.

<Tip>
  Fastest way to test: copy this payload, adjust it to your setup, and paste
  it into the **Try it** body - the form fields fill in automatically from the
  pasted JSON. Then press Send.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/stream" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Saturday Match Live Dub",
      "description": "Football match commentary dubbed from English into Spanish",
      "end_time": "2026-08-01T21:45:00Z",
      "timezone": "UTC",
      "voices": [12345],
      "source_stream": {
        "id": "match-feed",
        "url": "srt://ingest.example.com:9000",
        "latency": 2000,
        "category": 2
      },
      "audio_selections": [
        {
          "id": "commentary",
          "source": "$first_audio",
          "source_language": 1
        }
      ],
      "processing_profiles": [
        {
          "id": "dubbing",
          "demixing": "best_model",
          "transcribing": "best_model",
          "translating": "best_model",
          "revoicing": "best_model"
        }
      ],
      "pipelines": [
        {
          "id": "spanish",
          "profile": "dubbing",
          "audio_selection": "commentary",
          "outputs": [
            { "id": "es-audio", "kind": "audio", "language": 54 },
            { "id": "es-subtitle", "kind": "subtitle", "language": 54 }
          ]
        }
      ],
      "target_streams": [
        {
          "id": "spanish-out",
          "url": "srt://delivery.example.com:9100",
          "type": 1,
          "inputs": [
            { "asset_id": "es-audio" },
            { "passthrough_selector": "v:0" }
          ]
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  payload = {
      "name": "Saturday Match Live Dub",
      "description": "Football match commentary dubbed from English into Spanish",
      "end_time": "2026-08-01T21:45:00Z",  # streams always need an end time
      "timezone": "UTC",
      "voices": [12345],  # from GET /list-voices
      "source_stream": {
          "id": "match-feed",
          "url": "srt://ingest.example.com:9000",
          "latency": 2000,  # recommended SRT latency (ms)
          "category": 2,  # sports and entertainment
      },
      "audio_selections": [
          {
              "id": "commentary",
              "source": "$first_audio",
              "source_language": 1,  # English (US)
          }
      ],
      "processing_profiles": [
          {
              "id": "dubbing",
              "demixing": "best_model",
              "transcribing": "best_model",
              "translating": "best_model",
              "revoicing": "best_model",
          }
      ],
      "pipelines": [
          {
              "id": "spanish",
              "profile": "dubbing",
              "audio_selection": "commentary",
              "outputs": [
                  {"id": "es-audio", "kind": "audio", "language": 54},  # Spanish (Spain)
                  {"id": "es-subtitle", "kind": "subtitle", "language": 54},
              ],
          }
      ],
      "target_streams": [
          {
              "id": "spanish-out",
              "url": "srt://delivery.example.com:9100",
              "type": 1,  # SRT caller: Camb.ai pushes to your endpoint
              "inputs": [
                  {"asset_id": "es-audio"},
                  {"passthrough_selector": "v:0"},  # forward the original video
              ],
          }
      ],
  }

  response = requests.post(
      "https://client.camb.ai/apis/stream",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )

  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

A successful request returns the stream ID and the output URLs:

<CodeGroup>
  ```json Response theme={null}
  {
    "stream_id": 1234,
    "task_id": "b8f2f1f0-3c6a-4f5e-9b2a-1c2d3e4f5a6b",
    "stream_url_for_languages": [
      {
        "languages": [54],
        "url": "srt://delivery.example.com:9100"
      }
    ]
  }
  ```
</CodeGroup>

## Scheduling

Every stream needs an `end_time` (with its `timezone`); the stream stops
automatically at that moment. `start_time` is optional: omit it to start
right away, or set it to schedule the stream for later.

```json theme={null}
{
  "start_time": "2026-08-01T19:30:00Z",
  "end_time": "2026-08-01T21:45:00Z",
  "timezone": "UTC"
}
```

Scheduling rules:

* Times are ISO 8601 with a UTC offset, and the `timezone` (IANA name) must
  match their offset.
* `start_time` cannot be in the past and at most 7 days in the future.
* `end_time` must be at least 15 minutes after the start.

To end a stream before its `end_time`, [delete it](delete-stream). To extend
or shorten a running stream, [update](update-stream) its `end_time`.

## Choosing targets

| You want to...                         | Use                                                    |
| -------------------------------------- | ------------------------------------------------------ |
| Push to your own SRT endpoint          | `"type": 1` with your `url`                            |
| Push to an RTMP ingest (e.g. YouTube)  | `"type": 2` (or `4` for YouTube) with the ingest `url` |
| Let viewers pull from Camb.ai over SRT | `"type": 6`, omit `url`; the play URL is returned      |
| Get a Camb.ai-hosted HLS recording     | `"type": 3`, omit `url`; the playback URL is returned  |

Each target lists `inputs`: pipeline outputs by `asset_id`, and untouched
source tracks by `passthrough_selector` (e.g. `v:0` for the video). Source
tracks that are not replaced by a pipeline output are forwarded automatically
unless you set `passthrough_policy` to `none`.

## Errors

* `402` - Insufficient credits for the requested configuration.
* `422` - Validation error: missing required blocks, an `id` reference that
  doesn't resolve (e.g. a pipeline referencing an unknown profile), invalid
  language IDs, or malformed URLs.

## Related endpoints

* [Probe a Source Stream](probe-stream) - inspect the source before creating
* [Get Stream Status](get-stream-status) - monitor state and output URLs
* [Update a Stream](update-stream) - reschedule, reconfigure, or toggle dubbing live
* [Delete a Stream](delete-stream) - terminate a running or scheduled stream
* [Create an SRT Flow](create-flow) - standing SRT endpoints usable as source or target


# Create a Stream Template
Source: https://docs.camb.ai/api-reference/endpoint/streaming/create-template

post /stream/templates/
Save a created stream's configuration as a named template.

## Overview

Saves an existing stream's configuration under a name, so the same setup can
be recreated later without rebuilding the payload. The template stores no
configuration of its own: applying it with
[Use a Stream Template](use-template) replays the referenced stream's
original creation payload.

The `stream_id` must belong to a stream created in your workspace. Template
names are unique per workspace, and each workspace can hold at most 20
templates; a duplicate name or a full workspace returns `409`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/stream/templates/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "matchday-dubbing", "stream_id": 4821}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://client.camb.ai/apis/stream/templates/",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={"name": "matchday-dubbing", "stream_id": 4821},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12,
    "name": "matchday-dubbing",
    "stream_id": 4821
  }
  ```
</ResponseExample>

## Related endpoints

* [List Stream Templates](list-templates)
* [Use a Stream Template](use-template)
* [Delete a Stream Template](delete-template)


# Delete an SRT Flow
Source: https://docs.camb.ai/api-reference/endpoint/streaming/delete-flow

delete /flows/{flow_id}
Delete a stream flow and shut down its SRT endpoint.

## Overview

Deletes a flow and shuts down its SRT endpoint. Its URLs stop working
immediately.

<Warning>
  Deletion is permanent, and a new flow gets new URLs and a new key. Make sure
  no encoders or streams are still using this flow before deleting it.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://client.camb.ai/apis/flows/42" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://client.camb.ai/apis/flows/42",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  { "status": "deleted", "id": 42 }
  ```
</ResponseExample>

## Errors

* `404` - No flow with this ID belongs to your team.

## Related endpoints

* [Create an SRT Flow](create-flow)
* [List SRT Flows](list-flows)


# Delete a Stream
Source: https://docs.camb.ai/api-reference/endpoint/streaming/delete-stream

delete /stream/{stream_id}
Delete a stream, stopping it if it is live.

## Overview

Deletes a stream. If the stream is live, processing stops and outputs are
finalised; a scheduled stream is cancelled. The stream's status becomes `4`
(ended).

Deleting does not erase the stream's history: you can still call
[`GET /stream/{stream_id}`](get-stream-status) afterwards to read its final
state. Streams stop on their own at their `end_time`; use this endpoint to end
one earlier.

<Note>
  A deleted stream cannot be restarted. To run the same setup again, create a
  new stream with the same payload, or use [flows](create-flow) as your
  endpoints so encoders and viewers keep the same URLs across runs.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://client.camb.ai/apis/stream/1234" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://client.camb.ai/apis/stream/1234",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

## Errors

* `404` - No stream with this ID belongs to your team.
* `422` - Invalid `stream_id`.

## Related endpoints

* [Create a Stream](create-new-stream)
* [Get Stream Status](get-stream-status)
* [Update a Stream](update-stream)


# Delete a Stream Template
Source: https://docs.camb.ai/api-reference/endpoint/streaming/delete-template

delete /stream/templates/{template_id}
Delete a stream template from your workspace.

## Overview

Removes a template from your workspace. Only the template entry is deleted:
the stream it was saved from, and any streams created from the template, are
unaffected.

Each workspace can hold at most 20 templates. Once the limit is reached,
saving a new template requires deleting one first.

Templates are scoped to your workspace: requesting a template that belongs to
another workspace returns `404`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://client.camb.ai/apis/stream/templates/12" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
      "https://client.camb.ai/apis/stream/templates/12",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": 12
  }
  ```
</ResponseExample>

## Related endpoints

* [List Stream Templates](list-templates)
* [Use a Stream Template](use-template)


# Get an SRT Flow
Source: https://docs.camb.ai/api-reference/endpoint/streaming/get-flow

get /flows/{flow_id}
Retrieve a stream flow, including its play and push URLs.

## Overview

Returns the full details of one flow, including its `play_url`, `push_urls`,
and access `key`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/flows/42" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://client.camb.ai/apis/flows/42",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

## Errors

* `404` - No flow with this ID belongs to your team.

## Related endpoints

* [Create an SRT Flow](create-flow)
* [Update an SRT Flow](update-flow)
* [Delete an SRT Flow](delete-flow)


# Get Stream Status
Source: https://docs.camb.ai/api-reference/endpoint/streaming/get-stream-status

get /stream/{stream_id}
Retrieve the current status of a stream, including source details and the state and URLs of every output.

## Overview

Returns the current state of a stream. The response shape is the same whether
the stream is scheduled, live, or finished, which makes it suitable for
dashboards and polling loops.

Use it to:

* Track the stream through its lifecycle (`scheduled` → `setting up` →
  `started` → `ended`).
* Read the playback URLs of Camb.ai-hosted outputs (SRT listener, HLS
  recording).
* Check per-target delivery state and surface errors.

<Tip>
  When polling, a cadence of 5–15 seconds is plenty. Back off once the stream
  reaches a terminal status (`4`, `5`, or `6`).
</Tip>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/stream/1234" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://client.camb.ai/apis/stream/1234",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "stream_id": 1234,
    "status": 3,
    "source": {
      "type": 1,
      "playback_url": null
    },
    "targets": [
      {
        "id": "spanish-out",
        "type": 1,
        "state": "active",
        "playback_url": null,
        "destination_url": "srt://delivery.example.com:9100"
      }
    ],
    "scheduled_at": "2026-08-01T10:00:00Z",
    "started_at": "2026-08-01T10:00:05Z",
    "stopped_at": null,
    "task_id": "b8f2f1f0-3c6a-4f5e-9b2a-1c2d3e4f5a6b",
    "error": null
  }
  ```
</ResponseExample>

## Reading the response

* `status` - the stream lifecycle status: `1` scheduled, `2` setting up, `3`
  started, `4` ended, `5` interrupted, `6` error.
* `targets[].state` - each output progresses `scheduled` → `active` →
  `completed`, or `failed` on error.
* `targets[].playback_url` - set for Camb.ai-hosted outputs; this is where
  you or your viewers connect.
* `targets[].destination_url` - set for push outputs; the endpoint Camb.ai is
  delivering to.
* `error` - populated when `status` is `6`.

## Errors

* `404` - No stream with this ID belongs to your team.
* `422` - Invalid `stream_id`.

## Related endpoints

* [Create a Stream](create-new-stream)
* [Update a Stream](update-stream)
* [Delete a Stream](delete-stream)


# List SRT Flows
Source: https://docs.camb.ai/api-reference/endpoint/streaming/list-flows

get /flows
List all stream flows belonging to your team.

## Overview

Returns a summary of every flow owned by your team. Use
[Get an SRT Flow](get-flow) to retrieve a flow's URLs and key.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/flows" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://client.camb.ai/apis/flows",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": 42,
      "label": "stadium-encoder",
      "mode": "listener",
      "failover": true,
      "active": true,
      "team_id": 7
    }
  ]
  ```
</ResponseExample>

## Related endpoints

* [Create an SRT Flow](create-flow)
* [Get an SRT Flow](get-flow)


# List Stream Templates
Source: https://docs.camb.ai/api-reference/endpoint/streaming/list-templates

get /stream/templates/
List the stream templates saved in your workspace.

## Overview

A stream template is a named snapshot of a previously created stream's
configuration, saved from the stream builder in the portal or with
[Create a Stream Template](create-template). Templates let you recreate a
proven setup, for example your matchday dubbing configuration, without
rebuilding the payload each time.

This endpoint returns every template saved in your workspace. Use
[Use a Stream Template](use-template) to retrieve a template's full payload.

Each workspace can hold at most 20 templates. When the limit is reached,
[delete a template](delete-template) before saving a new one.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/stream/templates/" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://client.camb.ai/apis/stream/templates/",
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "templates": [
      {
        "id": 12,
        "name": "matchday-dubbing",
        "stream_id": 4821
      },
      {
        "id": 15,
        "name": "press-conference",
        "stream_id": 5010
      }
    ]
  }
  ```
</ResponseExample>

## Related endpoints

* [Create a Stream Template](create-template)
* [Use a Stream Template](use-template)
* [Create Stream](create-new-stream)


# Live Streaming Overview
Source: https://docs.camb.ai/api-reference/endpoint/streaming/overview

Dub, translate, and transcribe live streams in real time with the Camb.ai Streaming API.

The Streaming API takes a live feed, processes it with Camb.ai's AI pipeline
in real time, and publishes the results to the destinations you choose: dub a
football match's commentary into Spanish as it happens, push the dubbed feed
to YouTube, and
keep an HLS recording, all from one API call.

<Info>
  **Supported source protocols:** SRT is supported today. RTMP and HLS ingest
  are coming soon.
</Info>

## The streaming lifecycle

<Steps>
  <Step title="Probe (optional)">
    [`POST /stream/probe/`](probe-stream) - inspect the source and discover
    its video, audio, and data tracks.
  </Step>

  <Step title="Create">
    [`POST /stream`](create-new-stream) - configure source, pipelines, and
    targets. You get back a `stream_id` and output URLs.
  </Step>

  <Step title="Monitor">
    [`GET /stream/{stream_id}`](get-stream-status) - poll the stream status
    and read the state and playback URLs of each output.
  </Step>

  <Step title="Adjust">
    [`PATCH /stream/{stream_id}`](update-stream) - reschedule, reconfigure,
    or apply live adjustments such as turning dubbing on and off.
  </Step>

  <Step title="End">
    [`DELETE /stream/{stream_id}`](delete-stream) - stop the stream, or let
    it end automatically at its `end_time`.
  </Step>
</Steps>

## Core concepts

A stream's configuration is a small graph of blocks that reference each other
by `id`:

| Block                 | What it does                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `source_stream`       | The live feed to ingest (an SRT URL, or a [flow](create-flow)'s play URL).                                          |
| `audio_selections`    | Names the source audio track(s) to process and their spoken language.                                               |
| `processing_profiles` | How audio is processed: demixing, transcribing, translating, revoicing, each `none`, `best_model`, or `fast_model`. |
| `pipelines`           | Connect one audio selection to one profile and declare output assets (dubbed audio, subtitles) per language.        |
| `target_streams`      | Where outputs go: your SRT/RTMP endpoints, YouTube, or Camb.ai-hosted SRT/HLS outputs.                              |

Language and voice choices are numeric IDs from the platform's catalog
endpoints: [`/source-languages`](/api-reference/endpoint/get-source-languages),
[`/target-languages`](/api-reference/endpoint/get-target-languages), and
[`/list-voices`](/api-reference/endpoint/list-voices).

## Stream flows

[Flows](create-flow) are standing SRT endpoints hosted by Camb.ai,
independent of any single stream. Use a flow when you want a stable ingest
point for your encoder (**listener** mode) or want Camb.ai to pull from your
infrastructure and re-serve it (**caller** mode), then plug the flow's URL
into any stream as its source or target.

## Authentication

Every request needs your API key in the `x-api-key` header. You can find your
API key(s) in the API section of the Camb.ai studio.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" "https://client.camb.ai/apis/stream/1234"
```

## Endpoints

| Endpoint                                       | Purpose                                 |
| ---------------------------------------------- | --------------------------------------- |
| [`POST /stream`](create-new-stream)            | Create a stream                         |
| [`GET /stream/{stream_id}`](get-stream-status) | Get stream status                       |
| [`PATCH /stream/{stream_id}`](update-stream)   | Update a stream / toggle dubbing        |
| [`DELETE /stream/{stream_id}`](delete-stream)  | Terminate a running or scheduled stream |
| [`POST /stream/probe/`](probe-stream)          | Inspect a source                        |
| [`POST /flows`](create-flow)                   | Create an SRT flow                      |
| [`GET /flows`](list-flows)                     | List SRT flows                          |
| [`GET /flows/{flow_id}`](get-flow)             | Get an SRT flow                         |
| [`PATCH /flows/{flow_id}`](update-flow)        | Update an SRT flow                      |
| [`DELETE /flows/{flow_id}`](delete-flow)       | Delete an SRT flow                      |


# Probe a Source Stream
Source: https://docs.camb.ai/api-reference/endpoint/streaming/probe-stream

post /stream/probe/
Inspect a source stream and list its video, audio, and data tracks before creating a live stream.

## Overview

A preflight check that connects to a source URL and reports the tracks it
carries, without creating anything. Use it to:

* Verify the source is reachable before scheduling a stream.
* Find the right audio track for `audio_selections[].source`.
* Check for data tracks such as SCTE-35 ad markers.

<Info>
  SRT sources are supported today; RTMP and HLS ingest are coming soon. Note
  the trailing slash in the path: `POST /stream/probe/`.
</Info>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/stream/probe/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "srt://ingest.example.com:9000",
      "passphrase": "my-secret-passphrase",
      "stream_id": "live/primary"
    }'
  ```

  ```python Python theme={null}
  import requests

  payload = {
      "url": "srt://ingest.example.com:9000",
      # Only needed if the source is encrypted / requires a streamid:
      "passphrase": "my-secret-passphrase",
      "stream_id": "live/primary",
  }

  response = requests.post(
      "https://client.camb.ai/apis/stream/probe/",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )

  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

A reachable source returns its tracks:

<CodeGroup>
  ```json Response theme={null}
  {
    "video_streams": [
      {
        "index": 0,
        "codec_name": "h264",
        "width": 1920,
        "height": 1080,
        "frame_rate": "25/1"
      }
    ],
    "audio_streams": [
      {
        "index": 1,
        "codec_name": "aac",
        "sample_rate": 48000,
        "channels": 2,
        "channel_layout": "stereo",
        "tags": { "language": "eng" }
      }
    ],
    "data_streams": []
  }
  ```
</CodeGroup>

## From probe to create

Pick the audio track to process and reference it in your create payload's
`audio_selections`. Selectors count within a track type, so the first audio
track is `a:0` regardless of its overall index:

```json theme={null}
{
  "audio_selections": [
    { "id": "commentary", "source": "a:0", "source_language": 1 }
  ]
}
```

If you are unsure which track carries speech, start with `$first_audio`.

## Errors

* `422` - Validation error, or the source could not be reached.

## Related endpoints

* [Create a Stream](create-new-stream)
* [Get Stream Status](get-stream-status)


# Update an SRT Flow
Source: https://docs.camb.ai/api-reference/endpoint/streaming/update-flow

patch /flows/{flow_id}
Rename a stream flow or bring its endpoint online or offline.

## Overview

Updates a flow. Only `label` and `active` can be changed. To change a flow's
mode, URLs, or failover setup, delete it and create a new one.

Setting `active` controls whether the flow's SRT endpoint is online. Inactive
flows keep their URLs and key, so you can take an endpoint offline between
events without reconfiguring your encoders.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://client.camb.ai/apis/flows/42" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "active": false }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      "https://client.camb.ai/apis/flows/42",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={"active": False},
  )

  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

## Errors

* `404` - No flow with this ID belongs to your team.
* `422` - Validation error (e.g. a `label` already used by another of your team's flows).

## Related endpoints

* [Create an SRT Flow](create-flow)
* [Get an SRT Flow](get-flow)
* [Delete an SRT Flow](delete-flow)


# Update a Stream
Source: https://docs.camb.ai/api-reference/endpoint/streaming/update-stream

patch /stream/{stream_id}
Update a stream's configuration or apply live adjustments, including turning dubbing on and off, without recreating it.

## Overview

Partially updates an existing stream. Send only the fields you want to change.
Updates are allowed while the stream is scheduled, setting up, or started.

There are two kinds of changes:

* **Configuration updates** - rescheduling, replacing voices or dictionaries,
  and adding or modifying audio selections, profiles, pipelines, and targets.
  These are persisted into the stream configuration.
* **Live pipeline patches** (`pipeline_patches`) - runtime-only adjustments to
  a running stream: turn dubbing on or off, adjust the dubbing mix, or nudge
  audio/video sync. These take effect within seconds and are not persisted.

<Note>
  List fields that carry `id`s (`audio_selections`, `processing_profiles`,
  `encoding_profiles`, `pipelines`, `target_streams`) are **merged by `id`**:
  entries you send are added or replaced as a whole, and existing entries are
  never removed.
</Note>

<Tip>
  You can paste a full JSON body into the **Try it** form and the fields fill
  in automatically - copy any example below as a starting point.
</Tip>

## Turning dubbing on and off

Set `dubbing_enabled` on a pipeline patch. With `false`, dubbing pauses and
the original audio passes through; with `true`, dubbing resumes.

<CodeGroup>
  ```bash cURL (pause dubbing) theme={null}
  curl -X PATCH "https://client.camb.ai/apis/stream/1234" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "pipeline_patches": [
        { "pipeline_id": "spanish", "dubbing_enabled": false }
      ]
    }'
  ```

  ```python Python (reschedule) theme={null}
  import requests

  payload = {
      "start_time": "2026-08-01T11:00:00Z",
      "end_time": "2026-08-01T13:00:00Z",
      "timezone": "UTC",
  }

  response = requests.patch(
      "https://client.camb.ai/apis/stream/1234",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )

  response.raise_for_status()
  print(response.json())
  ```

  ```python Python (adjust the live mix) theme={null}
  import requests

  payload = {
      "pipeline_patches": [
          {
              "pipeline_id": "spanish",
              "mixing": {
                  "original_audio_gain": 0.1,
                  "background_audio_gain": 0.8,
              },
          }
      ]
  }

  response = requests.patch(
      "https://client.camb.ai/apis/stream/1234",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )

  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

## Common updates

| Goal                          | Fields to send                                                          |
| ----------------------------- | ----------------------------------------------------------------------- |
| Pause / resume dubbing        | `pipeline_patches[].dubbing_enabled`                                    |
| Adjust the dubbing mix live   | `pipeline_patches[].mixing` gains (0.0–1.0)                             |
| Fix audio/video sync live     | `pipeline_patches[].avsync.delay` (−2.0 to 2.0 s)                       |
| Reschedule                    | `start_time`, `end_time`, `timezone`                                    |
| Change voices or dictionaries | `voices`, `dictionaries`                                                |
| Add a target language         | a new entry in `pipelines` (and its target)                             |
| Add or repoint an output      | `target_streams` entry with the same `id` (replace) or a new `id` (add) |

## Errors

* `400` - The stream has already finished and can no longer be updated.
* `404` - No stream with this ID belongs to your team.
* `422` - Validation error: unknown `pipeline_id`, an `id` reference that
  doesn't resolve, or times without a matching `timezone`.

## Related endpoints

* [Create a Stream](create-new-stream)
* [Get Stream Status](get-stream-status)
* [Delete a Stream](delete-stream)


# Use a Stream Template
Source: https://docs.camb.ai/api-reference/endpoint/streaming/use-template

get /stream/templates/{template_id}/payload
Retrieve a template's stream creation payload, ready to post as a new stream.

## Overview

Returns the stream creation payload the template was saved from: the exact
configuration of that stream, including its source, audio selections,
processing profiles, pipelines and targets.

The returned payload is compatible with the
[Create Stream](create-new-stream) request body. Its `start_time` and
`end_time` are the original stream's schedule and will be in the past, so set
them to your new broadcast window before creating the stream.

Templates are scoped to your workspace: requesting a template that belongs to
another workspace returns `404`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/stream/templates/12/payload" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://client.camb.ai/apis/stream/templates/12/payload",
      headers={"x-api-key": "YOUR_API_KEY"},
  )
  response.raise_for_status()

  payload = response.json()["payload"]

  # Reschedule, then create a new stream from the template.
  payload["start_time"] = "2026-08-15T18:45:00+02:00"
  payload["end_time"] = "2026-08-15T21:00:00+02:00"

  created = requests.post(
      "https://client.camb.ai/apis/stream",
      headers={"x-api-key": "YOUR_API_KEY"},
      json=payload,
  )
  created.raise_for_status()
  print(created.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "payload": {
      "name": "Matchday 3: home fixture",
      "source_stream": {
        "id": "stadium_feed",
        "url": "srt://ingest.example.com:9000",
        "category": 2
      },
      "audio_selections": [
        {
          "id": "commentary",
          "source": "$first_audio",
          "source_language": 1
        }
      ],
      "processing_profiles": [
        {
          "id": "full_dub",
          "demixing": "fast_model",
          "transcribing": "fast_model",
          "translating": "best_model",
          "revoicing": "fast_model"
        }
      ],
      "pipelines": [
        {
          "id": "spanish",
          "audio_selection": "commentary",
          "profile": "full_dub",
          "outputs": [
            { "id": "audio_es", "kind": "audio", "language": 37 },
            { "id": "subtitle_es", "kind": "subtitle", "language": 37 }
          ]
        }
      ],
      "target_streams": [
        {
          "id": "delivery",
          "type": 1,
          "url": "srt://delivery.example.com:9100",
          "inputs": [{ "asset_id": "audio_es" }]
        }
      ],
      "start_time": "2026-08-01T18:45:00+02:00",
      "end_time": "2026-08-01T21:00:00+02:00",
      "timezone": "Europe/Madrid"
    }
  }
  ```
</ResponseExample>

## Related endpoints

* [List Stream Templates](list-templates)
* [Create Stream](create-new-stream)


# Update Translation for a Term in Dictionary
Source: https://docs.camb.ai/api-reference/endpoint/update-term-in-dictionary

put /dictionaries/term/{dictionary_id}/{term_id}
Updates existing translations for a specific term within a dictionary, allowing you to refine translation accuracy, add new language variants, or correct linguistic content as your understanding evolves.

This endpoint represents one of the most nuanced and powerful operations in dictionary management - the ability to refine and improve existing translations after they've been established. Unlike creating new terms or adding entirely new content, updating translations acknowledges that language is living and evolving, and that our understanding of how concepts translate across cultures deepens over time.

## Understanding the Evolution of Translation Quality

The need to update translations arises from several important realities of multilingual content management. Languages themselves evolve, with new terms entering common usage while others become obsolete. Technical domains introduce specialized vocabulary that requires increasingly precise translations as understanding deepens. Cultural contexts shift, making some translations more or less appropriate over time.

## Quality Assurance in Translation Updates

Updating translations carries inherent responsibilities around quality assurance that extend beyond technical correctness. When you modify existing translations, you're potentially affecting every user and system that depends on that linguistic mapping. This influence requires thoughtful consideration of how changes might impact existing workflows, cached content, or user expectations.

## Integration Strategies for Translation Management

Consider implementing interfaces that help users understand the context and impact of proposed translation changes. Showing how current translations are being used, what alternatives exist, or how changes might affect related terms helps users make informed decisions about when updates truly improve linguistic resources versus when they might cause unintended disruption.


# Live Transcription (Websocket)
Source: https://docs.camb.ai/api-reference/websockets/listen

Stream raw audio to CAMB over a single WebSocket and receive cumulative interim transcripts, word-level timing, and typed events.

<Note>
  **Beta.** The live transcription WebSocket is generally available for testing but the schema, event shape, and error codes may change in backwards-incompatible ways before GA. Pin to the SDK versions you test against.
</Note>

## What you get back

After connect, the server emits a single `Ready` event, then streams `Results` messages as your audio is consumed. Each `Results` carries the **cumulative** transcript for the current utterance — replace your in-progress UI state with it rather than concatenating.

The `is_final` flag tells interim refinements (`false`) apart from the frame that finalizes an utterance (`true`). After a final, **the next `Results` starts a brand-new utterance from an empty string** — so if you only ever overwrite your UI with the latest `transcript`, each new utterance erases the previous one. Show the interim frames as a live preview, then commit the text when `is_final` is `true` (the server also emits an `UtteranceEnd` boundary marker around the same point). Word-level timing (`channel.alternatives[0].words`, each entry with `word`/`start`/`end`/`confidence`) is populated only on the **final** frame (`is_final: true`); interim frames carry an empty `words` array. The `UtteranceEnd` marker also reports `last_word_end`. When the client stops sending audio, the connection closes cleanly with WebSocket close code `1000`.

## Supported source languages

Pass any of the codes below as the `language` query parameter, or omit it to default to `en-us`. You can also pass the Languages enum name (`EN_US`) or its numeric ID. The model performs automatic language detection regardless of the value passed.

<Accordion title="All 143 supported source languages">
  | Code             | Language                                         |
  | :--------------- | :----------------------------------------------- |
  | `en-us`          | English (United States)                          |
  | `af-za`          | Afrikaans (South Africa)                         |
  | `am-et`          | Amharic (Ethiopia)                               |
  | `ar-ae`          | Arabic (United Arab Emirates)                    |
  | `ar-bh`          | Arabic (Bahrain)                                 |
  | `ar-dz`          | Arabic (Algeria)                                 |
  | `ar-eg`          | Arabic (Egypt)                                   |
  | `ar-iq`          | Arabic (Iraq)                                    |
  | `ar-jo`          | Arabic (Jordan)                                  |
  | `ar-kw`          | Arabic (Kuwait)                                  |
  | `ar-lb`          | Arabic (Lebanon)                                 |
  | `ar-ly`          | Arabic (Libya)                                   |
  | `ar-ma`          | Arabic (Morocco)                                 |
  | `ar-om`          | Arabic (Oman)                                    |
  | `ar-qa`          | Arabic (Qatar)                                   |
  | `ar-sa`          | Arabic (Saudi Arabia)                            |
  | `ar-sy`          | Arabic (Syria)                                   |
  | `ar-tn`          | Arabic (Tunisia)                                 |
  | `ar-ye`          | Arabic (Yemen)                                   |
  | `az-az`          | Azerbaijani (Latin, Azerbaijan)                  |
  | `bg-bg`          | Bulgarian (Bulgaria)                             |
  | `bn-bd`          | Bangla (Bangladesh)                              |
  | `bn-in`          | Bengali (India)                                  |
  | `bs-ba`          | Bosnian (Bosnia And Herzegovina)                 |
  | `ca-es`          | Catalan                                          |
  | `cs-cz`          | Czech (Czechia)                                  |
  | `cy-gb`          | Welsh (United Kingdom)                           |
  | `da-dk`          | Danish (Denmark)                                 |
  | `de-at`          | German (Austria)                                 |
  | `de-ch`          | German (Switzerland)                             |
  | `de-de`          | German (Germany)                                 |
  | `el-gr`          | Greek (Greece)                                   |
  | `en-au`          | English (Australia)                              |
  | `en-ca`          | English (Canada)                                 |
  | `en-gb`          | English (United Kingdom)                         |
  | `en-hk`          | English (Hong Kong Sar)                          |
  | `en-ie`          | English (Ireland)                                |
  | `en-in`          | English (India)                                  |
  | `en-ke`          | English (Kenya)                                  |
  | `en-ng`          | English (Nigeria)                                |
  | `en-nz`          | English (New Zealand)                            |
  | `en-ph`          | English (Philippines)                            |
  | `en-sg`          | English (Singapore)                              |
  | `en-tz`          | English (Tanzania)                               |
  | `en-za`          | English (South Africa)                           |
  | `es-ar`          | Spanish (Argentina)                              |
  | `es-bo`          | Spanish (Bolivia)                                |
  | `es-cl`          | Spanish (Chile)                                  |
  | `es-co`          | Spanish (Colombia)                               |
  | `es-cr`          | Spanish (Costa Rica)                             |
  | `es-cu`          | Spanish (Cuba)                                   |
  | `es-do`          | Spanish (Dominican Republic)                     |
  | `es-ec`          | Spanish (Ecuador)                                |
  | `es-es`          | Spanish (Spain)                                  |
  | `es-gq`          | Spanish (Equatorial Guinea)                      |
  | `es-gt`          | Spanish (Guatemala)                              |
  | `es-hn`          | Spanish (Honduras)                               |
  | `es-mx`          | Spanish (Mexico)                                 |
  | `es-ni`          | Spanish (Nicaragua)                              |
  | `es-pa`          | Spanish (Panama)                                 |
  | `es-pe`          | Spanish (Peru)                                   |
  | `es-pr`          | Spanish (Puerto Rico)                            |
  | `es-py`          | Spanish (Paraguay)                               |
  | `es-sv`          | Spanish (El Salvador)                            |
  | `es-us`          | Spanish (United States)                          |
  | `es-uy`          | Spanish (Uruguay)                                |
  | `es-ve`          | Spanish (Venezuela)                              |
  | `et-ee`          | Estonian (Estonia)                               |
  | `eu-es`          | Basque                                           |
  | `fa-ir`          | Persian (Iran)                                   |
  | `fi-fi`          | Finnish (Finland)                                |
  | `fr-be`          | French (Belgium)                                 |
  | `fr-ca`          | French (Canada)                                  |
  | `fr-ch`          | French (Switzerland)                             |
  | `fr-fr`          | French (France)                                  |
  | `gl-es`          | Galician                                         |
  | `gu-in`          | Gujarati (India)                                 |
  | `he-il`          | Hebrew (Israel)                                  |
  | `hi-in`          | Hindi (India)                                    |
  | `hr-hr`          | Croatian (Croatia)                               |
  | `hu-hu`          | Hungarian (Hungary)                              |
  | `hy-am`          | Armenian (Armenia)                               |
  | `id-id`          | Indonesian (Indonesia)                           |
  | `is-is`          | Icelandic (Iceland)                              |
  | `it-it`          | Italian (Italy)                                  |
  | `ja-jp`          | Japanese (Japan)                                 |
  | `ka-ge`          | Georgian (Georgia)                               |
  | `kk-kz`          | Kazakh (Kazakhstan)                              |
  | `km-kh`          | Khmer (Cambodia)                                 |
  | `kn-in`          | Kannada (India)                                  |
  | `ko-kr`          | Korean (Korea)                                   |
  | `lo-la`          | Lao (Laos)                                       |
  | `lt-lt`          | Lithuanian (Lithuania)                           |
  | `lv-lv`          | Latvian (Latvia)                                 |
  | `mk-mk`          | Macedonian (North Macedonia)                     |
  | `ml-in`          | Malayalam (India)                                |
  | `mn-mn`          | Mongolian (Mongolia)                             |
  | `mr-in`          | Marathi (India)                                  |
  | `ms-my`          | Malay (Malaysia)                                 |
  | `mt-mt`          | Maltese (Malta)                                  |
  | `my-mm`          | Burmese (Myanmar)                                |
  | `nb-no`          | Norwegian (Bokmål, Norway)                       |
  | `ne-np`          | Nepali (Nepal)                                   |
  | `nl-be`          | Dutch (Belgium)                                  |
  | `nl-nl`          | Dutch (Netherlands)                              |
  | `pa-in`          | Punjabi (India)                                  |
  | `pl-pl`          | Polish (Poland)                                  |
  | `ps-af`          | Pashto (Afghanistan)                             |
  | `pt-br`          | Portuguese (Brazil)                              |
  | `pt-pt`          | Portuguese (Portugal)                            |
  | `ro-ro`          | Romanian (Romania)                               |
  | `ru-ru`          | Russian (Russia)                                 |
  | `si-lk`          | Sinhala (Sri Lanka)                              |
  | `sk-sk`          | Slovak (Slovakia)                                |
  | `sl-si`          | Slovenian (Slovenia)                             |
  | `so-so`          | Somali (Somalia)                                 |
  | `sq-al`          | Albanian (Albania)                               |
  | `sr-rs`          | Serbian (Cyrillic, Serbia)                       |
  | `su-id`          | Sundanese (Indonesia)                            |
  | `sv-se`          | Swedish (Sweden)                                 |
  | `sw-ke`          | Swahili (Kenya)                                  |
  | `sw-tz`          | Swahili (Tanzania)                               |
  | `ta-in`          | Tamil (India)                                    |
  | `ta-lk`          | Tamil (Sri Lanka)                                |
  | `ta-my`          | Tamil (Malaysia)                                 |
  | `ta-sg`          | Tamil (Singapore)                                |
  | `te-in`          | Telugu (India)                                   |
  | `th-th`          | Thai (Thailand)                                  |
  | `tl-ph`          | Tagalog (Philippines)                            |
  | `tr-tr`          | Turkish (Turkey)                                 |
  | `uk-ua`          | Ukrainian (Ukraine)                              |
  | `ur-in`          | Urdu (India)                                     |
  | `ur-pk`          | Urdu (Pakistan)                                  |
  | `uz-uz`          | Uzbek (Latin, Uzbekistan)                        |
  | `vi-vn`          | Vietnamese (Vietnam)                             |
  | `zh-cn`          | Chinese (Mandarin, Simplified)                   |
  | `zh-cn-henan`    | Chinese (Zhongyuan Mandarin Henan, Simplified)   |
  | `zh-cn-liaoning` | Chinese (Northeastern Mandarin, Simplified)      |
  | `zh-cn-shaanxi`  | Chinese (Zhongyuan Mandarin Shaanxi, Simplified) |
  | `zh-cn-shandong` | Chinese (Jilu Mandarin, Simplified)              |
  | `zh-cn-sichuan`  | Chinese (Southwestern Mandarin, Simplified)      |
  | `zh-hk`          | Chinese (Cantonese, Traditional)                 |
  | `zh-tw`          | Chinese (Taiwanese Mandarin, Traditional)        |
</Accordion>

## Sample Testing Script

The CAMB SDKs wrap the protocol below behind a typed event dispatcher. The snippets here stream a WAV file at real-time pace so the server sees arrival patterns equivalent to a live microphone capture. For mic input, swap `FileAudioSource(...)` for `Microphone(...)` (Python) or `Microphone.fromBrowser` / `Microphone.fromNode` (TypeScript) — see the [Live Transcription tutorial](/tutorials/live-transcription-with-sdk).

<CodeGroup>
  ```python Python theme={null}
  # pip install camb-sdk
  import asyncio
  import os
  import wave

  from camb.client import CambAI
  from camb.live_transcription import FileAudioSource, ServerMessageType


  async def main(audio_path: str = "sample.wav") -> None:
      with wave.open(audio_path, "rb") as wf:
          sample_rate, channels = wf.getframerate(), wf.getnchannels()

      client = CambAI(api_key=os.environ["CAMB_API_KEY"])
      session = await client.live_transcription.connect(
          model="boli-v5",
          language="en-us",
          encoding="linear16",
          sample_rate=sample_rate,
          channels=channels,
      )

      @session.on(ServerMessageType.READY)
      def _(_): print("Ready: streaming audio...")

      @session.on(ServerMessageType.RESULTS)
      def _(msg):
          text = msg.transcript.strip()
          if not text:
              return
          # Interim frames print as they arrive; commit the final on its own
          # line so the next utterance doesn't overwrite it.
          if not msg.is_final:
              print(f"[Interim] {text}\n", end="", flush=True)
          else:
              print(f"\r\033[K{text}\n", end="", flush=True)

      @session.on(ServerMessageType.CLOSED)
      def _(info): print(f"\nClosed: code={info.code}")

      async with session:
          await session.stream_audio(FileAudioSource(audio_path, real_time=True))


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  // npm install @camb-ai/sdk ws
  import fs from "node:fs";
  import { CambClient, ServerMessageType } from "@camb-ai/sdk";

  // Minimal WAV reader — returns { sampleRate, channels, bitsPerSample, pcm }.
  function readWav(path: string) {
    const buf = fs.readFileSync(path);
    let o = 12, sr = 0, ch = 0, bps = 0, dStart = -1, dLen = 0;
    while (o < buf.length - 8) {
      const id = buf.toString("ascii", o, o + 4);
      const size = buf.readUInt32LE(o + 4);
      if (id === "fmt ") { ch = buf.readUInt16LE(o + 10); sr = buf.readUInt32LE(o + 12); bps = buf.readUInt16LE(o + 22); }
      else if (id === "data") { dStart = o + 8; dLen = size; break; }
      o += 8 + size;
    }
    return { sampleRate: sr, channels: ch, bitsPerSample: bps, pcm: buf.subarray(dStart, dStart + dLen) };
  }

  const { sampleRate, channels, bitsPerSample, pcm } = readWav("sample.wav");

  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY! });
  const session = await client.liveTranscription.connect({
    model: "boli-v5",
    language: "en-us",
    encoding: "linear16",
    sampleRate,
    channels,
  });

  session.on(ServerMessageType.Ready, () => console.log("Ready: streaming audio..."));
  session.on(ServerMessageType.Results, (m) => {
    const text = m.transcript.trim();
    if (!text) return;
    // Interim frames print as they arrive; commit the final on its own line.
    if (!m.isFinal) process.stdout.write(`[Interim] ${text}\n`);
    else process.stdout.write(`\r\x1b[K${text}\n`);
  });
  session.on(ServerMessageType.Closed, (i) => console.log(`\nClosed: code=${i.code}`));

  // Real-time-paced send so the server sees live arrival patterns.
  const bytesPerSec = sampleRate * channels * (bitsPerSample / 8);
  const chunk = Math.floor(bytesPerSec / 10);  // 100 ms
  const t0 = Date.now();
  let sent = 0;
  for (let i = 0; i < pcm.length; i += chunk) {
    await session.sendAudio(pcm.subarray(i, i + chunk));
    sent += chunk;
    const drift = (sent / bytesPerSec) * 1000 - (Date.now() - t0);
    if (drift > 0) await new Promise((r) => setTimeout(r, drift));
  }
  await session.close();
  await session.waitUntilClosed();
  ```
</CodeGroup>

### Timeout

The Live Transcription API has an internal timeout of 1 hour. Please add retries to handle/create further connections.

### Raw protocol (no SDK)

If you cannot use the SDKs, the wire protocol is small enough to drive directly. Open `wss://realtime.camb.ai/streaming-transcription/listen?...` with the `x-api-key` header, send binary PCM frames matching the `encoding` / `sample_rate` / `channels` query string, optionally send `{"type":"KeepAlive"}` during silence, and finish with `{"type":"CloseStream"}`. The server returns `{"type":"Ready"}` once, then `{"type":"Results", ...}` frames carrying the cumulative transcript (`"is_final": false` for interim refinements, `true` on the frame that finalizes each utterance), and closes with WebSocket code `1000` on a clean shutdown.


# Live TTS (WebSocket)
Source: https://docs.camb.ai/api-reference/websockets/live-tts

Stream text in, receive synthesized speech audio + optional word-level timestamps in real time over a single WebSocket connection.

Bidirectional WebSocket endpoint for real-time text-to-speech. Push text as you have it; receive audio as it's synthesized, in strict segment order. Designed for live captions, narration over streaming LLM output, interactive voice apps — anywhere you want playback to start before the writer is finished writing.

```
wss://client.camb.ai/apis/live-tts/ws
```

Authenticate with your CambAI API key via the `x-api-key` header (or `?api_key=...` query parameter for clients that can't set headers).

## Quickstart

A complete, copy-pasteable client. Connect → configure → stream text → write the audio to a file.

```python expandable theme={null}
import asyncio
import json
import websockets


async def synthesize(api_key: str, text: str, out_path: str = "out.mp3") -> None:
    url = "wss://client.camb.ai/apis/live-tts/ws"
    async with websockets.connect(
        url,
        additional_headers=[("x-api-key", api_key)],
    ) as ws:
        # 1. First frame: session config.
        await ws.send(json.dumps({
            "type": "session.start",
            "voice_id": 6460,
            "language": "en-us",
            "output_format": "mp3",
            "word_timestamps": True,
        }))

        # 2. Server confirms with session.ready.
        ready = json.loads(await ws.recv())
        assert ready["type"] == "session.ready", ready
        print(f"session {ready['session_id']} run_id={ready['run_id']}")

        # 3. Stream text. You can call text.chunk many times; the server
        #    segments based on content (and on a 1s idle flush).
        await ws.send(json.dumps({"type": "text.chunk", "text": text}))
        await ws.send(json.dumps({"type": "text.done"}))

        # 4. Receive ordered audio + json frames until the session ends.
        with open(out_path, "wb") as f:
            async for msg in ws:
                if isinstance(msg, bytes):
                    f.write(msg)
                    continue

                frame = json.loads(msg)
                kind = frame["type"]
                if kind == "segment.start":
                    print(f"  segment {frame['segment_id']}: {frame['text']!r}")
                    for w in frame.get("word_timestamps", []):
                        print(f"    {w['start']:6.2f}s → {w['end']:6.2f}s  {w['word']}")
                elif kind == "segment.skipped":
                    print(f"  ! skipped segment {frame['segment_id']}: {frame['text']!r}")
                elif kind == "session.done":
                    print("done")
                    break
                elif kind == "session.error":
                    raise RuntimeError(frame["error"])


asyncio.run(synthesize(
    api_key="your-camb-api-key",
    text="Hello, world. This is a streaming text-to-speech demo.",
))
```

That's the whole integration surface. Everything below is reference for the four message types you'll exchange.

## Integration in 4 steps

<Steps>
  <Step title="Open the socket with your API key">
    ```python theme={null}
    async with websockets.connect(
        "wss://client.camb.ai/apis/live-tts/ws",
        additional_headers=[("x-api-key", "your-camb-api-key")],
    ) as ws:
        ...
    ```

    Missing or invalid key → server closes with code `4401`.
  </Step>

  <Step title="Send `session.start` as the first frame">
    ```json theme={null}
    {
      "type": "session.start",
      "voice_id": 6460,
      "language": "en-us",
      "output_format": "mp3",
      "word_timestamps": true,
      "idle_timeout": 1.0,

      "enhance_named_entities_pronunciation": false,
      "apply_enhancement": null,
      "enhance_reference_audio_quality": false,
      "maintain_source_accent": false,
      "speaking_rate": null,
      "inference_steps": null
    }
    ```

    `voice_id` is the only required field — everything else has a sensible default. The tuning knobs mirror the regular `POST /tts-stream` API one-for-one (`enhance_named_entities_pronunciation`, `apply_enhancement`, `enhance_reference_audio_quality`, `maintain_source_accent`, `speaking_rate`), so you can port a working `/tts-stream` payload directly. See the full reference at the top of the page for types and defaults.

    Wait for the `session.ready` reply (carries `session_id` and `run_id`). A malformed first frame, forbidden voice, or unsupported language → `session.error` then close `4400`.
  </Step>

  <Step title="Stream text in">
    ```json theme={null}
    {"type": "text.chunk", "text": "Hello, "}
    {"type": "text.chunk", "text": "world."}
    ```

    Push as fast or as slowly as you like. The server segments by content (sentence boundaries), and **idle-flushes after `idle_timeout` seconds of silence** (default `1.0`) — so for live use cases (LLM token stream, transcribed mic input) you don't need to send `text.done` until the session is truly over.

    `idle_timeout` is only a *fallback* flush for trailing fragments without a boundary. **A complete sentence (terminal punctuation, paragraph break, etc.) is flushed immediately — it never waits on `idle_timeout`.** Bump the value on `session.start` (e.g. `2.5`) if your producer routinely stalls *mid*-sentence — slower LLMs, token-level jitter — to avoid splitting one sentence across two segments.

    <Warning>
      **Slow producers fragment sentences.** If your LLM (or other source) is not producing text fast enough to land consecutive chunks within `idle_timeout` (default `1s`), each chunk will be flushed as its own segment — even if together they would have formed a single sentence. The result is choppier audio and prosody that resets at each fragment boundary. Raise `idle_timeout` to cover the worst-case gap between your producer's tokens.
    </Warning>
  </Step>

  <Step title="Read ordered audio + lifecycle frames">
    For each segment N, the server emits, in order:

    ```
    segment.start N → <binary audio chunks> → segment.done N
    ```

    Segment N's frames are completely emitted before any of segment N+1's, even though synthesis runs concurrently behind the scenes. Concatenate the binary frames per `segment_id` and you have playable audio.

    When everything is done you'll receive `session.done`, followed by a clean close.
  </Step>
</Steps>

## Common patterns

### Stream from an LLM

Push tokens straight from the model. Don't call `text.done` — let the idle flush handle in-flight buffering, then close when the LLM is done.

```python theme={null}
async for token in llm_stream():
    await ws.send(json.dumps({"type": "text.chunk", "text": token}))

# LLM finished; flush any tail and end cleanly.
await ws.send(json.dumps({"type": "text.done"}))
```

### Play audio while it's still synthesizing

Hand each segment to your player as soon as `segment.done` arrives:

```python theme={null}
buffers: dict[int, bytearray] = {}
current_segment: int | None = None

async for msg in ws:
    if isinstance(msg, bytes):
        if current_segment is not None:
            buffers.setdefault(current_segment, bytearray()).extend(msg)
        continue

    frame = json.loads(msg)
    if frame["type"] == "segment.start":
        current_segment = frame["segment_id"]
    elif frame["type"] == "segment.done":
        sid = frame["segment_id"]
        player.enqueue(bytes(buffers.pop(sid)))   # play this segment
        current_segment = None
    elif frame["type"] == "session.done":
        break
```

### Recover from a skipped segment

`segment.skipped` means TTS retries (3 by default, exponential backoff) were exhausted for that segment. The session keeps running — re-send the text in a new `text.chunk` if you need the audio:

```python theme={null}
if frame["type"] == "segment.skipped":
    await ws.send(json.dumps({"type": "text.chunk", "text": frame["text"]}))
```

### Word-level timestamps

Set `"word_timestamps": true` in `session.start`. When resolution succeeds, `segment.start` carries a `word_timestamps` array:

```json theme={null}
{
  "type": "segment.start",
  "segment_id": 0,
  "text": "Hello, world.",
  "word_timestamps": [
    {"word": "Hello", "start": 0.04, "end": 0.32},
    {"word": "world", "start": 0.38, "end": 0.71}
  ]
}
```

Word-timestamp failures (timeout, 5xx, network) are silently swallowed; the segment is still delivered without the `word_timestamps` field. Treat it as **best-effort** — don't block playback on it.

## Reference

The AsyncAPI spec above documents every message type and field. Quick lookup:

### Close codes

| Code   | Reason                                                     |
| :----- | :--------------------------------------------------------- |
| `4400` | Bad first frame, forbidden voice, or unsupported language. |
| `4401` | Missing or invalid API key.                                |
| `4402` | Insufficient credits.                                      |

### Auth & billing

* API key auth is identical to the rest of `/apis/*`.
* A `TTS_API` Run is created on `session.start`; its `run_id` is in `session.ready` and can be queried later via the standard run endpoints.
* **Credits are deducted per segment**, immediately before that segment is synthesized. If you run out mid-session, the server emits a single `session.error` and closes with `4402`.

### Voice & language

Voice access uses the same rules as `/tts-stream`. The session is pinned to the `mars-8.1-flash-beta` speech model — see the [streaming TTS docs](/api-reference/endpoint/create-tts-stream) for the supported BCP-47 locales. For best results, supply a reference voice in the same language/accent as `language`.

### Server-side TTS retries

`ConnectionError` / `TimeoutError` / `OSError` / `aiohttp.ClientError` against the underlying TTS engine trigger up to 3 retries per segment with exponential backoff. On exhaustion the segment becomes `segment.skipped` (see *Recover from a skipped segment* above) and the rest of the session continues normally.


# Realtime Speech To Speech
Source: https://docs.camb.ai/api-reference/websockets/realtime

Stream microphone audio into a realtime translation session and receive transcripts, translated text, and translated audio.

<Note>
  **Beta.** The Speech to Speech WebSocket is generally available for testing but session events, configuration, and audio formats may change in backwards-incompatible ways before GA.
</Note>

Bidirectional WebSocket endpoint for real-time speech translation. This endpoint is served by `realtime-api-server` at `wss://realtime.camb.ai/v1/realtime`, separate from the `/apis/live-tts/ws` and `/streaming-transcription/listen` WebSocket endpoints.

```http theme={null}
GET /v1/realtime
Host: realtime.camb.ai
x-api-key: <YOUR_API_KEY>
```

Sessions run in one of two modes, selected with the `mode` query parameter or the `mode` field of the first `session.update`. `fast` (the default) accepts audio almost immediately and translates with the lowest latency, but supports fewer languages. `slow` supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready.

`mode` replaced a `model` parameter that took engine codenames. Both are still accepted — `iris` resolves to `fast`, and `lilac`/`violet`/`orchid` to `slow` — so existing integrations keep working while you migrate.

Authenticate with the `x-api-key` WebSocket request header. If your client cannot set WebSocket headers, send credentials in the first `session.update` event instead.

## Quickstart

Use the **SDK** (Python or TypeScript) — it handles the session lifecycle (including the `session.starting` cold-boot wait), surfaces the server's binary audio frames as typed audio events, and exposes typed events. Input and output audio are PCM16, mono, 24 kHz. The example below streams a WAV file and writes the translated speech to another WAV.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import os
  import wave

  from camb.client import CambAI
  from camb.realtime import ServerEventType
  from camb.live_transcription import FileAudioSource


  async def main():
      client = CambAI(api_key=os.environ["CAMB_API_KEY"])
      session = await client.realtime.connect(
          source_language="en-us",
          target_language="de-de",
      )

      out_audio = bytearray()

      @session.on(ServerEventType.TEXT_DONE)
      def _(event):
          print("translation:", event.text)

      @session.on(ServerEventType.AUDIO_DELTA)
      def _(event):
          out_audio.extend(event.data)  # raw PCM16 mono 24 kHz

      async with session:
          await session.wait_until_ready()
          # Input WAV must be 16-bit PCM, mono, 24 kHz.
          await session.stream_audio(FileAudioSource("input_24k_mono.wav", real_time=True))

      with wave.open("translated.wav", "wb") as out:
          out.setnchannels(1)
          out.setsampwidth(2)
          out.setframerate(24000)
          out.writeframes(bytes(out_audio))


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import fs from "node:fs";

  import { CambClient, RealtimeServerEventType } from "@camb-ai/sdk";

  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });
  const session = await client.realtime.connect({
    sourceLanguage: "en-us",
    targetLanguage: "de-de",
  });

  const outChunks = [];
  let resolveDone;
  const audioDone = new Promise((r) => (resolveDone = r));

  session.on(RealtimeServerEventType.TextDone, (event) =>
    console.log("translation:", event.text),
  );
  session.on(RealtimeServerEventType.AudioDelta, (event) =>
    outChunks.push(Buffer.from(event.data)), // raw PCM16 mono 24 kHz
  );
  session.on(RealtimeServerEventType.AudioDone, () => resolveDone());

  await session.waitUntilReady();

  // Input WAV must be 16-bit PCM, mono, 24 kHz. This skips the standard 44-byte
  // header and streams the PCM data at real-time pace in 100 ms slices.
  const data = fs.readFileSync("input_24k_mono.wav").subarray(44);
  const chunkSize = 24000 * 2 * 0.1;
  for (let i = 0; i < data.length; i += chunkSize) {
    await session.sendAudio(data.subarray(i, i + chunkSize));
    await new Promise((r) => setTimeout(r, 100));
  }

  await Promise.race([audioDone, new Promise((r) => setTimeout(r, 30_000))]);
  await session.close();

  // Raw PCM16 mono 24 kHz; wrap in a WAV header to play it (see the tutorial).
  fs.writeFileSync("translated.pcm", Buffer.concat(outChunks));
  ```
</CodeGroup>

See the [Realtime Speech Translation tutorial](/tutorials/realtime-translation-with-sdk) for the microphone quickstart, the full event list, and configuration.

The sections below document the underlying wire protocol for reference (for example, if you are building a client in a language without an SDK).

## Integration in 4 steps

<Steps>
  <Step title="Open the realtime socket">
    Connect to `wss://realtime.camb.ai/v1/realtime`. This endpoint is not under the `client.camb.ai/apis` namespace used by the other WebSocket API references.

    ```python theme={null}
    async with websockets.connect(
        "wss://realtime.camb.ai/v1/realtime",
        additional_headers=[("x-api-key", "YOUR_API_KEY")],
    ) as ws:
        ...
    ```
  </Step>

  <Step title="Send `session.update` as the first message">
    The first WebSocket message must be a JSON `session.update` event. The server waits up to 10 seconds for it.

    ```json theme={null}
    {
      "type": "session.update",
      "session": {
        "source_language": "en-us",
        "target_language": "de-de",
        "output_modalities": ["text", "audio"]
      }
    }
    ```

    The server responds with `session.created`, then `session.updated`.
  </Step>

  <Step title="Stream input audio">
    Send microphone audio as base64-encoded bytes in `input_audio_buffer.append`. Only text WebSocket messages are parsed as realtime events.

    ```json theme={null}
    {
      "type": "input_audio_buffer.append",
      "audio": "<base64_audio_bytes>"
    }
    ```

    Each decoded audio payload can be up to 256 KiB.
  </Step>

  <Step title="Read translated output">
    Listen for transcript, translated text, and translated audio events. `response.text.delta` values are additive for the current response, and `response.audio.delta` contains base64-encoded synthesized audio bytes.
  </Step>
</Steps>

## Authentication

Prefer the WebSocket request header:

```http theme={null}
x-api-key: <YOUR_API_KEY>
```

The initial `session.update` event can also carry credentials:

<CodeGroup>
  ```json API key auth theme={null}
  {
    "type": "session.update",
    "session": {
      "source_language": "en-us",
      "target_language": "de-de",
      "output_modalities": ["text", "audio"]
    },
    "auth": {
      "api_key": "<YOUR_API_KEY>"
    }
  }
  ```
</CodeGroup>

If both the request header and `auth` object are present, the request header credential is used.

## Reference

The AsyncAPI spec above documents every client and server event. Quick lookup:

### Session configuration

| Field               | Type      | Required | Notes                                                                                                 |
| :------------------ | :-------- | :------- | :---------------------------------------------------------------------------------------------------- |
| `source_language`   | string    | Yes      | Source language tag, for example `en-us`. Must be a [supported language](#supported-languages).       |
| `target_language`   | string    | Yes      | Target language tag, for example `de-de`. Must be a [supported language](#supported-languages).       |
| `output_modalities` | string\[] | No       | Defaults to `["text", "audio"]`.                                                                      |
| `voice`             | object    | No       | Output voice selection. Defaults to `{ "type": "default" }`. See [Voice selection](#voice-selection). |

### Voice selection

By default, translated speech is synthesized with a built-in voice for the target language. To synthesize the translation with one of your own cloned voices, include a `voice` object in the session configuration:

```json theme={null}
{
  "type": "session.update",
  "session": {
    "source_language": "en-us",
    "target_language": "de-de",
    "output_modalities": ["text", "audio"],
    "voice": { "type": "cloned", "voice_id": 147320 }
  }
}
```

| Field      | Type    | Required                  | Notes                                                                                                                                                        |
| :--------- | :------ | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | string  | Yes                       | `"default"` to use the built-in voice, or `"cloned"` to use one of your voices.                                                                              |
| `voice_id` | integer | When `type` is `"cloned"` | ID of a voice you own. Get it from [List Voices](/api-reference/endpoint/list-voices) or [Create Custom Voice](/api-reference/endpoint/create-custom-voice). |

The voice must belong to your account — stock/built-in voice IDs are rejected with an `error` event. Omitting `voice` (or sending `{ "type": "default" }`) uses the built-in voice. The resolved selection is echoed back in `session.created`.

If you use the SDK, pass `voice_id` (Python) or `voiceId` (TypeScript) to `realtime.connect()` and it builds this `voice` object for you:

<CodeGroup>
  ```python Python theme={null}
  session = await client.realtime.connect(
      source_language="en-us",
      target_language="de-de",
      voice_id=147320,
  )
  ```

  ```typescript TypeScript theme={null}
  const session = await client.realtime.connect({
    sourceLanguage: "en-us",
    targetLanguage: "de-de",
    voiceId: 147320,
  });
  ```
</CodeGroup>

<Tip>
  For the most natural-sounding results, choose a voice whose reference
  language matches your `target_language`. A large mismatch between the
  voice's native language and the translation language can reduce clarity
  and accent accuracy.
</Tip>

### Supported languages

`source_language` and `target_language` accept the BCP-47 tags below (case-insensitive). Pick any supported language as the source and any supported language as the target.

<Accordion title="Supported realtime languages (14)">
  | Code    | Language                       |
  | :------ | :----------------------------- |
  | `ar-ae` | Arabic (United Arab Emirates)  |
  | `ar-eg` | Arabic (Egypt)                 |
  | `ar-sa` | Arabic (Saudi Arabia)          |
  | `de-de` | German (Germany)               |
  | `en-gb` | English (United Kingdom)       |
  | `en-us` | English (United States)        |
  | `es-es` | Spanish (Spain)                |
  | `fr-ca` | French (Canada)                |
  | `fr-fr` | French (France)                |
  | `hi-in` | Hindi (India)                  |
  | `ja-jp` | Japanese (Japan)               |
  | `ko-kr` | Korean (Korea)                 |
  | `pt-br` | Portuguese (Brazil)            |
  | `zh-cn` | Chinese (Mandarin, Simplified) |
</Accordion>

### Client events

| Event                       | Support                                        |
| :-------------------------- | :--------------------------------------------- |
| `session.update`            | Required first message.                        |
| `input_audio_buffer.append` | Supported after activation.                    |
| `input_audio_buffer.clear`  | Recognized but not supported; returns `error`. |
| `input_audio_buffer.commit` | Recognized but not supported; returns `error`. |
| `response.cancel`           | Recognized but not supported; returns `error`. |

### Server events

| Event                                                   | Description                                            |
| :------------------------------------------------------ | :----------------------------------------------------- |
| `session.created`                                       | Session has been authorized, started, and activated.   |
| `session.updated`                                       | Active session configuration.                          |
| `conversation.item.input_audio_transcription.completed` | Completed user transcript.                             |
| `response.text.delta`                                   | Additive translated text delta.                        |
| `response.text.done`                                    | Final translated text.                                 |
| `response.audio.delta`                                  | Base64-encoded translated audio bytes.                 |
| `response.audio.done`                                   | Current translated audio response is complete.         |
| `error`                                                 | Unsupported recognized event or billing stop decision. |

### Limits

| Limit                                                         | Value                      |
| :------------------------------------------------------------ | :------------------------- |
| Initial `session.update` timeout                              | 10 seconds                 |
| Maximum client event text size                                | 1 MiB                      |
| Maximum decoded audio payload per `input_audio_buffer.append` | 256 KiB                    |
| Audio encoding in `input_audio_buffer.append.audio`           | Base64-encoded audio bytes |

### Billing

Active sessions are charged in billing windows and finalized on close, failure, or billing stop. If billing stops a session, the server sends an `error` event whose `error.message` is the billing close reason, then ends the realtime loop.


# Choosing a Model
Source: https://docs.camb.ai/choosing-a-model

A guide to picking the right MARS 8 variant for your use case

The MARS 8 family has six model variants, each optimized for different trade-offs between **latency**, **quality**, **controllability**, and **deployment footprint**. Use this guide to find the best fit for your application.

## Quick Comparison

|                             | MARS-8.1-Flash-Beta           | MARS-8.1-Pro-Beta | MARS-Flash | MARS-Pro     | MARS-Instruct    | MARS-Nano    |
| --------------------------- | ----------------------------- | ----------------- | ---------- | ------------ | ---------------- | ------------ |
| **Parameters**              | 600M                          | 600M              | 600M       | 600M         | 1.2B             | 50M          |
| **TTFB**                    | Faster than MARS-8.1-Pro-Beta | 800 ms – 2 s      | \~150 ms   | 800 ms – 2 s | Higher (offline) | 500 ms – 2 s |
| **Real-time capable**       | Yes                           | Yes               | Yes        | Yes          | No               | Yes          |
| **Emotion/prosody control** | No                            | No                | No         | No           | Yes              | No           |
| **On-device friendly**      | No                            | No                | No         | No           | No               | Yes          |

## Decision Flowchart

Start with the primary constraint of your application:

### 1. Do you want to evaluate the newest MARS 8.1 beta models?

**Yes - try [MARS-8.1-Flash-Beta](/models#mars-81-flash-beta-48khz) or [MARS-8.1-Pro-Beta](/models#mars-81-pro-beta-48khz).**

Use `speech_model: "mars-8.1-flash-beta"` when you want the same MARS 8.1 quality target with faster generation. Use `speech_model: "mars-8.1-pro-beta"` when you want to compare the newest Pro-quality model against `mars-pro`. These 8.1 models may perform much better for pronunciation, overall prosody, accent control, accent coverage, quality across different accents, and expressiveness with high-pitch reference voices.

Because these are beta models, validate them with your target voices, languages, accents, and formats before rolling them into production. For best results, your target language should use a reference voice in the same language and accent.

### 2. Do you need real-time, low-latency speech?

**Yes - use [MARS-Flash](/models#mars-flash-2205khz48khz).**

Flash is purpose-built for conversational AI. With TTFB as low as 150 ms, it handles agentic conversations, call center bots, and live assistants where every millisecond counts.

Choose Flash when:

* You're building a voice agent or assistant
* End-to-end latency is a hard requirement
* Speed and real-time responsiveness matter most

### 3. Do you need high-fidelity speech with voice and emotion transfer?

**Yes - use [MARS-Pro](/models#mars-pro-48khz).**

Pro offers balanced speed and fidelity, delivering the best overall performance when speed is not the primary constraint. It preserves speaker identity and emotion from reference audio, making it ideal for dubbing, audiobooks, and expressive media.

Choose Pro when:

* You need expressive, natural-sounding speech
* Real-time translation with voice transfer is required
* You can tolerate 800 ms – 2 s of latency
* Short or challenging reference audio is involved

### 4. Do you need fine-grained control over delivery style?

**Yes - use [MARS-Instruct](/models#mars-instruct-2205khz).**

Instruct gives you director-level control. You can independently adjust speaker identity, emotion, and prosody using either a reference audio sample or a text description (e.g., "warm and reassuring tone").

Choose Instruct when:

* You're producing content for TV, film, or post-production
* You need to guide emotion and delivery with text instructions
* Latency is not a concern (batch/offline workflows)
* You want to decouple speaker identity from speaking style

<Note>
  See the [Emotional Voice Control tutorial](/tutorials/emotional-voice-control) for examples of emotion tags, prosody control, and best practices.
</Note>

### 5. Do you need to run TTS on-device?

**Yes - use [MARS-Nano](/models#mars-nano).**

At just 50M parameters, Nano runs in memory-constrained environments where cloud access isn't available or practical.

Choose Nano when:

* You're deploying on edge hardware or mobile devices
* Strict memory and compute budgets apply
* Cloud connectivity is unreliable or unavailable

## Common Scenarios

| Scenario                                            | Recommended Model         |
| --------------------------------------------------- | ------------------------- |
| Faster MARS 8.1 output with stronger accent quality | MARS-8.1-Flash-Beta       |
| Evaluating the newest Pro-quality TTS output        | MARS-8.1-Pro-Beta         |
| Voice agent for customer support                    | MARS-Flash                |
| Real-time language translation with voice cloning   | MARS-Pro                  |
| Audiobook production                                | MARS-Pro                  |
| Movie dubbing with director-guided emotion          | MARS-Instruct             |
| Smart speaker / IoT device                          | MARS-Nano                 |
| Live conversational assistant                       | MARS-Flash                |
| Post-production voice editing                       | MARS-Instruct             |
| Offline batch TTS pipeline                          | MARS-Pro or MARS-Instruct |

## Still Not Sure?

* **Start with MARS-Pro** if you want the best balance of speed and fidelity without worrying about constraints.
* **Switch to Flash** if latency testing reveals Pro is too slow for your real-time pipeline.
* **Reach out on [Discord](https://discord.gg/hzXnxTxhFw)** if your use case doesn't fit neatly into one of these categories.


# Custom Cloud Providers
Source: https://docs.camb.ai/custom-cloud-providers



### A Compute-First Business Model

The status quo of "pay-per-character" API pricing eats margins as they scale. We are changing it. This is also ideal for enterprise use cases requiring strict data privacy, dedicated throughput, or custom model fine-tuning.

MARS 8 Series is available on following providers:

* Google Cloud Vertex AI
* AWS Bedrock
* Hugging face
* Baseten
* Modal
* Cerebrium
* Simplismart
* Replicate

For access contact [help@camb.ai](mailto:help@camb.ai)

## Routing Via Camb AI SDK

The Camb AI SDK directly supports routing Text-to-Speech generation requests to private or above custom deployments of the MARS model.

#### Baseten Deployment

Initialize the client with your API key and the specific model URL. [Baseten Provider Example](https://github.com/Camb-ai/cambai-python-sdk/blob/main/examples/baseten_provider_example.py)

Deployment Link: [https://app.baseten.co/deploy/mars8-flash](https://app.baseten.co/deploy/mars8-flash)

```python theme={null}
import base64
from camb.client import CambAI, save_stream_to_file

client = CambAI(
    tts_provider="baseten",
    provider_params={
        "api_key": "YOUR_BASETEN_API_KEY",
        "mars_pro_url": "https://model-xxxxxx.api.baseten.co/environments/production/predict"
    }
)

def main():
    response = client.text_to_speech.tts(
        text="Hello World and my dear friends",
        language="en-us",
        speech_model="mars-flash",
        request_options={
            "additional_body_parameters": {
                "reference_audio": base64.b64encode(open("audio.wav", "rb").read()).decode('utf-8'),  # or a public signed url
                "reference_language": "en-us"  # required
            },
            "timeout_in_seconds": 300
        }
    )
    save_stream_to_file(response, "tts_output.wav")
    print("Success! Audio saved to tts_output.wav")

if __name__ == "__main__":
    main()
```

### How it Works

1. The SDK bypasses standard Camb AI API endpoints.
2. It authenticates directly with Baseten using the provided API Key.
3. It streams generated audio directly from the model instance.

## Vertex AI Deployment

<Note>
  Support for Vertex AI is currently in progress.
</Note>

#### Usage Example

```python theme={null}
client = CambAI(
    tts_provider="vertex",
    provider_params={
        "project_id": "your-gcp-project-id",
        "location": "us-central1"
    }
)
```


# Authentication & API Keys
Source: https://docs.camb.ai/getting-started/authentication

Learn how to authenticate with the CAMB.AI API

All CAMB.AI API requests require authentication using an API key. This guide explains how to obtain and use your API key.

## Getting Your API Key

1. Go to [CAMB.AI Studio](https://studio.camb.ai)
2. Sign in or create an account
3. Navigate to your account settings
4. Generate or copy your API key

<Warning>
  Keep your API key secure. Never expose it in client-side code or public repositories.
</Warning>

## Using Your API Key

Include your API key in the `x-api-key` header of every request.

### Header Format

```
x-api-key: your_camb_api_key
```

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/tts-stream" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello world!",
      "voice_id": 147320
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://client.camb.ai/apis/tts-stream",
      headers=headers,
      json={"text": "Hello world!", "voice_id": 147320}
  )
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://client.camb.ai/apis/tts-stream", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      text: "Hello world!",
      voice_id: 147320
    })
  });
  ```
</CodeGroup>

## SDK Authentication

When using the official SDKs, pass your API key during client initialization.

<CodeGroup>
  ```python Python SDK theme={null}
  from camb.client import CambAI

  client = CambAI(api_key="your_api_key")
  # Or use environment variable
  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))
  ```

  ```typescript TypeScript SDK theme={null}
  import { CambClient } from '@camb-ai/sdk';

  const client = new CambClient({ apiKey: "YOUR_API_KEY" });
  // Or use environment variable
  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });
  ```
</CodeGroup>

## Error Responses

| Status Code | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `401`       | Invalid or missing API key                        |
| `403`       | API key doesn't have permission for this resource |
| `429`       | Rate limit exceeded                               |

### Example Error Response

```json theme={null}
{
  "error": "Invalid API key",
  "status": 401
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Never hardcode API keys">
    Use environment variables or secure secret management systems.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Generate new API keys regularly and revoke old ones.
  </Accordion>

  <Accordion title="Use separate keys for environments">
    Create different API keys for development, staging, and production.
  </Accordion>

  <Accordion title="Monitor usage">
    Check your API usage in CAMB.AI Studio to detect unauthorized access.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/getting-started/quickstart">
    Make your first API call
  </Card>

  <Card title="SDK Guide" icon="code" href="/sdk-guides/general-guide">
    Use our official SDKs
  </Card>
</CardGroup>


# Baseten
Source: https://docs.camb.ai/hosting-platforms/baseten

Use Camb.ai MARS models with your own Baseten deployment

## Overview

The Camb.ai SDK supports using **Baseten** as a TTS provider, allowing you to run MARS models on your own Baseten infrastructure for enhanced control and scalability.

Deployment Link: [https://app.baseten.co/deploy/mars8-flash](https://app.baseten.co/deploy/mars8-flash)

### Key Features

* **Self-hosted Infrastructure**: Run MARS models on your own Baseten deployment
* **Voice Cloning**: Requires reference audio for voice cloning capabilities
* **Streaming Support**: Real-time audio streaming
* **Full SDK Integration**: Works seamlessly with both Python and TypeScript SDKs

***

## Prerequisites

* A Baseten account with MARS model deployed
* Your Baseten API key
* Your Baseten model URL (mars\_pro\_url)
* A reference audio file for voice cloning

***

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install camb-sdk
  ```

  ```bash TypeScript theme={null}
  npm install @camb-ai/sdk
  ```
</CodeGroup>

## Usage

<CodeGroup>
  ```python Python theme={null}
  import base64
  from camb.client import CambAI, save_stream_to_file

  client = CambAI(
      tts_provider="baseten",
      provider_params={
          "api_key": "YOUR_BASETEN_API_KEY",
          "mars_pro_url": "https://model-xxxxxx.api.baseten.co/environments/production/predict"
      }
  )

  def main():
      response = client.text_to_speech.tts(
          text="Hello World and my dear friends",
          language="en-us",
          speech_model="mars-pro",
          request_options={
              "additional_body_parameters": {
                  "reference_audio": base64.b64encode(open("audio.wav", "rb").read()).decode('utf-8'),
                  "reference_language": "en-us"  # required
              },
              "timeout_in_seconds": 300
          }
      )
      save_stream_to_file(response, "tts_output.mp3")
      print("Success! Audio saved to tts_output.mp3")

  if __name__ == "__main__":
      main()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, saveStreamToFile } from '@camb-ai/sdk';
  import * as fs from 'fs';

  // Initialize client with Baseten provider
  const client = new CambClient({
      ttsProvider: 'baseten',
      providerParams: {
          api_key: process.env.BASETEN_API_KEY || 'YOUR_BASETEN_API_KEY',
          mars_pro_url: process.env.BASETEN_URL || 'YOUR_BASETEN_MARS_PRO_URL'
      }
  });

  async function main() {
      try {
          // Read reference audio file (you need to provide this)
          const referenceAudioPath = process.env.REFERENCE_AUDIO_PATH || 'reference.wav';

          if (!fs.existsSync(referenceAudioPath)) {
              console.error(`Reference audio file not found: ${referenceAudioPath}`);
              console.log('Please provide a reference audio file or set REFERENCE_AUDIO_PATH environment variable');
              return;
          }

          const referenceAudio = fs.readFileSync(referenceAudioPath).toString('base64');

          console.log('Generating speech with Baseten provider...');
          const response = await client.textToSpeech.tts({
              text: 'Hello World and my dear friends',
              language: 'en-us',
              speech_model: 'mars-pro',
              output_configuration: {
                  format: 'wav'
              },
              additional_body_parameters: {
                  reference_audio: referenceAudio,
                  reference_language: 'en-us'  // required
              }
          });

          const outputFile = 'baseten_output.wav';
          await saveStreamToFile(response, outputFile);
          console.log(`✓ Audio generated with Baseten provider and saved to ${outputFile}`);

      } catch (error) {
          console.error('Error:', error.message);
          if (error.body) {
              console.error('Details:', error.body);
          }
      }
  }

  main();
  ```
</CodeGroup>

***

## Configuration

### Required Parameters

| Parameter            | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `api_key`            | Your Baseten API key                                 |
| `mars_pro_url`       | Your Baseten MARS model endpoint URL                 |
| `reference_audio`    | Base64-encoded reference audio for voice cloning     |
| `reference_language` | Language code of the reference audio (e.g., `en-us`) |

### Optional Parameters

| Parameter            | Description                   | Default    |
| -------------------- | ----------------------------- | ---------- |
| `speech_model`       | MARS model variant            | `mars-pro` |
| `language`           | Target language for synthesis | `en-us`    |
| `output_format`      | Audio output format           | `mp3`      |
| `timeout_in_seconds` | Request timeout               | -          |

***

## Resources

* [Baseten Documentation](https://docs.baseten.co)
* [Camb.ai Python SDK](https://github.com/camb-ai/cambai-python-sdk)
* [Camb.ai TypeScript SDK](https://github.com/camb-ai/cambai-node-sdk)


# LiveKit
Source: https://docs.camb.ai/integrations/livekit

Build real-time voice AI agents with Camb.ai TTS and LiveKit Agents

<Note>Integration with LiveKit is currently being reviewed</Note>

## Overview

The **livekit-plugins-camb** package enables you to integrate Camb.ai's MARS text-to-speech models into your LiveKit voice agents. This integration provides high-quality, low-latency voice synthesis for real-time conversational AI applications.

### Key Features

* **MARS Models**: Access to Camb.ai's latest generation TTS models (mars-flash, mars-pro)
* **Multilingual**: Up to 312 languages depending on the MARS model — see [Language Support](/language-support)
* **Real-time Streaming**: HTTP chunked streaming for low-latency audio
* **Voice Customization**: Voice selection and enhanced pronunciation for names/places
* **Model-specific Sample Rates**: 22.05kHz (mars-flash) or 48kHz (mars-pro)

***

## Installation

### Prerequisites

* Python 3.9 or higher
* A Camb.ai API key ([get one here](https://studio.camb.ai))
* LiveKit Cloud account or self-hosted LiveKit server

### Install the Plugin

```bash theme={null}
pip install livekit-plugins-camb
```

For a complete voice agent setup with VAD (Voice Activity Detection):

```bash theme={null}
pip install livekit-plugins-camb 'livekit-agents[silero]' python-dotenv
```

***

## Quick Start

### 1. Set Up Environment Variables

Create a `.env` file in your project directory:

```bash theme={null}
# Camb.ai API key
CAMB_API_KEY=your_camb_api_key

# LiveKit credentials
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret

# LLM provider (e.g., OpenAI)
OPENAI_API_KEY=your_openai_api_key

# STT provider (e.g., Deepgram)
DEEPGRAM_API_KEY=your_deepgram_api_key
```

### 2. Create Your Voice Agent

```python theme={null}
import logging

from dotenv import load_dotenv
from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    JobProcess,
    cli,
    room_io,
)
from livekit.plugins import camb, silero

load_dotenv()

logger = logging.getLogger("voice-agent")


class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=(
                "You are a helpful voice assistant. "
                "Keep your responses concise and conversational. "
                "Do not use emojis or special formatting."
            ),
        )

    async def on_enter(self):
        # Generate initial greeting
        self.session.generate_reply(allow_interruptions=False)


server = AgentServer()


def prewarm(proc: JobProcess):
    # Pre-load VAD model for faster startup
    proc.userdata["vad"] = silero.VAD.load()


server.setup_fnc = prewarm


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        # Speech-to-text
        stt="deepgram/nova-3",
        # Language model
        llm="openai/gpt-4.1-mini",
        # Camb.ai TTS
        tts=camb.TTS(),
        # Voice activity detection
        vad=ctx.proc.userdata["vad"],
    )

    await session.start(
        agent=MyAgent(),
        room=ctx.room,
    )


if __name__ == "__main__":
    cli.run_app(server)
```

### 3. Run Your Agent

**Development mode** (with LiveKit Agents Playground):

```bash theme={null}
python your_agent.py dev
```

**Production mode**:

```bash theme={null}
python your_agent.py start
```

***

## Configuration

### TTS Options

The `camb.TTS` class accepts the following parameters:

| Parameter                | Type   | Default                | Description                                                   |
| ------------------------ | ------ | ---------------------- | ------------------------------------------------------------- |
| `api_key`                | `str`  | `CAMB_API_KEY` env var | Your Camb.ai API key                                          |
| `voice_id`               | `int`  | `147320`               | Voice ID (use `list_voices()` to discover)                    |
| `language`               | `str`  | `"en-us"`              | BCP-47 language code                                          |
| `model`                  | `str`  | `"mars-flash"`         | MARS model to use (`mars-flash` or `mars-pro`)                |
| `output_format`          | `str`  | `"pcm_s16le"`          | Audio format                                                  |
| `enhance_named_entities` | `bool` | `False`                | Enhanced pronunciation for names and places                   |
| `sample_rate`            | `int`  | Auto-detected          | Audio sample rate (auto-detected from model if not specified) |

### Available Models

<Tabs>
  <Tab title="Fast (Recommended)">
    ```python theme={null}
    tts=camb.TTS(model="mars-flash")
    ```

    Best for real-time voice agents. Lowest latency (22.05kHz) with high quality.
  </Tab>

  <Tab title="High Quality">
    ```python theme={null}
    tts=camb.TTS(model="mars-pro")
    ```

    Higher quality synthesis at 48kHz sample rate.
  </Tab>
</Tabs>

### Language Support

Camb.ai supports up to 312 languages depending on the MARS model — see [Language Support](/language-support) for the full per-model locale list. Specify the language using BCP-47 codes:

```python theme={null}
# English (US)
tts=camb.TTS(language="en-us")

# French
tts=camb.TTS(language="fr-fr")

# Spanish
tts=camb.TTS(language="es-es")

# German
tts=camb.TTS(language="de-de")

# Japanese
tts=camb.TTS(language="ja-jp")
```

***

## Advanced Usage

### Dynamic Option Updates

Update TTS settings during a session:

```python theme={null}
# Change voice mid-conversation
session.tts.update_options(voice_id=1234)

# Switch model
session.tts.update_options(model="mars-pro")

# Switch language
session.tts.update_options(language="es-es")
```

### Function Tools

Add custom capabilities to your agent using the `@function_tool` decorator. The LLM automatically discovers these functions and calls them based on user conversation.

```python theme={null}
from livekit.agents.llm import function_tool
from livekit.agents import RunContext

class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful assistant that can look up weather.",
        )

    @function_tool
    async def lookup_weather(
        self,
        context: RunContext,
        location: str,
        latitude: str,
        longitude: str
    ):
        """Called when the user asks for weather related information.
        Ensure the user's location (city or region) is provided.
        When given a location, please estimate the latitude and longitude of the location and
        do not ask the user for them.

        Args:
            location: The location they are asking for
            latitude: The latitude of the location, do not ask user for it
            longitude: The longitude of the location, do not ask user for it
        """
        # Your weather lookup logic here
        return "sunny with a temperature of 70 degrees."
```

For more details, see the [LiveKit Function Tools documentation](https://docs.livekit.io/agents/logic/tools/).

### Custom HTTP Session

For advanced use cases, provide your own aiohttp session:

```python theme={null}
import aiohttp

async with aiohttp.ClientSession() as session:
    tts = camb.TTS(http_session=session)
    # Use TTS...
```

### Metrics and Logging

Track usage and performance:

```python theme={null}
from livekit.agents import metrics, MetricsCollectedEvent

usage_collector = metrics.UsageCollector()

@session.on("metrics_collected")
def on_metrics(ev: MetricsCollectedEvent):
    metrics.log_metrics(ev.metrics)
    usage_collector.collect(ev.metrics)

# Get usage summary after session
summary = usage_collector.get_summary()
logger.info(f"Session usage: {summary}")
```

***

## Full Voice Agent Example

Here's a full example combining all features.

### Installation

```bash theme={null}
pip install livekit-plugins-camb 'livekit-agents[silero]' python-dotenv
```

### Code

```python theme={null}
import logging

from dotenv import load_dotenv

from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    JobProcess,
    MetricsCollectedEvent,
    RunContext,
    cli,
    metrics,
    room_io,
)
from livekit.agents.llm import function_tool
from livekit.plugins import camb, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

logger = logging.getLogger("basic-agent")

load_dotenv()


class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="Your name is Kelly. You would interact with users via voice."
            "with that in mind keep your responses concise and to the point."
            "do not use emojis, asterisks, markdown, or other special characters in your responses."
            "You are curious and friendly, and have a sense of humor."
            "you will speak english to the user",
        )

    async def on_enter(self):
        # when the agent is added to the session, it'll generate a reply
        # according to its instructions
        # Keep it uninterruptible so the client has time to calibrate AEC
        self.session.generate_reply(allow_interruptions=False)

    @function_tool
    async def lookup_weather(
        self, context: RunContext, location: str, latitude: str, longitude: str
    ):
        """Called when the user asks for weather related information.
        Ensure the user's location (city or region) is provided.
        When given a location, please estimate the latitude and longitude of the location and
        do not ask the user for them.

        Args:
            location: The location they are asking for
            latitude: The latitude of the location, do not ask user for it
            longitude: The longitude of the location, do not ask user for it
        """
        logger.info(f"Looking up weather for {location}")
        return "sunny with a temperature of 70 degrees."


server = AgentServer()


def prewarm(proc: JobProcess):
    proc.userdata["vad"] = silero.VAD.load()


server.setup_fnc = prewarm


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    ctx.log_context_fields = {"room": ctx.room.name}

    session = AgentSession(
        stt="deepgram/nova-3",
        llm="openai/gpt-4.1-mini",
        tts=camb.TTS(),
        turn_detection=MultilingualModel(),
        vad=ctx.proc.userdata["vad"],
        preemptive_generation=True,
        resume_false_interruption=True,
        false_interruption_timeout=1.0,
    )

    usage_collector = metrics.UsageCollector()

    @session.on("metrics_collected")
    def _on_metrics_collected(ev: MetricsCollectedEvent):
        metrics.log_metrics(ev.metrics)
        usage_collector.collect(ev.metrics)

    async def log_usage():
        summary = usage_collector.get_summary()
        logger.info(f"Usage: {summary}")

    ctx.add_shutdown_callback(log_usage)

    await session.start(
        agent=MyAgent(),
        room=ctx.room,
        room_options=room_io.RoomOptions(
            audio_input=room_io.AudioInputOptions(),
        ),
    )


if __name__ == "__main__":
    cli.run_app(server)
```

### Run

**Development mode** (opens playground in browser):

```bash theme={null}
python your_agent.py dev
```

**Production mode:**

```bash theme={null}
python your_agent.py start
```

Then connect via the [LiveKit Agents Playground](https://agents-playground.livekit.io/).

***

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Invalid API Key Error">
    Ensure your `CAMB_API_KEY` environment variable is set correctly:

    ```bash theme={null}
    export CAMB_API_KEY=your_api_key_here
    ```

    Or pass it directly:

    ```python theme={null}
    tts=camb.TTS(api_key="your_api_key")
    ```
  </Accordion>

  <Accordion title="Voice Not Found">
    The voice ID must be an integer. Use `list_voices()` to find available voices:

    ```python theme={null}
    voices = await camb.list_voices()
    print(voices)
    ```
  </Accordion>

  <Accordion title="Timeout Errors">
    TTS synthesis can take time for longer texts. The plugin automatically uses a minimum 60-second timeout.

    For very long texts, consider breaking them into smaller chunks.
  </Accordion>

  <Accordion title="Audio Quality Issues">
    * Use `mars-pro` for highest quality (48kHz) or `mars-flash` for best latency (22.05kHz)
    * Ensure your network connection is stable
    * Use `pcm_s16le` format for lowest latency
  </Accordion>

  <Accordion title="Connection Errors">
    Check that you can reach the Camb.ai API:

    ```bash theme={null}
    curl -H "x-api-key: YOUR_KEY" https://client.camb.ai/apis/list-voices
    ```
  </Accordion>
</AccordionGroup>

### Debug Logging

Enable debug logging for detailed information:

```python theme={null}
import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("livekit.plugins.camb")
logger.setLevel(logging.DEBUG)
```

***

## Resources

* [LiveKit Agents Documentation](https://docs.livekit.io/agents/)
* [LiveKit Agents Playground](https://agents-playground.livekit.io/)
* [Camb.ai API Reference](/api-reference/endpoint/create-tts)
* [LiveKit Agents GitHub Repository](https://github.com/livekit/agents)
* [LiveKit Slack Community](https://livekit.io/join-slack)


# Pipecat
Source: https://docs.camb.ai/integrations/pipecat

Build real-time voice AI agents with Camb.ai TTS and Pipecat

## Overview

The **pipecat-ai** framework provides a `CambTTSService` that integrates Camb.ai's MARS text-to-speech models into your voice AI pipelines. This integration enables high-quality, low-latency voice synthesis for real-time conversational AI applications.

### Key Features

* **MARS Models**: Access to Camb.ai's latest generation TTS models (mars-flash, mars-pro)
* **140+ Languages**: Extensive multilingual support
* **Real-time Streaming**: Streaming audio chunks for low-latency output
* **Model-specific Sample Rates**: 22.05kHz (mars-flash) or 48kHz (mars-pro)
* **Multiple Transports**: Works with Daily, Twilio, WebRTC, and WebSocket transports

***

## Installation

### Prerequisites

* Python 3.9 or higher
* A Camb.ai API key ([get one here](https://studio.camb.ai))
* A transport provider account (e.g., Daily, Twilio)

### Install Pipecat with Camb.ai Support

```bash theme={null}
pip install "pipecat-ai[camb,silero]"
```

For a complete voice agent setup with specific transports:

```bash theme={null}
# With Daily transport
pip install "pipecat-ai[camb,silero,daily]"

# With Twilio transport
pip install "pipecat-ai[camb,silero,websocket]"
```

***

## Quick Start

### 1. Set Up Environment Variables

Create a room at [Daily Dashboard](https://dashboard.daily.co/rooms), then create a `.env` file in your project directory:

```bash theme={null}
# Camb.ai API key
CAMB_API_KEY=your_camb_api_key

# Daily room configuration
DAILY_ROOM_URL=https://your-domain.daily.co/room-name
DAILY_TOKEN=your_daily_token  # Optional for public rooms

# STT provider (e.g., Deepgram)
DEEPGRAM_API_KEY=your_deepgram_api_key

# LLM provider (e.g., OpenAI)
OPENAI_API_KEY=your_openai_api_key
```

### 2. Create Your Voice Agent

```python theme={null}
import asyncio
import os

from dotenv import load_dotenv
from loguru import logger

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.services.camb.tts import CambTTSService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.daily.transport import DailyTransport, DailyParams

load_dotenv()


async def main():
    # Get room configuration from environment
    room_url = os.getenv("DAILY_ROOM_URL")
    token = os.getenv("DAILY_TOKEN", "")  # Don't include this for public rooms

    # to generate a token, you can use this curl command:
    # curl -H "Content-Type: application/json" \
    # -H "Authorization: Bearer <your-api-key>" \
    # -XPOST -d '{"properties":{"room_name":"<room-name>"}}' \
    # https://api.daily.co/v1/meeting-tokens
    # then use the token in the DAILY_TOKEN environment variable
    # then join the room with the token. https://your-room-url.daily.co/room-id?t=your-room-token

    if not room_url:
        raise ValueError("DAILY_ROOM_URL environment variable is required")

    logger.info(f"Connecting to room: {room_url}")

    # Configure transport
    transport = DailyTransport(
        room_url=room_url,
        token=token,
        bot_name="Camb Voice Bot",
        params=DailyParams(
            audio_in_enabled=True,
            audio_out_enabled=True,
            vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
        ),
    )

    # Initialize services
    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))

    tts = CambTTSService(
        api_key=os.getenv("CAMB_API_KEY"),
        model="mars-flash",
    )

    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))

    # Set up conversation context
    messages = [
        {
            "role": "system",
            "content": "You are a helpful voice assistant. "
            "Keep your responses concise and conversational. "
            "Avoid special characters or emojis.",
        },
    ]

    context = LLMContext(messages)
    context_aggregator = LLMContextAggregatorPair(context)

    # Build the pipeline
    pipeline = Pipeline(
        [
            transport.input(),
            stt,
            context_aggregator.user(),
            llm,
            tts,
            transport.output(),
            context_aggregator.assistant(),
        ]
    )

    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
        ),
    )

    # Handle client connection
    @transport.event_handler("on_client_connected")
    async def on_client_connected(transport, client):
        logger.info("Client connected")
        messages.append({"role": "system", "content": "Please introduce yourself briefly."})
        await task.queue_frames([LLMRunFrame()])

    @transport.event_handler("on_client_disconnected")
    async def on_client_disconnected(transport, client):
        logger.info("Client disconnected")
        await task.cancel()

    runner = PipelineRunner()
    await runner.run(task)


if __name__ == "__main__":
    asyncio.run(main())
```

### 3. Run Your Agent

```bash theme={null}
python your_agent.py
```

***

## Configuration

### CambTTSService Options

The `CambTTSService` class accepts the following parameters:

| Parameter     | Type          | Default        | Description                                                          |
| ------------- | ------------- | -------------- | -------------------------------------------------------------------- |
| `api_key`     | `str`         | Required       | Your Camb.ai API key                                                 |
| `voice_id`    | `int`         | `147320`       | Voice ID (browse voices at [Camb.ai Studio](https://studio.camb.ai)) |
| `model`       | `str`         | `"mars-flash"` | MARS model to use                                                    |
| `timeout`     | `float`       | `60.0`         | Request timeout in seconds                                           |
| `sample_rate` | `int`         | Auto           | Audio sample rate (auto-detected from model)                         |
| `params`      | `InputParams` | `None`         | Additional voice parameters                                          |

### InputParams Options

| Parameter  | Type       | Default       | Description            |
| ---------- | ---------- | ------------- | ---------------------- |
| `language` | `Language` | `Language.EN` | Language for synthesis |

### Available Models

<Tabs>
  <Tab title="Fast (Recommended)">
    ```python theme={null}
    tts = CambTTSService(
        api_key=os.getenv("CAMB_API_KEY"),
        model="mars-flash",
    )
    ```

    Best for real-time voice agents. Lowest latency at 22.05kHz sample rate.
  </Tab>

  <Tab title="High Quality">
    ```python theme={null}
    tts = CambTTSService(
        api_key=os.getenv("CAMB_API_KEY"),
        model="mars-pro",
    )
    ```

    Highest quality output at 48kHz sample rate.
  </Tab>
</Tabs>

### Language Support

Camb.ai supports up to 312 languages depending on the MARS model — see [Language Support](/language-support) for the full per-model locale list. Specify the language using Pipecat's `Language` enum:

```python theme={null}
from pipecat.transcriptions.language import Language
from pipecat.services.camb.tts import CambTTSService

# English (US)
tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    params=CambTTSService.InputParams(language=Language.EN_US),
)

# French
tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    params=CambTTSService.InputParams(language=Language.FR),
)

# Spanish
tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    params=CambTTSService.InputParams(language=Language.ES),
)

# Japanese
tts = CambTTSService(
    api_key=os.getenv("CAMB_API_KEY"),
    params=CambTTSService.InputParams(language=Language.JA),
)
```

***

## Advanced Usage

### Dynamic Settings Updates

Update TTS settings during runtime:

```python theme={null}
# Update language
await tts._update_settings({"language": Language.ES})

# Update voice
await tts._update_settings({"voice_id": 12345})
```

### Using with Multiple Transports

Pipecat supports multiple transport backends. Here's how to configure Camb.ai TTS with different transports:

```python theme={null}
from pipecat.transports.daily.transport import DailyTransport, DailyParams
from pipecat.transports.websocket.fastapi import FastAPIWebsocketTransport, FastAPIWebsocketParams
from pipecat.transports.webrtc.transport import WebRTCTransport, TransportParams

# Daily transport
daily_transport = DailyTransport(
    room_url="...",
    token="...",
    params=DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    ),
)

# WebSocket transport (for Twilio)
websocket_transport = FastAPIWebsocketTransport(
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
    ),
)
```

### Metrics and Logging

Track usage and performance with Pipecat's built-in metrics:

```python theme={null}
from pipecat.pipeline.task import PipelineParams, PipelineTask

task = PipelineTask(
    pipeline,
    params=PipelineParams(
        enable_metrics=True,
        enable_usage_metrics=True,
    ),
)
```

Enable debug logging for detailed information:

```python theme={null}
from loguru import logger

logger.enable("pipecat")
```

***

## Multi-Transport Voice Agent

Here's a full example using the Pipecat runner utilities for transport-agnostic deployment:

```python theme={null}
import os

from dotenv import load_dotenv
from loguru import logger

from pipecat.audio.turn.smart_turn.local_smart_turn_v3 import LocalSmartTurnAnalyzerV3
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.runner.types import RunnerArguments
from pipecat.runner.utils import create_transport
from pipecat.services.camb.tts import CambTTSService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.base_transport import BaseTransport, TransportParams
from pipecat.transports.daily.transport import DailyParams
from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams
from pipecat.turns.user_stop import TurnAnalyzerUserTurnStopStrategy
from pipecat.turns.user_turn_strategies import UserTurnStrategies

load_dotenv(override=True)


transport_params = {
    "daily": lambda: DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
    ),
    "twilio": lambda: FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
    ),
    "webrtc": lambda: TransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
    ),
}


async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
    logger.info("Starting Camb.ai TTS bot")

    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))

    tts = CambTTSService(
        api_key=os.getenv("CAMB_API_KEY"),
        model="mars-flash",
    )

    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))

    messages = [
        {
            "role": "system",
            "content": "You are a helpful voice assistant powered by Camb.ai. "
            "Keep your responses concise and conversational. "
            "Avoid special characters, emojis, or bullet points.",
        },
    ]

    context = LLMContext(messages)
    user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
        context,
        user_params=LLMUserAggregatorParams(
            user_turn_strategies=UserTurnStrategies(
                stop=[TurnAnalyzerUserTurnStopStrategy(turn_analyzer=LocalSmartTurnAnalyzerV3())]
            ),
        ),
    )

    pipeline = Pipeline(
        [
            transport.input(),
            stt,
            user_aggregator,
            llm,
            tts,
            transport.output(),
            assistant_aggregator,
        ]
    )

    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
            audio_out_sample_rate=22050,
        ),
        idle_timeout_secs=runner_args.pipeline_idle_timeout_secs,
    )

    @transport.event_handler("on_client_connected")
    async def on_client_connected(transport, client):
        logger.info("Client connected")
        messages.append({"role": "system", "content": "Please introduce yourself."})
        await task.queue_frames([LLMRunFrame()])

    @transport.event_handler("on_client_disconnected")
    async def on_client_disconnected(transport, client):
        logger.info("Client disconnected")
        await task.cancel()

    runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
    await runner.run(task)


async def bot(runner_args: RunnerArguments):
    """Main bot entry point compatible with Pipecat Cloud."""
    transport = await create_transport(runner_args, transport_params)
    await run_bot(transport, runner_args)


if __name__ == "__main__":
    from pipecat.runner.run import main
    main()
```

***

## Tutorial: Local Voice Agent

Build a voice agent that runs on your local machine using your microphone and speakers - perfect for quick prototyping.

### Installation

```bash theme={null}
pip install "pipecat-ai[camb,silero,local]"
```

### Local Audio Example

```python theme={null}
import asyncio
import os

from dotenv import load_dotenv
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.services.camb.tts import CambTTSService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.local.audio import LocalAudioTransport, LocalAudioTransportParams

load_dotenv()


async def main():
    transport = LocalAudioTransport(
        LocalAudioTransportParams(
            audio_in_enabled=True,
            audio_out_enabled=True,
            vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
        )
    )

    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
    tts = CambTTSService(api_key=os.getenv("CAMB_API_KEY"), model="mars-flash")
    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))

    messages = [{"role": "system", "content": "You are a helpful voice assistant."}]
    context = LLMContext(messages)
    context_aggregator = LLMContextAggregatorPair(context)

    pipeline = Pipeline([
        transport.input(),
        stt,
        context_aggregator.user(),
        llm,
        tts,
        transport.output(),
        context_aggregator.assistant(),
    ])

    task = PipelineTask(pipeline, params=PipelineParams(audio_out_sample_rate=22050))

    @task.event_handler("on_pipeline_started")
    async def on_started(task, frame):
        messages.append({"role": "system", "content": "Please introduce yourself."})
        await task.queue_frames([LLMRunFrame()])

    runner = PipelineRunner()
    await runner.run(task)


if __name__ == "__main__":
    asyncio.run(main())
```

***

## Tutorial: Self-Hosted WebRTC Agent

Deploy a voice agent accessible from any browser without third-party services.

### Installation

```bash theme={null}
pip install "pipecat-ai[camb,silero,webrtc]" pipecat-ai-small-webrtc-prebuilt fastapi uvicorn
```

### WebRTC Server Example

```python theme={null}
import os
import uuid
from typing import Dict

import uvicorn
from dotenv import load_dotenv
from fastapi import BackgroundTasks, FastAPI, Request
from fastapi.responses import RedirectResponse
from pipecat_ai_small_webrtc_prebuilt.frontend import SmallWebRTCPrebuiltUI

from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams
from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat.services.camb.tts import CambTTSService
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.transports.base_transport import TransportParams
from pipecat.transports.smallwebrtc.connection import IceServer, SmallWebRTCConnection
from pipecat.transports.smallwebrtc.transport import SmallWebRTCTransport

load_dotenv()

app = FastAPI()
connections: Dict[str, SmallWebRTCConnection] = {}
sessions: Dict[str, Dict] = {}
ice_servers = [IceServer(urls="stun:stun.l.google.com:19302")]
app.mount("/client", SmallWebRTCPrebuiltUI)


async def run_bot(conn: SmallWebRTCConnection):
    transport = SmallWebRTCTransport(
        webrtc_connection=conn,
        params=TransportParams(
            audio_in_enabled=True,
            audio_out_enabled=True,
            vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.2)),
        ),
    )

    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
    tts = CambTTSService(api_key=os.getenv("CAMB_API_KEY"), model="mars-flash")
    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))

    messages = [{"role": "system", "content": "You are a helpful voice assistant."}]
    context = LLMContext(messages)
    context_aggregator = LLMContextAggregatorPair(context)

    pipeline = Pipeline([
        transport.input(), stt, context_aggregator.user(),
        llm, tts, transport.output(), context_aggregator.assistant(),
    ])

    task = PipelineTask(pipeline, params=PipelineParams(enable_metrics=True))

    @transport.event_handler("on_client_connected")
    async def on_connected(transport, client):
        messages.append({"role": "system", "content": "Please introduce yourself."})
        await task.queue_frames([LLMRunFrame()])

    @transport.event_handler("on_client_disconnected")
    async def on_disconnected(transport, client):
        await task.cancel()

    runner = PipelineRunner(handle_sigint=False)
    await runner.run(task)


@app.get("/")
async def root():
    return RedirectResponse(url="/client/")


@app.post("/start")
async def start(request: Request):
    """RTVI protocol: Create a new session."""
    try:
        request_data = await request.json()
    except Exception:
        request_data = {}

    session_id = str(uuid.uuid4())
    sessions[session_id] = request_data

    result = {"sessionId": session_id}
    if request_data.get("enableDefaultIceServers"):
        result["iceConfig"] = {"iceServers": [{"urls": "stun:stun.l.google.com:19302"}]}
    return result


@app.api_route("/sessions/{session_id}/{path:path}", methods=["POST", "PATCH"])
async def session_proxy(session_id: str, path: str, request: Request, background_tasks: BackgroundTasks):
    """RTVI protocol: Proxy requests to session endpoints."""
    if session_id not in sessions:
        return {"error": "Invalid session"}, 404

    if path.endswith("api/offer"):
        request_data = await request.json()
        return await offer(request_data, background_tasks)
    return {"status": "ok"}


@app.post("/api/offer")
async def offer(request: dict, background_tasks: BackgroundTasks):
    pc_id = request.get("pc_id")

    if pc_id and pc_id in connections:
        conn = connections[pc_id]
        await conn.renegotiate(
            sdp=request["sdp"],
            type=request["type"],
            restart_pc=request.get("restart_pc", False),
        )
    else:
        conn = SmallWebRTCConnection(ice_servers)
        await conn.initialize(sdp=request["sdp"], type=request["type"])

        @conn.event_handler("closed")
        async def handle_closed(c: SmallWebRTCConnection):
            connections.pop(c.pc_id, None)

        background_tasks.add_task(run_bot, conn)

    answer = conn.get_answer()
    connections[answer["pc_id"]] = conn
    return answer


if __name__ == "__main__":
    uvicorn.run(app, host="localhost", port=7860)
```

Run and open [http://localhost:7860](http://localhost:7860) in your browser.

***

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Invalid API Key Error">
    Ensure your `CAMB_API_KEY` environment variable is set correctly:

    ```bash theme={null}
    export CAMB_API_KEY=your_api_key_here
    ```

    Or pass it directly:

    ```python theme={null}
    tts = CambTTSService(api_key="your_api_key")
    ```
  </Accordion>

  <Accordion title="Voice Not Found">
    The voice ID must be an integer. Browse available voices at [Camb.ai Studio](https://studio.camb.ai) to find valid voice IDs.
  </Accordion>

  <Accordion title="Text Too Short Error">
    Camb.ai requires a minimum of 3 characters for TTS synthesis. The service will log a warning and skip synthesis for shorter text.
  </Accordion>

  <Accordion title="Timeout Errors">
    TTS synthesis can take time for longer texts. The default timeout is 60 seconds. For very long texts, consider:

    * Breaking them into smaller chunks
    * Increasing the timeout: `CambTTSService(..., timeout=120.0)`
  </Accordion>

  <Accordion title="Sample Rate Mismatch">
    Different models use different sample rates:

    * `mars-flash`: 22.05kHz
    * `mars-pro`: 48kHz

    The service automatically selects the correct sample rate based on the model. If you need a specific rate, pass it explicitly:

    ```python theme={null}
    tts = CambTTSService(..., sample_rate=48000)
    ```
  </Accordion>
</AccordionGroup>

### Debug Logging

Enable debug logging for detailed information:

```python theme={null}
from loguru import logger

# Enable all pipecat logging
logger.enable("pipecat")

# Or enable specific module logging
import logging
logging.basicConfig(level=logging.DEBUG)
```

***

## Resources

* [Pipecat Documentation](https://docs.pipecat.ai/)
* [Pipecat GitHub Repository](https://github.com/pipecat-ai/pipecat)
* [Camb.ai API Reference](/api-reference/endpoint/create-tts)
* [Pipecat Examples](https://github.com/pipecat-ai/pipecat/tree/main/examples)
* [Pipecat Discord Community](https://discord.gg/pipecat)


# Introduction
Source: https://docs.camb.ai/introduction



CAMB.AI is the localization AI infrastructure company built to help the world’s biggest Enterprises reach 8 billion fans, customers and viewers. Supporting 140+ languages!
Explore our docs to integrate Camb AI's MARS & BOLI models into your applications.

<CardGroup>
  <Card title="SDK Guide" icon="code" href="/tutorials/tts-with-sdk">
    Learn how to install and use the Python & Node.js SDKs to build voice apps quickly.
  </Card>

  <Card title="Custom Cloud Providers" icon="cloud" href="/custom-cloud-providers">
    Access MARS models on your own favorite cloud providers like Google Cloud, Modal, Baseten, etc.
  </Card>

  <Card title="Open Source" icon="github" href="/open-source">
    Explore our open-source models MARS 6 and MARS 5 on GitHub.
  </Card>
</CardGroup>

## Quick Start

<div>
  <UseCaseCard title="Text to Speech" description="Generate speech from text using the Python or TypeScript SDK. The best place to start." icon="🎙️" href="/tutorials/tts-with-sdk" />

  <UseCaseCard title="TTS without SDK" description="Call the TTS API directly with HTTP requests for maximum control." icon="⌨️" href="/tutorials/direct-api" />

  <UseCaseCard title="TTS with Accents" description="Generate speech in 140+ language accents with the same voice." icon="🌍" href="/tutorials/tts-with-accents" />

  <UseCaseCard title="Translated TTS" description="Translate text and generate speech in the target language in one call." icon="🌐" href="/tutorials/translated-tts" />

  <UseCaseCard title="Text to Sound Effects" description="Generate royalty-free sound effects and music from text descriptions." icon="🔊" href="/tutorials/text-to-sound" />

  <UseCaseCard title="Voice Cloning" description="Clone a voice from a reference audio file and generate speech with it." icon="🎤" href="/tutorials/voice-cloning" />
</div>

***

## Features Suite

* **Live Streaming**: Deliver live content globally with real-time audio translation and dubbing.
* **Live Text to Speech**: Realistic, emotional speech synthesis, featuring MARS 8 in 4 variants - mars pro, mars flash, mars instruct, and mars nano. Available on all cloud providers.
* **Translation**: Context-aware neural translation using our proprietary BOLI Model.
* **Dubbing**: Automated video dubbing using our AI that preserves emotional delivery across 140+ languages.
* **Voice Cloning**: Create digital voice replicas from audio as short as 2 seconds.
* **Audio Separation**: Isolate and extract distinct audio components from mixed recordings using deep learning to separate speech from background elements.
* **Sound and Music**: Create high-quality music and realistic soundscapes, delivering immersive audio experiences from simple text prompts.
* **Transcription**: Convert speech to text with speaker identification, timestamps, and specialized terminology (dictionaries) support.
* **Subtitles**: Generate subtitle-ready cues from a media file, translated into any number of target languages in one call.
  and more!

Continue exploring our detailed documentation for each API:

<CardGroup>
  <Card title="Live Streaming" icon="satellite-dish" href="/api-reference/endpoint/streaming/overview">
    Stream real-time dubbed content for live events, broadcasts, and interactive applications.
  </Card>

  <Card title="Text-to-Speech" icon="audio-lines" href="/api-reference/endpoint/create-tts-stream">
    Transform text into natural-sounding speech with customizable voice features across 140+ languages
  </Card>

  <Card title="Translated Text-to-Speech" icon="messages-square" href="/api-reference/endpoint/create-translated-tts">
    Translate text and synthesize speech in one step across 140+ languages
  </Card>

  <Card title="Dubbing" icon="video" href="/api-reference/endpoint/end-to-end-dubbing">
    Localize your content using our AI that preserves emotional delivery across 140+ languages
  </Card>

  <Card title="Stories" icon="book-audio" href="/api-reference/endpoint/create-story">
    Convert written narratives into audiobooks using your own voice or custom voice.
  </Card>

  <Card title="Translated Stories" icon="book-audio" href="/api-reference/endpoint/create-translated-story">
    Translate and convert narratives into audiobooks in 140+ languages
  </Card>

  <Card title="Translation" icon="languages" href="/api-reference/endpoint/create-translation">
    Translate content across 140+ language pairs  with context-aware neural technology.
  </Card>

  <Card title="Transcription" icon="captions" href="/api-reference/endpoint/create-transcription">
    Convert speech to text with speaker identification, timestamps, and specialized terminology (dictionaries) support.
  </Card>

  <Card title="Subtitles" icon="closed-caption" href="/api-reference/endpoint/create-subtitle">
    Generate subtitle-ready cues from a media file, translated into any number of target languages in one call.
  </Card>

  <Card title="Voice from Description" icon="speech" href="/api-reference/endpoint/create-text-to-voice">
    Create unique voices by describing characteristics or clone existing voices from audio samples for consistent brand identity.
  </Card>

  <Card title="Sound and Music" icon="speaker" href="/api-reference/endpoint/create-text-to-sound">
    Create high-quality music and realistic soundscapes, delivering immersive audio experiences from simple text prompts.
  </Card>

  <Card title="Audio Separation" icon="separator-vertical" href="/api-reference/endpoint/create-audio-separation">
    Isolate and extract distinct audio components from mixed recordings using deep learning to separate speech from background elements.
  </Card>
</CardGroup>


# Language Support
Source: https://docs.camb.ai/language-support



Each MARS model supports a different set of languages and locales. Use the locale code (e.g. `en-us`) as the `language` parameter when calling the API.

## MARS-Flash & MARS-Pro (MARS 8)

Supported in `mars-flash` and `mars-pro`. **33 languages supported.**

| Code    | Language              |
| :------ | :-------------------- |
| `en-us` | English (USA)         |
| `en-in` | English (India)       |
| `zh-cn` | Chinese (China)       |
| `fr-fr` | French (France)       |
| `de-de` | German (Germany)      |
| `ja-jp` | Japanese (Japan)      |
| `ru-ru` | Russian (Russia)      |
| `ko-kr` | Korean (South Korea)  |
| `es-es` | Spanish (Spain)       |
| `es-mx` | Spanish (Mexico)      |
| `pt-pt` | Portuguese (Portugal) |
| `pt-br` | Portuguese (Brazil)   |
| `ar-sa` | Arabic (Saudi Arabia) |
| `id-id` | Indonesian (ID)       |
| `hi-in` | Hindi (India)         |
| `nl-nl` | Dutch (Netherlands)   |
| `ar-xa` | Arabic (Pan-Arabic)   |
| `ar-sy` | Arabic (Syria)        |
| `it-it` | Italian (Italy)       |
| `ar-eg` | Arabic (Egypt)        |
| `ta-in` | Tamil (India)         |
| `te-in` | Telugu (India)        |
| `bn-in` | Bengali (India)       |
| `ar-ma` | Arabic (Morocco)      |
| `mr-in` | Marathi (India)       |
| `kn-in` | Kannada (India)       |
| `bn-bd` | Bengali (Bangladesh)  |
| `as-in` | Assamese (India)      |
| `ml-in` | Malayalam (India)     |
| `fr-ca` | French (Canada)       |
| `pl-pl` | Polish (Poland)       |
| `tr-tr` | Turkish (Turkey)      |
| `pa-in` | Punjabi (India)       |

## MARS 8.1 Beta Models

Supported in `mars-8.1-flash-beta` and `mars-8.1-pro-beta`. **312 languages supported.**

| Code             | Language                                  |
| :--------------- | :---------------------------------------- |
| `en-us`          | English (USA)                             |
| `af-za`          | Afrikaans (South Africa)                  |
| `am-et`          | Amharic (Ethiopia)                        |
| `ar-ae`          | Arabic (UAE)                              |
| `ar-bh`          | Arabic (Bahrain)                          |
| `ar-dz`          | Arabic (Algeria)                          |
| `ar-eg`          | Arabic (Egypt)                            |
| `ar-iq`          | Arabic (Iraq)                             |
| `ar-jo`          | Arabic (Jordan)                           |
| `ar-kw`          | Arabic (Kuwait)                           |
| `ar-lb`          | Arabic (Lebanon)                          |
| `ar-ly`          | Arabic (Libya)                            |
| `ar-ma`          | Arabic (Morocco)                          |
| `ar-om`          | Arabic (Oman)                             |
| `ar-qa`          | Arabic (Qatar)                            |
| `ar-sa`          | Arabic (Saudi Arabia)                     |
| `ar-sy`          | Arabic (Syria)                            |
| `ar-tn`          | Arabic (Tunisia)                          |
| `ar-ye`          | Arabic (Yemen)                            |
| `az-az`          | Azerbaijani (Azerbaijan)                  |
| `bg-bg`          | Bulgarian (Bulgaria)                      |
| `bn-bd`          | Bengali (Bangladesh)                      |
| `bn-in`          | Bengali (India)                           |
| `bs-ba`          | Bosnian (Bosnia & Herz.)                  |
| `ca-es`          | Catalan (Spain)                           |
| `cs-cz`          | Czech (Czechia)                           |
| `cy-gb`          | Welsh (United Kingdom)                    |
| `da-dk`          | Danish (Denmark)                          |
| `de-at`          | German (Austria)                          |
| `de-ch`          | German (Switzerland)                      |
| `de-de`          | German (Germany)                          |
| `el-gr`          | Greek (Greece)                            |
| `en-au`          | English (Australia)                       |
| `en-ca`          | English (Canada)                          |
| `en-gb`          | English (United Kingdom)                  |
| `en-hk`          | English (Hong Kong)                       |
| `en-ie`          | English (Ireland)                         |
| `en-in`          | English (India)                           |
| `en-ke`          | English (Kenya)                           |
| `en-ng`          | English (Nigeria)                         |
| `en-nz`          | English (New Zealand)                     |
| `en-ph`          | English (Philippines)                     |
| `en-sg`          | English (Singapore)                       |
| `en-tz`          | English (Tanzania)                        |
| `en-za`          | English (South Africa)                    |
| `es-ar`          | Spanish (Argentina)                       |
| `es-bo`          | Spanish (Bolivia)                         |
| `es-cl`          | Spanish (Chile)                           |
| `es-co`          | Spanish (Colombia)                        |
| `es-cr`          | Spanish (Costa Rica)                      |
| `es-cu`          | Spanish (Cuba)                            |
| `es-do`          | Spanish (Dominican Rep.)                  |
| `es-ec`          | Spanish (Ecuador)                         |
| `es-es`          | Spanish (Spain)                           |
| `es-gq`          | Spanish (Eq. Guinea)                      |
| `es-gt`          | Spanish (Guatemala)                       |
| `es-hn`          | Spanish (Honduras)                        |
| `es-mx`          | Spanish (Mexico)                          |
| `es-ni`          | Spanish (Nicaragua)                       |
| `es-pa`          | Spanish (Panama)                          |
| `es-pe`          | Spanish (Peru)                            |
| `es-pr`          | Spanish (Puerto Rico)                     |
| `es-py`          | Spanish (Paraguay)                        |
| `es-sv`          | Spanish (El Salvador)                     |
| `es-us`          | Spanish (USA)                             |
| `es-uy`          | Spanish (Uruguay)                         |
| `es-ve`          | Spanish (Venezuela)                       |
| `et-ee`          | Estonian (Estonia)                        |
| `eu-es`          | Basque (Spain)                            |
| `fa-ir`          | Persian (Iran)                            |
| `fi-fi`          | Finnish (Finland)                         |
| `fil-ph`         | Filipino (Philippines)                    |
| `fr-be`          | French (Belgium)                          |
| `fr-ca`          | French (Canada)                           |
| `fr-ch`          | French (Switzerland)                      |
| `fr-fr`          | French (France)                           |
| `ga-ie`          | Irish (Ireland)                           |
| `gl-es`          | Galician (Spain)                          |
| `gu-in`          | Gujarati (India)                          |
| `he-il`          | Hebrew (Israel)                           |
| `hi-in`          | Hindi (India)                             |
| `hr-hr`          | Croatian (Croatia)                        |
| `hu-hu`          | Hungarian (Hungary)                       |
| `hy-am`          | Armenian (Armenia)                        |
| `id-id`          | Indonesian (ID)                           |
| `is-is`          | Icelandic (Iceland)                       |
| `it-it`          | Italian (Italy)                           |
| `ja-jp`          | Japanese (Japan)                          |
| `jv-id`          | Javanese (ID)                             |
| `ka-ge`          | Georgian (Georgia)                        |
| `kk-kz`          | Kazakh (Kazakhstan)                       |
| `km-kh`          | Khmer (Cambodia)                          |
| `kn-in`          | Kannada (India)                           |
| `ko-kr`          | Korean (South Korea)                      |
| `lo-la`          | Lao (Laos)                                |
| `lt-lt`          | Lithuanian (Lithuania)                    |
| `lv-lv`          | Latvian (Latvia)                          |
| `mk-mk`          | Macedonian (N. Macedonia)                 |
| `ml-in`          | Malayalam (India)                         |
| `mn-mn`          | Mongolian (Mongolia)                      |
| `mr-in`          | Marathi (India)                           |
| `ms-my`          | Malay (Malaysia)                          |
| `mt-mt`          | Maltese (Malta)                           |
| `my-mm`          | Burmese (Myanmar)                         |
| `nb-no`          | Norwegian Bokmål (Norway)                 |
| `nl-be`          | Dutch (Belgium)                           |
| `nl-nl`          | Dutch (Netherlands)                       |
| `pl-pl`          | Polish (Poland)                           |
| `ps-af`          | Pashto (Afghanistan)                      |
| `pt-br`          | Portuguese (Brazil)                       |
| `pt-pt`          | Portuguese (Portugal)                     |
| `ro-ro`          | Romanian (Romania)                        |
| `ru-ru`          | Russian (Russia)                          |
| `si-lk`          | Sinhala (Sri Lanka)                       |
| `sk-sk`          | Slovak (Slovakia)                         |
| `sl-si`          | Slovenian (Slovenia)                      |
| `so-so`          | Somali (Somalia)                          |
| `sq-al`          | Albanian (Albania)                        |
| `sr-rs`          | Serbian (Serbia)                          |
| `sv-se`          | Swedish (Sweden)                          |
| `sw-ke`          | Swahili (Kenya)                           |
| `sw-tz`          | Swahili (Tanzania)                        |
| `ta-in`          | Tamil (India)                             |
| `ta-lk`          | Tamil (Sri Lanka)                         |
| `ta-my`          | Tamil (Malaysia)                          |
| `ta-sg`          | Tamil (Singapore)                         |
| `te-in`          | Telugu (India)                            |
| `th-th`          | Thai (Thailand)                           |
| `tr-tr`          | Turkish (Turkey)                          |
| `uk-ua`          | Ukrainian (Ukraine)                       |
| `ur-in`          | Urdu (India)                              |
| `ur-pk`          | Urdu (Pakistan)                           |
| `uz-uz`          | Uzbek (Uzbekistan)                        |
| `vi-vn`          | Vietnamese (Vietnam)                      |
| `zh-cn`          | Chinese (China)                           |
| `zh-cn-henan`    | Chinese (China, Henan)                    |
| `zh-cn-liaoning` | Chinese (China, Liaoning)                 |
| `zh-cn-shaanxi`  | Chinese (China, Shaanxi)                  |
| `zh-cn-shandong` | Chinese (China, Shandong)                 |
| `zh-cn-sichuan`  | Chinese (China, Sichuan)                  |
| `zh-hk`          | Chinese (Hong Kong)                       |
| `zh-tw`          | Chinese (Taiwan)                          |
| `zu-za`          | Zulu (South Africa)                       |
| `pa-in`          | Punjabi (India)                           |
| `sa-in`          | Sanskrit (India)                          |
| `ar-xa`          | Arabic (Pan-Arabic)                       |
| `tl-ph`          | Tagalog (Philippines)                     |
| `es-xl`          | Spanish (Latin America)                   |
| `as-in`          | Assamese (India)                          |
| `or-in`          | Odia (India)                              |
| `mai-in`         | Maithili (India)                          |
| `sd-in`          | Sindhi (India)                            |
| `kok-in`         | Konkani (India)                           |
| `mni-in`         | Manipuri (India)                          |
| `ks-in`          | Kashmiri (India)                          |
| `doi-in`         | Dogri (India)                             |
| `brx-in`         | Bodo (India)                              |
| `sat-in`         | Santali (India)                           |
| `yue-hk`         | Cantonese (Hong Kong)                     |
| `no-no`          | Norwegian (Norway)                        |
| `rw-rw`          | Kinyarwanda (Rwanda)                      |
| `be-by`          | Belarusian (Belarus)                      |
| `eo-xx`          | Esperanto (Generic)                       |
| `kab-dz`         | Kabyle (Algeria)                          |
| `lg-ug`          | Ganda (Uganda)                            |
| `ug-cn`          | Uighur (China)                            |
| `mhr-ru`         | Eastern Mari (Russia)                     |
| `ba-ru`          | Bashkir (Russia)                          |
| `ars-sa`         | Najdi Arabic (Saudi Arabia)               |
| `npi-np`         | Nepali (Nepal)                            |
| `ckb-iq`         | Central Kurdish (Iraq)                    |
| `dgo-in`         | Dogri (India)                             |
| `knn-in`         | Konkani (India)                           |
| `kbd-ru`         | Kabardian (Russia)                        |
| `ary-ma`         | Moroccan Arabic (Morocco)                 |
| `afb-kw`         | Gulf Arabic (Kuwait)                      |
| `bo-cn`          | Tibetan (China)                           |
| `fy-nl`          | Western Frisian (Netherlands)             |
| `kmr-xx`         | Northern Kurdish (Generic)                |
| `ab-ge`          | Abkhazian (Georgia)                       |
| `adx-cn`         | Amdo Tibetan (China)                      |
| `ky-kg`          | Kirghiz (Kyrgyzstan)                      |
| `kln-xx`         | Kalenjin (Generic)                        |
| `dv-mv`          | Dhivehi (Maldives)                        |
| `luo-xx`         | Luo (Generic)                             |
| `ady-ru`         | Adyghe (Russia)                           |
| `mrj-xx`         | Western Mari (Generic)                    |
| `tt-ru`          | Tatar (Russia)                            |
| `ltg-xx`         | Latgalian (Generic)                       |
| `br-fr`          | Breton (France)                           |
| `phr-xx`         | Pahari-Potwari (Generic)                  |
| `cv-ru`          | Chuvash (Russia)                          |
| `arz-eg`         | Egyptian Arabic (Egypt)                   |
| `gui-bo`         | Eastern Bolivian Guaraní (Bolivia)        |
| `acw-sa`         | Hijazi Arabic (Saudi Arabia)              |
| `acx-xx`         | Omani Arabic (Generic)                    |
| `orc-xx`         | Orma (Generic)                            |
| `mvy-xx`         | Indus Kohistani (Generic)                 |
| `aeb-xx`         | Tunisian Arabic (Generic)                 |
| `gjk-xx`         | Kachi Koli (Generic)                      |
| `phl-xx`         | Phalura (Generic)                         |
| `odk-xx`         | Od (Generic)                              |
| `lus-xx`         | Lushai (Generic)                          |
| `ayl-xx`         | Libyan Arabic (Generic)                   |
| `fue-ne`         | Borgu Fulfulde (Niger)                    |
| `hno-xx`         | Northern Hindko (Generic)                 |
| `kxp-xx`         | Wadiyara Koli (Generic)                   |
| `brh-pk`         | Brahui (Pakistan)                         |
| `plt-xx`         | Plateau Malagasy (Generic)                |
| `gbm-in`         | Garhwali (India)                          |
| `bmm-xx`         | Northern Betsimisaraka Malagasy (Generic) |
| `rof-xx`         | Rombo (Generic)                           |
| `ydd-xx`         | Eastern Yiddish (Generic)                 |
| `mi-nz`          | Maori (New Zealand)                       |
| `ln-cd`          | Lingala (DR Congo)                        |
| `xmv-mg`         | Antankarana Malagasy (Madagascar)         |
| `tkg-xx`         | Tesaka Malagasy (Generic)                 |
| `ha-ng`          | Hausa (Nigeria)                           |
| `nan-xx`         | Min Nan Chinese (Generic)                 |
| `bzc-xx`         | Southern Betsimisaraka Malagasy (Generic) |
| `oc-fr`          | Occitan (France)                          |
| `oru-xx`         | Ormuri (Generic)                          |
| `ksf-cm`         | Bafia (Cameroon)                          |
| `an-es`          | Aragonese (Spain)                         |
| `bft-pk`         | Balti (Pakistan)                          |
| `nnh-xx`         | Ngiemboon (Generic)                       |
| `sah-xx`         | Yakut (Generic)                           |
| `pms-xx`         | Piemontese (Generic)                      |
| `lij-xx`         | Ligurian (Generic)                        |
| `yo-ng`          | Yoruba (Nigeria)                          |
| `vro-xx`         | Võro (Generic)                            |
| `apc-xx`         | Levantine Arabic (Generic)                |
| `khw-xx`         | Khowar (Generic)                          |
| `uzn-xx`         | Northern Uzbek (Generic)                  |
| `fui-cm`         | Bagirmi Fulfulde (Cameroon)               |
| `bnm-cm`         | Batanga (Cameroon)                        |
| `trw-xx`         | Torwali (Generic)                         |
| `fuc-xx`         | Pulaar (Generic)                          |
| `kam-xx`         | Kamba (Generic)                           |
| `msh-xx`         | Masikoro Malagasy (Generic)               |
| `ff-sn`          | Fulah (Senegal)                           |
| `fuf-xx`         | Pular (Generic)                           |
| `pwn-xx`         | Paiwan (Generic)                          |
| `ig-xx`          | Igbo (Generic)                            |
| `ext-es`         | Extremaduran (Spain)                      |
| `tok-xx`         | Toki Pona (Generic)                       |
| `ia-xx`          | Interlingua (Generic)                     |
| `xh-za`          | Xhosa (South Africa)                      |
| `scn-xx`         | Sicilian (Generic)                        |
| `koo-xx`         | Konzo (Generic)                           |
| `fub-cm`         | Adamawa Fulfulde (Cameroon)               |
| `plk-xx`         | Kohistani Shina (Generic)                 |
| `ewo-cm`         | Ewondo (Cameroon)                         |
| `nso-xx`         | Pedi (Generic)                            |
| `gby-ng`         | Gbari (Nigeria)                           |
| `gdf-ng`         | Guduf-Gava (Nigeria)                      |
| `ceb-ph`         | Cebuano (Philippines)                     |
| `gwt-af`         | Gawar-Bati (Afghanistan)                  |
| `kw-gb`          | Cornish (United Kingdom)                  |
| `bhr-mg`         | Bara Malagasy (Madagascar)                |
| `dua-cm`         | Duala (Cameroon)                          |
| `gbr-ng`         | Gbagyi (Nigeria)                          |
| `txy-xx`         | Tanosy Malagasy (Generic)                 |
| `mxu-xx`         | Mada (Cameroon)                           |
| `kna-ng`         | Dera (Nigeria)                            |
| `kfp-xx`         | Korwa (Generic)                           |
| `its-xx`         | Isekiri (Generic)                         |
| `haw-us`         | Hawaiian (USA)                            |
| `tcy-xx`         | Tulu (Generic)                            |
| `bjn-id`         | Banjar (ID)                               |
| `wbl-xx`         | Wakhi (Generic)                           |
| `pbt-xx`         | Southern Pashto (Generic)                 |
| `xmw-xx`         | Tsimihety Malagasy (Generic)              |
| `szy-xx`         | Sakizaya (Generic)                        |
| `xmf-xx`         | Mingrelian (Generic)                      |
| `twu-xx`         | Termanu (Generic)                         |
| `nlv-xx`         | Orizaba Nahuatl (Generic)                 |
| `qxw-xx`         | Jauja Wanca Quechua (Generic)             |
| `pst-af`         | Central Pashto (Afghanistan)              |
| `wji-xx`         | Warji (Generic)                           |
| `fat-gh`         | Fanti (Ghana)                             |
| `bhh-il`         | Bukharic (Israel)                         |
| `tlp-mx`         | Filomena Mata-Coahuitlán Totonac (Mexico) |
| `ldb-ng`         | Dũya (Nigeria)                            |
| `ndi-xx`         | Samba Leko (Generic)                      |
| `elm-ng`         | Eleme (Nigeria)                           |
| `jns-xx`         | Jaunsari (Generic)                        |
| `hwo-xx`         | Hwana (Generic)                           |
| `bbl-ge`         | Bats (Georgia)                            |
| `afo-ng`         | Eloyi (Nigeria)                           |
| `abb-cm`         | Bankon (Cameroon)                         |
| `jal-xx`         | Yalahatan (Generic)                       |
| `idu-xx`         | Idoma (Generic)                           |
| `bew-id`         | Betawi (ID)                               |
| `qup-xx`         | Southern Pastaza Quechua (Generic)        |
| `noe-xx`         | Nimadi (Generic)                          |
| `byc-xx`         | Ubaghara (Generic)                        |
| `bug-id`         | Buginese (ID)                             |
| `btm-id`         | Batak Mandailing (ID)                     |
| `hia-xx`         | Lamang (Generic)                          |
| `deg-ng`         | Degema (Nigeria)                          |
| `kvx-xx`         | Parkari Koli (Generic)                    |
| `pcm-xx`         | Nigerian Pidgin (Generic)                 |
| `ijn-xx`         | Kalabari (Generic)                        |
| `ala-ng`         | Alago (Nigeria)                           |
| `pbu-xx`         | Northern Pashto (Generic)                 |
| `bjj-xx`         | Kanauji (Generic)                         |
| `cjk-ao`         | Chokwe (Angola)                           |
| `mrr-xx`         | Maria (India)                             |
| `qvi-xx`         | Imbabura Highland Quichua (Generic)       |
| `bgp-pk`         | Eastern Balochi (Pakistan)                |
| `bag-xx`         | Tuki (Generic)                            |

## MARS-Instruct

Supported in `mars-instruct`. **142 languages supported.**

| Code             | Language                  |
| :--------------- | :------------------------ |
| `en-us`          | English (USA)             |
| `af-za`          | Afrikaans (South Africa)  |
| `am-et`          | Amharic (Ethiopia)        |
| `ar-ae`          | Arabic (UAE)              |
| `ar-bh`          | Arabic (Bahrain)          |
| `ar-dz`          | Arabic (Algeria)          |
| `ar-eg`          | Arabic (Egypt)            |
| `ar-iq`          | Arabic (Iraq)             |
| `ar-jo`          | Arabic (Jordan)           |
| `ar-kw`          | Arabic (Kuwait)           |
| `ar-lb`          | Arabic (Lebanon)          |
| `ar-ly`          | Arabic (Libya)            |
| `ar-ma`          | Arabic (Morocco)          |
| `ar-om`          | Arabic (Oman)             |
| `ar-qa`          | Arabic (Qatar)            |
| `ar-sa`          | Arabic (Saudi Arabia)     |
| `ar-sy`          | Arabic (Syria)            |
| `ar-tn`          | Arabic (Tunisia)          |
| `ar-ye`          | Arabic (Yemen)            |
| `az-az`          | Azerbaijani (Azerbaijan)  |
| `bg-bg`          | Bulgarian (Bulgaria)      |
| `bgc-in`         | Haryanvi (Haryana, India) |
| `bho-in`         | Bhojpuri (India)          |
| `bn-bd`          | Bengali (Bangladesh)      |
| `bn-in`          | Bengali (India)           |
| `ca-es`          | Catalan (Spain)           |
| `cs-cz`          | Czech (Czechia)           |
| `da-dk`          | Danish (Denmark)          |
| `de-at`          | German (Austria)          |
| `de-ch`          | German (Switzerland)      |
| `de-de`          | German (Germany)          |
| `el-gr`          | Greek (Greece)            |
| `en-au`          | English (Australia)       |
| `en-ca`          | English (Canada)          |
| `en-gb`          | English (United Kingdom)  |
| `en-hk`          | English (Hong Kong)       |
| `en-ie`          | English (Ireland)         |
| `en-in`          | English (India)           |
| `en-ke`          | English (Kenya)           |
| `en-ng`          | English (Nigeria)         |
| `en-nz`          | English (New Zealand)     |
| `en-ph`          | English (Philippines)     |
| `en-sg`          | English (Singapore)       |
| `en-tz`          | English (Tanzania)        |
| `en-za`          | English (South Africa)    |
| `es-ar`          | Spanish (Argentina)       |
| `es-bo`          | Spanish (Bolivia)         |
| `es-cl`          | Spanish (Chile)           |
| `es-co`          | Spanish (Colombia)        |
| `es-cr`          | Spanish (Costa Rica)      |
| `es-cu`          | Spanish (Cuba)            |
| `es-do`          | Spanish (Dominican Rep.)  |
| `es-ec`          | Spanish (Ecuador)         |
| `es-es`          | Spanish (Spain)           |
| `es-gq`          | Spanish (Eq. Guinea)      |
| `es-gt`          | Spanish (Guatemala)       |
| `es-hn`          | Spanish (Honduras)        |
| `es-mx`          | Spanish (Mexico)          |
| `es-ni`          | Spanish (Nicaragua)       |
| `es-pa`          | Spanish (Panama)          |
| `es-pe`          | Spanish (Peru)            |
| `es-pr`          | Spanish (Puerto Rico)     |
| `es-py`          | Spanish (Paraguay)        |
| `es-sv`          | Spanish (El Salvador)     |
| `es-us`          | Spanish (USA)             |
| `es-uy`          | Spanish (Uruguay)         |
| `es-ve`          | Spanish (Venezuela)       |
| `et-ee`          | Estonian (Estonia)        |
| `eu-es`          | Basque (Spain)            |
| `fa-ir`          | Persian (Iran)            |
| `fi-fi`          | Finnish (Finland)         |
| `fr-be`          | French (Belgium)          |
| `fr-ca`          | French (Canada)           |
| `fr-ch`          | French (Switzerland)      |
| `fr-fr`          | French (France)           |
| `gl-es`          | Galician (Spain)          |
| `gu-in`          | Gujarati (India)          |
| `he-il`          | Hebrew (Israel)           |
| `hi-in`          | Hindi (India)             |
| `hr-hr`          | Croatian (Croatia)        |
| `hu-hu`          | Hungarian (Hungary)       |
| `hy-am`          | Armenian (Armenia)        |
| `id-id`          | Indonesian (ID)           |
| `is-is`          | Icelandic (Iceland)       |
| `it-it`          | Italian (Italy)           |
| `ja-jp`          | Japanese (Japan)          |
| `jv-id`          | Javanese (ID)             |
| `ka-ge`          | Georgian (Georgia)        |
| `kn-in`          | Kannada (India)           |
| `ko-kr`          | Korean (South Korea)      |
| `lo-la`          | Lao (Laos)                |
| `lt-lt`          | Lithuanian (Lithuania)    |
| `lv-lv`          | Latvian (Latvia)          |
| `mk-mk`          | Macedonian (N. Macedonia) |
| `ml-in`          | Malayalam (India)         |
| `mn-mn`          | Mongolian (Mongolia)      |
| `mr-in`          | Marathi (India)           |
| `ms-my`          | Malay (Malaysia)          |
| `my-mm`          | Burmese (Myanmar)         |
| `nb-no`          | Norwegian Bokmål (Norway) |
| `ne-np`          | Nepali (Nepal)            |
| `nl-be`          | Dutch (Belgium)           |
| `nl-nl`          | Dutch (Netherlands)       |
| `pl-pl`          | Polish (Poland)           |
| `ps-af`          | Pashto (Afghanistan)      |
| `pt-br`          | Portuguese (Brazil)       |
| `pt-pt`          | Portuguese (Portugal)     |
| `ro-ro`          | Romanian (Romania)        |
| `ru-ru`          | Russian (Russia)          |
| `si-lk`          | Sinhala (Sri Lanka)       |
| `sk-sk`          | Slovak (Slovakia)         |
| `sl-si`          | Slovenian (Slovenia)      |
| `sq-al`          | Albanian (Albania)        |
| `sr-rs`          | Serbian (Serbia)          |
| `sv-se`          | Swedish (Sweden)          |
| `sw-ke`          | Swahili (Kenya)           |
| `sw-tz`          | Swahili (Tanzania)        |
| `ta-in`          | Tamil (India)             |
| `ta-lk`          | Tamil (Sri Lanka)         |
| `ta-my`          | Tamil (Malaysia)          |
| `ta-sg`          | Tamil (Singapore)         |
| `te-in`          | Telugu (India)            |
| `th-th`          | Thai (Thailand)           |
| `tr-tr`          | Turkish (Turkey)          |
| `uk-ua`          | Ukrainian (Ukraine)       |
| `ur-in`          | Urdu (India)              |
| `ur-pk`          | Urdu (Pakistan)           |
| `vi-vn`          | Vietnamese (Vietnam)      |
| `zh-cn`          | Chinese (China)           |
| `zh-cn-henan`    | Chinese (China, Henan)    |
| `zh-cn-liaoning` | Chinese (China, Liaoning) |
| `zh-cn-shaanxi`  | Chinese (China, Shaanxi)  |
| `zh-cn-shandong` | Chinese (China, Shandong) |
| `zh-cn-sichuan`  | Chinese (China, Sichuan)  |
| `zh-hk`          | Chinese (Hong Kong)       |
| `pa-in`          | Punjabi (India)           |
| `ar-xa`          | Arabic (Pan-Arabic)       |
| `tl-ph`          | Tagalog (Philippines)     |
| `es-xl`          | Spanish (Latin America)   |
| `or-in`          | Odia (India)              |
| `sd-in`          | Sindhi (India)            |
| `be-by`          | Belarusian (Belarus)      |


# MARS 8 TTS Models
Source: https://docs.camb.ai/models



The **MARS 8** family consists of **zero-shot, multilingual Text-to-Speech (TTS) models** designed to cover a wide range of production needs. Each model varies in **latency, quality, controllability, and ideal use case**, allowing you to choose the right fit for your application.

Plus, MARS-Pro and MARS-Flash models are available on all [major cloud providers.](/custom-cloud-providers)

## Model Summary

| Model                   | Sample Rate        | Notes                                                                                                                                                                                                                                                                                  |
| :---------------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **mars-8.1-flash-beta** | **48kHz**          | Beta MARS 8.1 model, optimized for faster generation. Try this model when quality is the priority, as it may perform much better for pronunciation, expressiveness with high-pitch references, overall prosody, accent control, accent coverage, and quality across different accents. |
| **mars-8.1-pro-beta**   | **48kHz**          | Beta MARS Pro model. Try this model when quality is the priority, as it may perform much better for pronunciation, expressiveness with high-pitch references, overall prosody, accent control, accent coverage, and quality across different accents.                                  |
| **mars-flash**          | **22.05kHz/48kHz** | Ultra-low latency TTS for real-time agents, call center agents, and live conversational assistants.                                                                                                                                                                                    |
| **mars-pro**            | **48kHz**          | Balanced speed and fidelity for expressive real-time speech, dubbing, audiobooks, and digital media.                                                                                                                                                                                   |
| **mars-instruct**       | **22.05kHz**       | Director-level emotional and prosodic control with embedded expressive text tags.                                                                                                                                                                                                      |

## MARS-8.1-Flash-Beta (48khz)

**Faster preview access to MARS 8.1 quality improvements**

* **Model ID:** `mars-8.1-flash-beta`
* **Primary Use Cases:**
  * Faster evaluation of MARS 8.1 generation quality
  * Lower-latency workflows that still need stronger accent handling
  * Comparing output quality and speed against `mars-flash` and `mars-8.1-pro-beta`
* **Quality Improvements:** Provides the same quality as MARS 8.1, including much better quality across different accents, while being faster than `mars-8.1-pro-beta`.
* **Notes:** This is a beta model. For both MARS 8.1 beta models, your target language should use a reference voice in the same language and accent for the best results. Test with your target voices, languages, accents, and audio formats before using either beta model in production workflows.

## MARS-8.1-Pro-Beta (48khz)

**Preview access to the newest Pro-quality speech model**

* **Model ID:** `mars-8.1-pro-beta`
* **Primary Use Cases:**
  * Evaluating the latest MARS Pro generation quality
  * High-fidelity TTS experiments before production rollout
  * Comparing output quality against `mars-pro`
* **Quality Improvements:** May perform much better than `mars-pro` for pronunciation, overall prosody, accent control, accent coverage, and quality across different accents. It is also designed to improve expressiveness, especially for high-pitch reference voices.
* **Notes:** This is a beta model. For MARS 8.1 beta models, your target language should use a reference voice in the same language and accent for the best results. Test it with your target voices, languages, accents, and audio formats before using it in production workflows.

## MARS-Flash (22.05khz/48khz)

**Ultra-low latency TTS for real-time agents and assistants**

* **Parameters:** 600M
* **TTFB:** As low as **150 ms** on certain GPUs like Blackwell
* **Primary Use Cases:**
  * Agentic conversations
  * Call center agents
  * Live conversational assistants

## MARS-Pro (48khz)

**Balanced speed and fidelity for expressive real-time speech**

* **Parameters:** 600M
* **TTFB:** **800 ms – 2 s**
* **Primary Use Cases:**
  * Real-time translation with voice and emotion transfer
  * Expressive dubbing
  * Audiobooks and digital media
* **Notes:** Delivers best overall performance when speed is not the primary constraint, especially with short or challenging reference audio.

## MARS-Instruct (22.05khz)

**Director-level emotional and prosodic control**

* **Parameters:** 1.2B
* **TTFB:** Higher latency (not intended for real-time use)
* **Primary Use Cases:**
  * High-end TV and film production
  * Movie dubbing and post-production editing
* **Capabilities:**
  * Independent control of speaker identity and prosody
  * Style and emotion can be tuned using both:
  * A reference audio sample
  * A textual description of desired prosody

## MARS-Nano

**Highly efficient TTS for on-device deployment**

* **Parameters:** 50M
* **TTFB:** **500 ms – 2 s**, depending on available compute
* **Primary Use Cases:**
  * On-device applications
  * Environments with strict memory and compute constraints
* **Deployment Notes:** Currently deployed with partners and providers such as [**Broadcom**](https://www.camb.ai/blog-post/broadcom-parters-with-camb-ai).

### Tips For Best Results:

* For texts with numbers expand the numbers to words. For example, instead of "123" to "one hundred twenty three" or "one two three" as you need.
* For code-switched sentences, perform transliteration to convert the text to your chosen TTS language. We're improving the model to handle above nuances better, but we find that practically most LLM outputs feeding in already have the conversions. We've focused more on other parameters related to quality.

### Advanced Customization

Fine-tune the audio with additional parameters to control the performance, style, and quality of the generated speech.

These can be sent in the payload. More details available in the [API Reference](/api-reference/endpoint/create-tts-stream).

* **`user_instructions`**: Guide the voice's delivery (e.g., "Warm, clear, and conversational"). Only supported with `mars-instruct`.
* **`output_configuration`**: Set the audio format (`wav`, `mp3`), and apply enhancements.
* **`voice_settings`**: Enhance reference audio quality, maintain the source accent, or adjust the speaking rate.
* **`inference_options`**: Adjust stability, temperature, and speaker similarity for unique results.

## Language Support

**MARS-8.1-Flash-Beta, MARS-8.1-Pro-Beta, MARS-Flash, MARS-Pro, and MARS-Instruct** are released across multiple languages, collectively covering **99% of the world's speaking population**.

Coverage varies by model:

| Model                                      | Languages |
| :----------------------------------------- | :-------- |
| `mars-flash`, `mars-pro`                   | 33        |
| `mars-8.1-flash-beta`, `mars-8.1-pro-beta` | 312       |
| `mars-instruct`                            | 142       |

See the full per-model locale list in [Language Support](/language-support).


# Open Source
Source: https://docs.camb.ai/open-source

Explore our state-of-the-art open source speech models.

At Camb AI, we believe in democratizing access to powerful voice technology. We've released significant portions of our research as open-source models, allowing the community to build, experiment, and innovate.

## MARS 6 Turbo

**MARS6: A Small and Robust Hierarchical-Codec Text-to-Speech Model**

MARS 6 Turbo represents the latest evolution in our open-source speech synthesis technology. It delivers robust performance with a hierarchical codec architecture, optimized for efficiency without compromising on quality.

### Resources

* **Demo & Samples**: [Project Page](https://camb-ai.github.io/mars6-turbo/)
* **Research Paper**: [arXiv:2501.05787](https://arxiv.org/abs/2501.05787)
* **Website**: [https://camb.ai](https://camb.ai)

<Card title="MARS 6 Turbo GitHub" icon="github" href="https://github.com/Camb-ai/mars6-turbo">
  Access the model weights, inference code, and technical documentation.
</Card>

## MARS 5

[MARS 5](https://github.com/camb-ai/mars5-tts) remains a powerful tool in our open-source suite, offering a transformer-based architecture for flexible speech generation.

### Key Features

* **Flexible Prosody**: Context-aware rhythm and intonation.
* **Voice Cloning**: Zero-shot cloning with short reference audio.
* **Multilingual Support**: Diverse language and accent capabilities.

<Card title="MARS 5 GitHub Repository" icon="github" href="https://github.com/camb-ai/mars5-tts">
  Check out the MARS 5 code and models.
</Card>

## Community & Contribution

We welcome contributions! Whether it's adding support for new languages, optimizing inference, or building new applications on top of MARS, join us on GitHub to shape the future of open-source speech AI.


# Installation
Source: https://docs.camb.ai/other-products/chatterbox/installation

Install the Chatterbox Desktop App for Windows from CAMB AI Studio.

This guide walks you through installing the Chatterbox Desktop App for Windows from CAMB AI Studio. Follow each step in order — the process is quick and safe, and you can always go back if you need to review a setting.

<Warning>
  A system reboot is **mandatory** at the end of the installation so that the virtual audio drivers can be correctly installed and activated. If you skip the reboot, the app will not function as expected.
</Warning>

## Step 1 — Open CAMB AI Studio in your browser

1. Open your preferred web browser and sign in to [CAMB AI Studio](https://studio.camb.ai).
2. In the left-hand sidebar, scroll down to the **Platform** section.
3. Click **Integrations** to open the list of available integrations for your workspace.

<Frame>
  <img alt="CAMB AI Studio sidebar showing the Integrations option" />
</Frame>

## Step 2 — Download the Chatterbox Desktop App

1. On the Integrations page, find the **Chatterbox Desktop App** card.
2. Under the description, click the **Windows** button.
3. Your browser will begin downloading the Chatterbox installer. Wait until the download completes.

<Frame>
  <img alt="Chatterbox Desktop App card with the Windows download button" />
</Frame>

## Step 3 — Open the installer

1. Open File Explorer and navigate to your **Downloads** folder.
2. Locate the file named `Chatterbox-1.6.7-setup.exe` (the version number may differ).
3. Double-click the file to launch the installer. If Windows asks for permission, click **Yes**.

<Frame>
  <img alt="Chatterbox installer file in the Downloads folder" />
</Frame>

## Step 4 — Choose the installer language

A small window titled **Installer Language** appears. Make sure **English** (or your preferred language, if available) is selected, then click **OK**.

<Frame>
  <img alt="Installer Language selection dialog" />
</Frame>

## Step 5 — Start the Chatterbox Setup Wizard

The Chatterbox Setup welcome screen explains that the setup will guide you through the installation process. Click **Next** to proceed.

<Frame>
  <img alt="Chatterbox Setup welcome screen" />
</Frame>

## Step 6 — Review and accept the License Agreement

1. Review the terms on the **License Agreement** page.
2. Select **I accept the terms of the License Agreement**.
3. Click **Next** to continue.

<Frame>
  <img alt="License Agreement screen" />
</Frame>

## Step 7 — Confirm the installation location

The **Choose Install Location** screen shows where Chatterbox will be installed — by default `C:\Program Files\Chatterbox\`. For most users, keeping the default location is recommended.

If you need to change it, click **Browse…** and select a different folder. When you're satisfied, click **Next**.

<Frame>
  <img alt="Choose Install Location screen" />
</Frame>

## Step 8 — Configure Start Menu shortcuts

On the **Choose Start Menu Folder** screen, decide how Chatterbox appears in your Start Menu.

* The default folder name **Chatterbox** is usually best.
* If you prefer not to create any Start Menu shortcuts, check **Do not create shortcuts**.

When ready, click **Install** to begin the installation.

<Frame>
  <img alt="Choose Start Menu Folder screen" />
</Frame>

## Step 9 — Wait while installation completes

The installer now shows an **Installing** screen with a progress bar. Please wait while Chatterbox and its components (including the required audio drivers) are copied and configured. You don't need to do anything on this screen.

<Frame>
  <img alt="Installation progress screen" />
</Frame>

## Step 10 — Complete setup and reboot

When installation is complete, a **Completing Chatterbox Setup** screen appears with a prompt to restart your computer.

1. Select **Reboot now** (recommended).
2. Click **Finish** to close the installer and restart your computer.

<Frame>
  <img alt="Completing Chatterbox Setup screen with reboot prompt" />
</Frame>

<Info>
  Restarting your system is required so that the virtual audio drivers used by Chatterbox are correctly installed and activated.
</Info>

## What's next

After your computer reboots:

* Open Chatterbox from the Start Menu or desktop shortcut.
* Sign in with your CAMB AI Studio account to connect Chatterbox to your workspace.
* Continue to [Verify your setup](/other-products/chatterbox/setup-verification) to confirm the audio drivers are working before joining a live meeting.

If anything doesn't look as described above, you can safely close the installer and start again from your Downloads folder.


# Overview
Source: https://docs.camb.ai/other-products/chatterbox/overview

Real-time multilingual translation for your live meetings on Windows.

Chatterbox is the CAMB AI desktop app that brings live, multilingual translation into your everyday meetings. It installs a pair of virtual audio drivers on Windows, sits between your microphone and any meeting platform (Zoom, Microsoft Teams, Google Meet, and more), and translates your speech in real time so participants hear you in their preferred language.

## How it works

1. You speak into your normal microphone in your **"I Speak"** language.
2. Chatterbox transcribes, translates, and re-synthesizes the audio in the **"They Hear"** language.
3. The translated audio is routed through the **Chatterbox Virtual Microphone**, which the meeting platform picks up as your mic input.

Your participants hear you naturally in their language without installing anything on their end.

## Requirements

* **Operating system**: Windows 10 or 11.
* **CAMB AI Studio account**: sign in at [studio.camb.ai](https://studio.camb.ai) to download the installer and authenticate the app.
* **Headphones or earphones**: required during live sessions to prevent feedback loops between your speakers and microphone.
* **A reboot after install**: the virtual audio drivers only activate after a system restart.

## Get started

<CardGroup>
  <Card title="Install Chatterbox" icon="download" href="/other-products/chatterbox/installation">
    Step-by-step Windows installer walkthrough.
  </Card>

  <Card title="Verify your setup" icon="check-check" href="/other-products/chatterbox/setup-verification">
    Confirm virtual audio drivers are installed and working.
  </Card>

  <Card title="Use it in a meeting" icon="video" href="/other-products/chatterbox/using-chatterbox">
    Configure languages, audio devices, and start a live session.
  </Card>
</CardGroup>


# Realtime WebSocket events
Source: https://docs.camb.ai/other-products/chatterbox/realtime-websocket-events

Client and server event contracts for the Realtime WebSocket API.

The Realtime WebSocket API creates a real-time speech translation session over a single WebSocket connection. The client sends a session configuration first, then streams microphone audio with JSON events that contain base64-encoded audio. The server responds with session lifecycle events, transcripts, translated text, and translated audio.

For the interactive WebSocket playground, see [Realtime (WebSocket)](/api-reference/websockets/realtime).

## Endpoint

```http theme={null}
GET /v1/realtime?mode=fast
Host: realtime.camb.ai
x-api-key: <YOUR_API_KEY>
```

The request upgrades to a WebSocket connection. The `mode` query parameter is optional.

| Mode   | Notes                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `fast` | Default. Accepts audio almost immediately and translates with the lowest latency, but supports fewer languages.              |
| `slow` | Supports the full language list and translates more accurately, at the cost of a 30s+ cold boot before the session is ready. |

<Info>
  If `session.update.session.mode` is omitted, the server uses the `mode` query parameter. If both are omitted, the server uses `fast`.
</Info>

<Note>
  **Migrating from `model`.** `mode` replaced an earlier `model` parameter that took the engine codenames `lilac`, `violet`, `iris`, and `orchid`. Both the old parameter and the old values are still accepted, so existing integrations keep working — they resolve as follows, and the server logs a deprecation warning.

  | Retired value               | Resolves to |
  | --------------------------- | ----------- |
  | `iris`                      | `fast`      |
  | `lilac`, `violet`, `orchid` | `slow`      |

  `mode` wins if you send both. A value that was never valid is still rejected — the compatibility mapping covers the four codenames above, not arbitrary strings.
</Note>

## Session lifecycle

<Steps>
  <Step title="Open the WebSocket">
    Connect to `wss://realtime.camb.ai/v1/realtime`. Send your API key in the `x-api-key` request header when your WebSocket client supports custom headers.
  </Step>

  <Step title="Send `session.update` first">
    The first WebSocket message must be a JSON `session.update` event. The server waits up to 10 seconds for this initial event.
  </Step>

  <Step title="Wait for session activation">
    After authorization and activation, the server sends `session.created`, followed by `session.updated`.
  </Step>

  <Step title="Stream microphone audio">
    Send base64-encoded audio chunks with `input_audio_buffer.append`. The server forwards decoded audio bytes into the realtime pipeline.
  </Step>

  <Step title="Read realtime output">
    The server emits completed input transcripts, translated text deltas, final translated text, translated audio chunks, and audio completion events.
  </Step>
</Steps>

Only text WebSocket messages are parsed as realtime events. Binary messages and Pong frames are ignored. Ping frames receive Pong replies.

## Authentication

Prefer the `x-api-key` WebSocket request header.

```http theme={null}
x-api-key: <YOUR_API_KEY>
```

You can also send credentials in the initial `session.update` event.

<CodeGroup>
  ```json API key auth theme={null}
  {
    "type": "session.update",
    "session": {
      "mode": "fast",
      "source_language": "en-US",
      "target_language": "de-DE",
      "output_modalities": ["text", "audio"]
    },
    "auth": {
      "api_key": "<YOUR_API_KEY>"
    }
  }
  ```
</CodeGroup>

<Info>
  If the request header and `auth` object are both present, the request header credential is used.
</Info>

## Limits

| Limit                                                         | Value                      |
| ------------------------------------------------------------- | -------------------------- |
| Initial `session.update` timeout                              | 10 seconds                 |
| Maximum client event text size                                | 1 MiB                      |
| Maximum decoded audio payload per `input_audio_buffer.append` | 256 KiB                    |
| Audio encoding in `input_audio_buffer.append.audio`           | Base64-encoded audio bytes |

## Session configuration

Send the active session settings in `session.update.session`.

```json theme={null}
{
  "mode": "fast",
  "source_language": "en-US",
  "target_language": "de-DE",
  "output_modalities": ["text", "audio"]
}
```

| Field               | Type      | Required | Notes                                                                          |
| ------------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `mode`              | string    | No       | Defaults to the `mode` query parameter, then `fast`. Must be `fast` or `slow`. |
| `source_language`   | string    | Yes      | Source language tag, for example `en-US`.                                      |
| `target_language`   | string    | Yes      | Target language tag, for example `de-DE`.                                      |
| `output_modalities` | string\[] | No       | Defaults to `["text", "audio"]`.                                               |

## Client events

| Event                       | When to send it                  | Support                      |
| --------------------------- | -------------------------------- | ---------------------------- |
| `session.update`            | First message on the connection. | Required for activation.     |
| `input_audio_buffer.append` | After the session is active.     | Supported.                   |
| `input_audio_buffer.clear`  | Not available in this version.   | Recognized, returns `error`. |
| `input_audio_buffer.commit` | Not available in this version.   | Recognized, returns `error`. |
| `response.cancel`           | Not available in this version.   | Recognized, returns `error`. |

### `session.update`

Initializes the realtime session. This must be the first client event.

```json theme={null}
{
  "type": "session.update",
  "session": {
    "mode": "fast",
    "source_language": "en-US",
    "target_language": "de-DE",
    "output_modalities": ["text", "audio"]
  }
}
```

After activation, sending another `session.update` is recognized but not supported. The server responds with an `error` event.

```json theme={null}
{
  "type": "error",
  "error": {
    "message": "session.update after activation is not supported in this version"
  }
}
```

### `input_audio_buffer.append`

Appends audio bytes to the realtime input stream.

```json theme={null}
{
  "type": "input_audio_buffer.append",
  "audio": "<base64_audio_bytes>"
}
```

The server base64-decodes `audio` and forwards the decoded bytes into the realtime pipeline. Each decoded payload can be up to 256 KiB.

### Unsupported client events

These events are recognized so clients can receive a structured error instead of silent failure.

<AccordionGroup>
  <Accordion title="input_audio_buffer.clear">
    ```json theme={null}
    {
      "type": "input_audio_buffer.clear"
    }
    ```

    Server response:

    ```json theme={null}
    {
      "type": "error",
      "error": {
        "message": "input_audio_buffer.clear is not supported in this version"
      }
    }
    ```
  </Accordion>

  <Accordion title="input_audio_buffer.commit">
    ```json theme={null}
    {
      "type": "input_audio_buffer.commit"
    }
    ```

    Server response:

    ```json theme={null}
    {
      "type": "error",
      "error": {
        "message": "input_audio_buffer.commit is not supported in this version"
      }
    }
    ```
  </Accordion>

  <Accordion title="response.cancel">
    ```json theme={null}
    {
      "type": "response.cancel"
    }
    ```

    Server response:

    ```json theme={null}
    {
      "type": "error",
      "error": {
        "message": "response.cancel is not supported in this version"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Server events

| Event                                                   | Description                                                                                    |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `session.created`                                       | Sent after the server authorizes, starts, and activates the realtime session.                  |
| `session.updated`                                       | Sent immediately after `session.created` with the active session configuration.                |
| `conversation.item.input_audio_transcription.completed` | Sent when the pipeline produces a completed user transcript.                                   |
| `response.text.delta`                                   | Sent for incremental assistant translation text. Deltas are additive for the current response. |
| `response.text.done`                                    | Sent when the final assistant translation text is available.                                   |
| `response.audio.delta`                                  | Sent when synthesized output audio bytes are available.                                        |
| `response.audio.done`                                   | Sent when the current assistant audio response is complete.                                    |
| `error`                                                 | Sent for recognized unsupported client events and billing stop decisions.                      |

### Session events

`session.created` includes the durable realtime session ID.

```json theme={null}
{
  "type": "session.created",
  "session": {
    "id": "2a4d3cb0-ff62-4e02-a37c-9fcf4e49c8cc",
    "mode": "fast",
    "source_language": "en-US",
    "target_language": "de-DE",
    "output_modalities": ["text", "audio"]
  }
}
```

`session.updated` confirms the active session configuration.

```json theme={null}
{
  "type": "session.updated",
  "session": {
    "mode": "fast",
    "source_language": "en-US",
    "target_language": "de-DE",
    "output_modalities": ["text", "audio"]
  }
}
```

| Field                       | Type        | Notes                                                      |
| --------------------------- | ----------- | ---------------------------------------------------------- |
| `session.id`                | UUID string | Durable realtime session ID. Present on `session.created`. |
| `session.mode`              | string      | Active mode, `fast` or `slow`.                             |
| `session.source_language`   | string      | Source language tag.                                       |
| `session.target_language`   | string      | Target language tag.                                       |
| `session.output_modalities` | string\[]   | Active output modalities.                                  |

### Transcript and response events

```json theme={null}
{
  "type": "conversation.item.input_audio_transcription.completed",
  "transcript": "Hello, how are you?"
}
```

```json theme={null}
{
  "type": "response.text.delta",
  "delta": "Guten"
}
```

```json theme={null}
{
  "type": "response.text.done",
  "text": "Guten Tag, wie geht es Ihnen?"
}
```

```json theme={null}
{
  "type": "response.audio.delta",
  "delta": "<base64_audio_bytes>"
}
```

```json theme={null}
{
  "type": "response.audio.done"
}
```

### Errors and billing stops

The server sends `error` for recognized but unsupported client events.

```json theme={null}
{
  "type": "error",
  "error": {
    "message": "input_audio_buffer.commit is not supported in this version"
  }
}
```

Billing can also stop a session. In that case, the server sends an `error` event whose `error.message` is the billing close reason, then ends the realtime loop. Active sessions are charged in billing windows and finalized on close, failure, or billing stop.

## Example message flow

<CodeGroup>
  ```json Client: session.update theme={null}
  {
    "type": "session.update",
    "session": {
      "mode": "fast",
      "source_language": "en-US",
      "target_language": "de-DE",
      "output_modalities": ["text", "audio"]
    }
  }
  ```

  ```json Server: session.created theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "2a4d3cb0-ff62-4e02-a37c-9fcf4e49c8cc",
      "mode": "fast",
      "source_language": "en-US",
      "target_language": "de-DE",
      "output_modalities": ["text", "audio"]
    }
  }
  ```

  ```json Server: session.updated theme={null}
  {
    "type": "session.updated",
    "session": {
      "mode": "fast",
      "source_language": "en-US",
      "target_language": "de-DE",
      "output_modalities": ["text", "audio"]
    }
  }
  ```

  ```json Client: append audio theme={null}
  {
    "type": "input_audio_buffer.append",
    "audio": "<base64_audio_bytes>"
  }
  ```

  ```json Server: transcript theme={null}
  {
    "type": "conversation.item.input_audio_transcription.completed",
    "transcript": "Hello, how are you?"
  }
  ```

  ```json Server: text delta theme={null}
  {
    "type": "response.text.delta",
    "delta": "Guten Tag"
  }
  ```

  ```json Server: text done theme={null}
  {
    "type": "response.text.done",
    "text": "Guten Tag, wie geht es Ihnen?"
  }
  ```

  ```json Server: audio delta theme={null}
  {
    "type": "response.audio.delta",
    "delta": "<base64_audio_bytes>"
  }
  ```

  ```json Server: audio done theme={null}
  {
    "type": "response.audio.done"
  }
  ```
</CodeGroup>


# Verify your setup
Source: https://docs.camb.ai/other-products/chatterbox/setup-verification

Confirm that Chatterbox and its virtual audio drivers are installed and working.

After completing the installation and rebooting your computer, it's a good idea to verify that Chatterbox and its **Virtual Audio Drivers** are installed and working correctly. The app includes a guided test that walks you through this in a few minutes.

## Step 1 — Open Chatterbox and start the test

1. Launch the **Chatterbox Desktop App** from your Start Menu or desktop.
2. Sign in with your CAMB AI Studio account if prompted.
3. On the **Home** screen, confirm that your **I Speak** and **They Hear** languages look reasonable — you can adjust them later.
4. At the bottom of the window, click **Test Setup** to start an automatic check of your audio configuration.

<Frame>
  <img alt="Chatterbox Home screen with the Test Setup button highlighted" />
</Frame>

## Step 2 — Verify that audio drivers are installed

A window titled **Audio Device Setup** appears on the **Drivers Test** step.

1. In the **Verify Audio Drivers** section, click **Verify**.
2. The app checks whether the required Virtual Audio Drivers were correctly installed during setup and the reboot.
3. Wait a few moments while the check runs.

<Frame>
  <img alt="Audio Device Setup window on the Drivers Test step" />
</Frame>

## Step 3 — Confirm driver installation success

When verification completes, you should see a green success message such as **Audio Drivers Installed Successfully** along with a green checkmark. This means your system has the required audio drivers installed and configured, and Chatterbox can route audio correctly through them.

Click **Next Step** to continue to the audio functionality test.

<Frame>
  <img alt="Audio Drivers Installed Successfully confirmation" />
</Frame>

## Step 4 — Test audio with the installed drivers

The next screen, **Audio Test**, lets you confirm the drivers are actually working, not just installed.

1. Ensure the speaker device at the top is set to the speakers or headphones you are currently using.
2. Click **Test Driver 1**. You should hear a short test tone. A green **Driver 1 Working** message confirms the first audio path is functioning.
3. Click **Test Driver 2**. Again, you should hear a short test tone. A green **Driver 2 Working** message confirms the second audio path is also functioning.
4. Once both tests succeed, click **Complete** to close the Audio Device Setup window.

<Frame>
  <img alt="Audio Test screen with Test Driver 1 and Test Driver 2 controls" />
</Frame>

<Check>
  With both driver tests passing, your Virtual Audio Drivers are correctly installed and fully operational. You're ready to start using Chatterbox in live meetings.
</Check>

Next, head to [Using Chatterbox](/other-products/chatterbox/using-chatterbox) to configure your languages, audio devices, and join your first session.


# Using Chatterbox
Source: https://docs.camb.ai/other-products/chatterbox/using-chatterbox

Configure languages, audio devices, and start a live translated session.

Once installation and verification are complete, you can start using Chatterbox in your live meetings. The steps below help you get the best possible audio quality and translation performance.

## Step 1 — Wear earphones or headphones

Put on earphones or headphones **before** starting your session. This:

* Prevents audio feedback and echo, where your speakers feed back into your microphone.
* Avoids audio looping, where translated audio is re-captured and re-translated.
* Avoids degraded performance and noisy audio that come from using built-in laptop speakers.

<Warning>
  Using only built-in laptop speakers can cause feedback loops, degraded audio quality, and confusion for meeting participants.
</Warning>

## Step 2 — Configure language settings

<Frame>
  <img alt="Chatterbox language configuration showing I Speak and They Hear" />
</Frame>

* **I Speak**: Set this to the language you will actually speak during the meeting (for example, *English (United States)*). Chatterbox listens in this language to understand what you say.
* **They Hear**: Set this to the language your audience should hear (for example, *Spanish (Spain)*). Chatterbox translates your speech from **I Speak** into **They Hear**.

## Step 3 — Select the correct audio devices

<Frame>
  <img alt="Chatterbox audio device selection" />
</Frame>

**Confirm your microphone device.** In Chatterbox, set the microphone to your physical mic — for example:

* Your USB headset microphone, or
* Your external microphone, or
* Your laptop microphone if no other device is available.

Using the right mic ensures your voice is captured clearly for accurate translation.

**Confirm your output (speaker) device.** Set the output to the earphones or headphones you are wearing. If a different device (like monitor speakers or unused outputs) is selected, you may not hear the translated audio or it may be very quiet.

<Tip>
  Taking a moment here prevents common issues like "no one can hear me" or "I don't hear anything."
</Tip>

## Step 4 — Join your meeting using Chatterbox Virtual Audio

<Frame>
  <img alt="Meeting platform audio settings with Chatterbox Virtual Microphone selected" />
</Frame>

1. Open your preferred meeting platform (Zoom, Microsoft Teams, Google Meet, etc.).
2. In the meeting's audio settings, set your **microphone** to the Chatterbox virtual device — typically named **Chatterbox Virtual Microphone**.
3. Keep your **speakers** set to the device you normally use (your headphones or earphones).

<Info>
  **Why this is important:** selecting the Chatterbox Virtual Microphone lets the meeting platform receive audio that has been processed and translated by Chatterbox, rather than your raw microphone feed. This is how Chatterbox delivers live translated speech to your participants.
</Info>

### Optional — Reset Windows audio devices if needed

After installing Chatterbox, Windows may automatically change your default audio devices. If you notice unusual audio behavior in other apps (no sound, or sound coming from the wrong device), reset your defaults:

1. Right-click the speaker icon in the taskbar and choose **Sound settings**.
2. Check both **Input** and **Output** devices.
3. Set **Input** to your usual microphone (or headset mic).
4. Set **Output** to your usual speakers or headphones.

This ensures your computer's audio behaves as expected outside of Chatterbox, while Chatterbox continues to use its virtual devices during sessions.

## Step 5 — Start a Chatterbox session

<Frame>
  <img alt="Chatterbox Start Session button" />
</Frame>

1. Review your languages and audio devices one last time.
2. Click **Start Session** in the center of the Chatterbox window.
3. Begin speaking normally in your meeting.

Once the session is active, Chatterbox will listen to your speech, translate it, and output translated audio in real time according to your **I Speak** and **They Hear** settings. Your participants will hear you in their selected language through the Chatterbox Virtual Microphone.

<Check>
  With these steps complete, Chatterbox is configured for live meetings and optimized for clear audio and accurate translation.
</Check>


# Next.js (Page Router)
Source: https://docs.camb.ai/other-products/website-translation/nextjs-page-router

Configure CAMB AI Website Translator in a Next.js project using the Page Router.

This step-by-step guide walks you through configuring Website Translation in a Next.js project that uses the **Page Router**. It includes the exact `Script` configuration, best practices, and troubleshooting tips.

## Step 1 — Create your Website Configuration

In CAMB AI Studio, open the **Website Configuration** form and fill in the following:

* **Name** — A friendly name for your project (e.g., `My website`).
* **Domain** — Your production domain (e.g., `example.com`).
* **Redis Cache URL (Secure)** — A secure `rediss://` connection string for caching translations. See [Set up Redis with Upstash](/other-products/website-translation/redis-cache) if you don't have one.
* **Translate from** — The source language for your content.
* **Translate to** — One or more target languages.

Click **Create Website** to generate your API key.

<Frame>
  <img alt="Website Configuration form in CAMB AI Studio" />
</Frame>

## Step 2 — Add the script in Next.js

Integrate the script using Next.js's [`next/script`](https://nextjs.org/docs/pages/api-reference/components/script) in `pages/_app.tsx`. Make sure the `data-api-key` attribute comes **before** the `strategy` prop, exactly as shown below.

```tsx pages/_app.tsx theme={null}
import Script from "next/script";
import type { AppProps } from "next/app";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      {/* Website Translate Script */}
      <Script
        src="https://storage.googleapis.com/website-translation-script/translator.js"
        data-api-key="your-api-key"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  );
}
```

**Why this works:** The script loads after the page becomes interactive, minimizing render-blocking. The `data-api-key` attribute securely passes your key to the client script.

### Optional — Manage the API key via environment variable

If you prefer not to hard-code the key, expose it as `NEXT_PUBLIC_TRANSLATOR_API_KEY` and pass it to the `Script` tag:

```bash .env.local theme={null}
NEXT_PUBLIC_TRANSLATOR_API_KEY=your-api-key
```

```tsx pages/_app.tsx theme={null}
<Script
  src="https://storage.googleapis.com/website-translation-script/translator.js"
  data-api-key={process.env.NEXT_PUBLIC_TRANSLATOR_API_KEY}
  strategy="afterInteractive"
/>
```

## Step 3 — Deploy and verify

1. Deploy your Next.js app as usual (Vercel, Netlify, or your preferred platform).
2. Open your site in a browser and confirm that a **translation dropdown appears automatically**.
3. Switch languages and verify page text is translated without layout shifts or flashes.

## Best practices for a great UX

* **Warm the cache.** After deployment, visit your key pages yourself and wait for the initial translation to complete so future visitors get instant translations.
* **Keep phrases intact.** Avoid splitting single words or short phrases into many tiny elements — translation accuracy is higher when the translator sees whole sentences.

### Exclude content from translation

Use HTML attributes or classes to skip specific elements:

```html theme={null}
<div translate="no">BrandName</div>
<span class="notranslate">CodeSnippet()</span>
```

### Style the translation dropdown

Customize the dropdown via CSS variables:

```css theme={null}
:root {
  /* Position */
  --tl-position: fixed;
  --tl-bottom: 24px;
  --tl-right: 24px;
  --tl-top: auto;
  --tl-left: auto;
  --tl-z-index: 9999;

  /* Appearance */
  --tl-bg: #333;
  --tl-bg-hover: #555;
  --tl-color: #fff;
  --tl-border: none;
  --tl-border-radius: 4px;
  --tl-box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);

  /* Typography */
  --tl-font-family: "Inter", sans-serif;
  --tl-font-size: 14px;
  --tl-font-weight: 500;
  --tl-line-height: 1;

  /* Spacing */
  --tl-padding: 12px 16px;
  --tl-margin: 0;
  --tl-min-width: 120px;
  --tl-width: auto;
  --tl-height: auto;

  /* Options */
  --tl-option-bg: #333;
  --tl-option-color: #fff;
  --tl-option-padding: 8px 12px;

  /* Loading state */
  --tl-loading-opacity: 0.7;
  --tl-loading-icon: "⟳";
  --tl-loading-margin: 8px;
  --tl-loading-duration: 1s;

  /* Focus */
  --tl-outline: 2px solid #007acc;
  --tl-outline-offset: 2px;

  /* Transition */
  --tl-transition: all 0.2s ease;
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="No dropdown is visible">
    Verify that `pages/_app.tsx` includes the `Script` block and that your API key is correct. Hard-refresh the page (Cmd/Ctrl + Shift + R) and check the browser console for script errors.
  </Accordion>

  <Accordion title="Translations don't appear instantly">
    The first pass may be warming the cache. Visit the page once and try again — subsequent loads will pull translations from Redis.
  </Accordion>

  <Accordion title="Ad blockers or extensions">
    Rarely, browser extensions may block third-party scripts. Test in a clean browser profile or incognito window.
  </Accordion>
</AccordionGroup>

## Security & configuration notes

* **Only use the official script source:** `https://storage.googleapis.com/website-translation-script/translator.js`.
* **Prefer environment variables** (`NEXT_PUBLIC_TRANSLATOR_API_KEY`) for manageability across environments.
* **Use a secure Redis URL.** Your Redis Cache URL must use `rediss://` (TLS-encrypted) — never plain `redis://`.


# Overview
Source: https://docs.camb.ai/other-products/website-translation/overview

Translate your entire website into multiple languages with a single script tag.

CAMB AI **Website Translation** lets you add multilingual support to your site by dropping in a single `<script>` tag. Once installed, a translation dropdown appears on the page, and visitors can switch their language with one click — text is translated on the fly and cached via Redis for near-instant subsequent loads.

## How it works

1. You create a **Website Configuration** in CAMB AI Studio with your domain, source language, target languages, and a Redis cache URL.
2. Studio generates an **API key** scoped to that configuration.
3. You include the Website Translator script on your site, passing the API key via a `data-api-key` attribute.
4. The script renders a language picker, translates page content as visitors switch languages, and caches results in Redis so repeat visits are instant.

## What you'll need

* **A production domain** (the script is bound to the domain you register).
* **A Redis cache** — we recommend [Upstash](https://upstash.com) for a managed, serverless Redis with a free tier. See [Set up Redis with Upstash](/other-products/website-translation/redis-cache).
* **A list of source and target languages** for your site.

## Get started

<CardGroup>
  <Card title="Next.js (Page Router)" icon="code" href="/other-products/website-translation/nextjs-page-router">
    Integrate the translator using `next/script` in `pages/_app.tsx`.
  </Card>

  <Card title="Set up Redis with Upstash" icon="database" href="/other-products/website-translation/redis-cache">
    Provision a free Redis instance and grab the `rediss://` URL.
  </Card>
</CardGroup>

<Note>
  Working with the Next.js App Router or another framework? The same script-tag approach applies — load the script with the `data-api-key` attribute on every page. The integration guides will expand to cover more frameworks over time.
</Note>


# Set up Redis with Upstash
Source: https://docs.camb.ai/other-products/website-translation/redis-cache

Provision a free serverless Redis instance for caching website translations.

CAMB AI Website Translation uses Redis to cache translated text so visitors get instant page loads after the first visit. This guide walks you through creating a free Redis database on [Upstash](https://upstash.com) and wiring it up to your Website Configuration.

## 1. Sign up for Upstash

Navigate to [https://upstash.com](https://upstash.com).

<Frame>
  <img alt="Upstash landing page" />
</Frame>

Create an account using GitHub, Google, or email.

<Frame>
  <img alt="Upstash login page" />
</Frame>

After signing in, you'll be directed to the **Upstash Console**.

<Frame>
  <img alt="Upstash Console dashboard" />
</Frame>

## 2. Create a new Redis database

From the dashboard, select **Redis** and then **Create Database**.

Configure the database:

* **Name** — Assign a descriptive name (for example, `project-cache-db`).
* **Region** — Select a region close to your application hosting location to minimize latency.
* **Plan** — Choose the free plan if you're testing or working on a small project.

<Frame>
  <img alt="Create Database form" />
</Frame>

<Frame>
  <img alt="Plan selection screen" />
</Frame>

Click **Create**. After a few seconds, your database will be available.

<Frame>
  <img alt="Redis database dashboard" />
</Frame>

## 3. Access connection details

Once the database is created, you'll see:

* The **REST API URL**
* The **REST Token**
* The **Redis Connection URL** — this is what you'll paste into your CAMB AI Website Configuration as the **Redis Cache URL (Secure)**.

<Frame>
  <img alt="Redis database connection details panel" />
</Frame>

<Warning>
  Make sure the Redis Connection URL you copy starts with `rediss://` (note the double `s`). This is the TLS-encrypted endpoint required by the Website Translator.
</Warning>

## 4. Clearing the Redis cache

If you need to clear all cached translations from your Redis database, use the Flush functionality.

* From the Upstash Console, open your Redis database.
* Navigate to the **CLI** tab.

<Frame>
  <img alt="Upstash CLI tab" />
</Frame>

* Execute the `FLUSHALL` or `FLUSHDB` command.

<Frame>
  <img alt="Running FLUSHDB in the Upstash CLI" />
</Frame>

## 5. Time-to-Live (TTL) and inactivity

Redis allows you to set a time-to-live (TTL) on keys. The TTL specifies how long a key remains in the cache before being automatically deleted.

Key points about TTL behavior:

* **Expiration** — When the TTL for a key reaches zero, Redis automatically deletes it.
* **No TTL set** — If you don't set a TTL, the key will persist until explicitly removed.
* **Inactivity** — Redis does not automatically expire keys due to inactivity unless a TTL has been defined.

## 6. Monitoring and management

In the Upstash dashboard, you can:

* Review memory usage and request metrics by going to the **Usage** tab.

<Frame>
  <img alt="Usage tab showing memory and request metrics" />
</Frame>

* Monitor keys and expiration patterns.
* Reset credentials or delete the database when no longer needed.

<Frame>
  <img alt="Credentials management panel" />
</Frame>

## 7. Connect Redis to your Website Configuration

With your Upstash database ready, integrate it into CAMB AI Studio:

1. Open the **Website Configuration** form in Studio.

<Frame>
  <img alt="Website Translation configuration form" />
</Frame>

2. Provide the following:
   * **Name** — A friendly name for your project (e.g., `My Website`).
   * **Domain** — Your production domain (e.g., `example.com`).
   * **Redis Cache URL (Secure)** — The secure `rediss://` connection string from your Upstash database.
   * **Translate From** — The source language for your website's content.
   * **Translate To** — One or more target languages.

3. Click **Create Website**. This generates an API key for your project, which your application can use to fetch and cache translations.

Next, see [Next.js (Page Router)](/other-products/website-translation/nextjs-page-router) to drop the script into your app.


# Release Logs
Source: https://docs.camb.ai/release-logs/overview

Track updates and improvements to CAMB.AI

Welcome to the CAMB.AI Release Logs. Here you'll find detailed information about new features, improvements, and bug fixes in each release.

<Update label="Release/14.03.26">
  ### Enhancements:

  #### Conversion Improvements:

  * Blocked new TTS generation while audio is already playing.
  * Added de-bouncer to Speaker Settings so changes are saved automatically without needing to click Save every time. @csm
  * Added basic Settings access in Billing page for free plan users.
  * Enabled folder creation directly on mobile devices.

  #### Website Translation Analytics:

  * Implemented CIO Analytics tracking for Website Translation feature.
  * Migrated Website Translation analytics storage from internal database for better scalability and querying.

  #### Language Prompting

  * Introduced a dedicated language prompting field in the UI on project creation screen (more proactive and user-friendly).
</Update>

<Update label="Release/21.02.26">
  ### Enhancements:

  #### Code Cleanup:

  * Reorganized and cleaned up code in Narrations Creation Page for better readability and maintainability.
  * Refactored Stories Creation Page codebase to remove technical debt and improve future extensibility.
  * Restructured Dubbing Creation Page module layout and applied consistent clean-up patterns.
  * Cleaned up Transcription module code and components.
  * Improved folder structure and removed redundant code in TTS module.
  * Applied comprehensive code reorganization and clean-up in Voice Library for reduced complexity.

  #### User Journey Optimization:

  * Implemented a new onboarding flow with improved step progression and clearer guidance.

  #### Conversion Improvements:

  * Added gender specification (Male/Female) for stock voices in the voice selection module inside Speaker Settings.
  * Added tooltips in mobile view on the Dubbing Creation Page (now appear on tap/hold).
  * Corrected stale icon color in Stories Download Modal (now consistently displays the proper warning color).

  #### Subtitling v2:

  * Applied dialogue-level subtitle configurations (position, font, etc.) in the editor.
  * Added support for Subtitles Rules stored in CAMB metadata.
  * Enabled individual subtitle position adjustment directly in the editor.
  * Allowed users to configure maximum characters per line in Subtitle mode.
    * Added per-dialogue italic styling for subtitles.
  * Enabled custom settings selection during subtitle generation.
  * Removed whitespaces from character count calculations.

  ### Bug Fixes:

  * Prevented rapid play/pause actions in the Editor to avoid race conditions.
  * Blocked navigation to other projects when loading a run from history.
  * Fixed UI error complaining about voices with less than 90 seconds of audio.
  * Made the invite voice modal not auto close on accept/reject shared voice.
</Update>

<Update label="Release/14.02.26">
  ### Enhancements:

  #### Product Security Hardening

  * Implemented concurrent request limits limiting across APIs to protect against abuse and ensure fair resource usage.

  #### File Restructure & Code Clean Up (Non-Editor)

  * Reorganized and cleaned up code in the Insights module for better readability and long-term maintainability.
  * Refactored and cleaned the Image Translation codebase, removing technical debt and making future changes easier.
  * Restructured the Text-to-Audio (TTA) module layout and applied consistent clean-up patterns to enhance overall code quality.
  * Improved folder structure and removed redundant or outdated code in the Home module to make it easier to navigate and maintain.
  * Applied comprehensive code reorganization and clean-up in the Audio Separation module to reduce complexity and improve developer experience.

  #### Enhanced GHA Build Time

  * Changes to deployment flow to enhance build times.

  ### Bug Fixes:

  #### Conversions & Usability

  * Fixed Project Settings modal not auto-closing after updating subtitle position or font in Subtitle Settings.
</Update>

***


# Go SDK
Source: https://docs.camb.ai/sdk-guides/go-sdk

Install and use the Go SDK with context-based cancellation and streaming audio

The official Go SDK for Camb.ai provides convenient access to text-to-speech, dubbing, translation, transcription, voice cloning, and audio generation. It uses functional options for configuration and returns `io.Reader` streams for audio output.

## Installation

```bash theme={null}
go get github.com/camb-ai/cambai-go-sdk
```

The module currently declares **Go 1.13** as its minimum version in `go.mod`. Newer Go releases work with the module; use the version your team standardizes on for builds and CI.

***

## Authentication

Get your API key from [Camb.ai Studio](https://studio.camb.ai) and pass it with `option.WithAPIKey`. Reading `CAMB_API_KEY` from the environment keeps secrets out of source control.

```go theme={null}
import (
	"github.com/camb-ai/cambai-go-sdk/client"
	"github.com/camb-ai/cambai-go-sdk/option"
)

c := client.NewClient(option.WithAPIKey(os.Getenv("CAMB_API_KEY")))
```

<Tip>
  For local development, load `CAMB_API_KEY` from a `.env` file with a small helper or your process manager so the value never lands in version control.
</Tip>

***

## Imports

The root module is `package cambai`, so the default import name is `cambai` when you import `github.com/camb-ai/cambai-go-sdk`. You may also use an explicit alias (`import cambai "github.com/camb-ai/cambai-go-sdk"`) for clarity in larger codebases. The snippets below assume the default name `cambai`.

***

## Quick Start

`TextToSpeech.Tts` returns an `io.Reader` streaming audio. Copy it to a file (or another writer) with `io.Copy`.

```go theme={null}
package main

import (
	"context"
	"io"
	"os"

	"github.com/camb-ai/cambai-go-sdk"
	"github.com/camb-ai/cambai-go-sdk/client"
	"github.com/camb-ai/cambai-go-sdk/option"
)

func main() {
	c := client.NewClient(option.WithAPIKey(os.Getenv("CAMB_API_KEY")))

	stream, err := c.TextToSpeech.Tts(
		context.Background(),
		&cambai.CreateStreamTtsRequestPayload{
			Text:        "Hello from the Camb.ai Go SDK.",
			VoiceID:     147320,
			Language:    cambai.CreateStreamTtsRequestPayloadLanguageEnUs,
			SpeechModel: cambai.CreateStreamTtsRequestPayloadSpeechModelMarsFlash.Ptr(),
			OutputConfiguration: &cambai.StreamTtsOutputConfiguration{
				Format: cambai.OutputFormatWav.Ptr(),
			},
		},
	)
	if err != nil {
		panic(err)
	}

	out, err := os.Create("output.wav")
	if err != nil {
		panic(err)
	}
	defer out.Close()

	if _, err := io.Copy(out, stream); err != nil {
		panic(err)
	}
}
```

The snippets in the sections below assume `c` and `ctx` are initialized as shown above.

***

## Models

Camb.ai offers MARS models tuned for different quality and latency needs. Set `SpeechModel` on `CreateStreamTtsRequestPayload` using the generated constants (for example `CreateStreamTtsRequestPayloadSpeechModelMarsFlash`). If you omit it, the API applies its default model.

| Model                 | Sample Rate | Best For                                                                     |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `mars-8.1-flash-beta` | 48 kHz      | Faster MARS 8.1 generation; same quality improvements as `mars-8.1-pro-beta` |
| `mars-8.1-pro-beta`   | 48 kHz      | Improved pronunciation, expressiveness, and prosody over `mars-pro`          |
| `mars-flash`          | 22.05 kHz   | Low-latency real-time applications and conversational AI                     |
| `mars-pro`            | 48 kHz      | High-fidelity audio production and long-form content                         |
| `mars-instruct`       | 22.05 kHz   | Fine-grained tone and style control via text instructions                    |

<Tabs>
  <Tab title="MARS Flash">
    ```go theme={null}
    stream, err := c.TextToSpeech.Tts(ctx, &cambai.CreateStreamTtsRequestPayload{
    	Text:        "Hey, I can respond much faster.",
    	Language:    cambai.CreateStreamTtsRequestPayloadLanguageEnUs,
    	VoiceID:     147320,
    	SpeechModel: cambai.CreateStreamTtsRequestPayloadSpeechModelMarsFlash.Ptr(),
    	OutputConfiguration: &cambai.StreamTtsOutputConfiguration{
    		Format: cambai.OutputFormatWav.Ptr(),
    	},
    })
    if err != nil {
    	panic(err)
    }
    _ = stream
    ```

    **Best for:** Voice agents and real-time applications.

    **Sample rate:** 22.05 kHz.
  </Tab>

  <Tab title="MARS Pro">
    ```go theme={null}
    stream, err := c.TextToSpeech.Tts(ctx, &cambai.CreateStreamTtsRequestPayload{
    	Text:        "High-fidelity audio for production use.",
    	Language:    cambai.CreateStreamTtsRequestPayloadLanguageEnUs,
    	VoiceID:     147320,
    	SpeechModel: cambai.CreateStreamTtsRequestPayloadSpeechModelMarsPro.Ptr(),
    	OutputConfiguration: &cambai.StreamTtsOutputConfiguration{
    		Format: cambai.OutputFormatWav.Ptr(),
    	},
    })
    if err != nil {
    	panic(err)
    }
    _ = stream
    ```

    **Best for:** Audio production, dubbing, and long-form content.

    **Sample rate:** 48 kHz.
  </Tab>

  <Tab title="MARS Instruct">
    ```go theme={null}
    stream, err := c.TextToSpeech.Tts(ctx, &cambai.CreateStreamTtsRequestPayload{
    	Text:             "Great to meet you!",
    	Language:         cambai.CreateStreamTtsRequestPayloadLanguageEnUs,
    	VoiceID:          147320,
    	SpeechModel:      cambai.CreateStreamTtsRequestPayloadSpeechModelMarsInstruct.Ptr(),
    	UserInstructions: cambai.String("Speak in a warm, friendly tone"),
    	OutputConfiguration: &cambai.StreamTtsOutputConfiguration{
    		Format: cambai.OutputFormatWav.Ptr(),
    	},
    })
    if err != nil {
    	panic(err)
    }
    _ = stream
    ```

    **Best for:** Fine-grained control over tone and style.

    **Sample rate:** 22.05 kHz.
  </Tab>
</Tabs>

The `ctx` and `c` variables in the model tabs match the authenticated client pattern from the Quick Start and Authentication sections.

***

## TTS Options

`c.TextToSpeech.Tts(...)` accepts `CreateStreamTtsRequestPayload` with the core request fields plus optional controls for model behavior and output format.

| Field                               | Type                                   | Description                                                                                                                |
| ----------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Text`                              | string                                 | Text to synthesize. For MARS Instruct, you can include inline emotion or pacing tags in the text.                          |
| `Language`                          | enum                                   | Locale such as `cambai.CreateStreamTtsRequestPayloadLanguageEnUs`.                                                         |
| `VoiceID`                           | integer                                | Voice profile ID from `VoiceCloning.ListVoices`.                                                                           |
| `SpeechModel`                       | pointer enum/string                    | Model to use, such as `MarsFlash`, `MarsPro`, or `MarsInstruct`.                                                           |
| `UserInstructions`                  | string pointer                         | Adds style, tone, pronunciation, or delivery guidance for the request. Available only when `SpeechModel` is MARS Instruct. |
| `OutputConfiguration`               | `*cambai.StreamTtsOutputConfiguration` | Output settings such as audio format.                                                                                      |
| `VoiceSettings`                     | object                                 | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.                              |
| `InferenceOptions`                  | object                                 | Advanced generation controls for supported models.                                                                         |
| `EnhanceNamedEntitiesPronunciation` | boolean pointer                        | Improves pronunciation for names and other named entities when supported.                                                  |

***

## Voices

`VoiceCloning.ListVoices` returns the voices available to your account.

```go theme={null}
voices, err := c.VoiceCloning.ListVoices(ctx, &cambai.ListVoicesListVoicesGetRequest{})
if err != nil {
	panic(err)
}
for _, item := range voices {
	// item is a discriminated union; visit to get the typed Voice value.
	if v := item.Voice; v != nil {
		fmt.Println(v.ID, v.VoiceName)
	}
}
```

`VoiceCloning.CreateCustomVoice` accepts `BodyCreateCustomVoiceCreateCustomVoicePost` (voice name, `Gender`, optional description, and other metadata). Map `Gender` to the integer values described in the [Create custom voice](https://docs.camb.ai/api-reference/endpoint/create-custom-voice) reference. The generated request type in this module does not include a sample audio field; if your workflow requires uploading a clip, use the REST multipart contract or confirm the latest SDK types match your needs.

***

## Language support

TTS requests use typed language constants on `CreateStreamTtsRequestPayload` (for example `CreateStreamTtsRequestPayloadLanguageEnUs`). See [Language Support](/language-support) for the full per-model locale list. Dubbing, translation, transcription, and related payloads use the shared `cambai.Languages` type (for example `cambai.LanguagesEnUs`).

`Languages.GetSourceLanguages` and `Languages.GetTargetLanguages` return the language lists exposed by the API for products that distinguish source and target sets.

```go theme={null}
source, err := c.Languages.GetSourceLanguages(ctx, &cambai.GetSourceLanguagesSourceLanguagesGetRequest{})
if err != nil {
	panic(err)
}
targets, err := c.Languages.GetTargetLanguages(ctx, &cambai.GetTargetLanguagesTargetLanguagesGetRequest{})
if err != nil {
	panic(err)
}
fmt.Println(len(source), len(targets))
```

Per-model language coverage is summarized on the [Models](/models) page.

***

## Dubbing

Dubbing takes a public video URL, translates the audio into your target language, and synthesizes speech. The flow is asynchronous: submit with `Dub.EndToEndDubbing`, poll with `Dub.GetEndToEndDubbingStatus`, then read the output with `Dub.GetDubbedRunInfo`. Go uses **`EndToEndDubbing`** (same naming as the TypeScript SDK, unlike Python `create_dub`).

```go theme={null}
resp, err := c.Dub.EndToEndDubbing(ctx, &cambai.EndToEndDubbingRequestPayload{
	VideoURL:       "https://example.com/video.mp4",
	SourceLanguage: cambai.LanguagesEnUs,
	TargetLanguage: cambai.LanguagesFrFr.Ptr(),
})
if err != nil {
	panic(err)
}
taskID := *resp.TaskID
```

Poll `Dub.GetEndToEndDubbingStatus` with that task id until `Status` is `cambai.TaskStatusSuccess` or `cambai.TaskStatusError`, then call `Dub.GetDubbedRunInfo` with the `RunID` from the status object. See `examples/dubbing` in the [cambai-go-sdk](https://github.com/camb-ai/cambai-go-sdk) repository for a full loop.

For multiple targets in one job, set `TargetLanguages` instead of `TargetLanguage`.

### Transcript

After a successful run, `Dub.GetDubbedRunTranscript` returns transcript data for a target language.

```go theme={null}
// runID comes from GetEndToEndDubbingStatus after the job succeeds.
txt := cambai.TranscriptFileFormatTxt
transcript, err := c.Dub.GetDubbedRunTranscript(
	ctx,
	&runID,
	cambai.LanguagesFrFr,
	&cambai.GetDubbedRunTranscriptTranscriptRunIDLanguageGetRequest{
		FormatType: txt.Ptr(),
	},
)
if err != nil {
	panic(err)
}
fmt.Println(transcript)
```

***

## Translation

Submit strings with `Translation.CreateTranslation`, poll `GetTranslationTaskStatus`, then fetch strings with `GetTranslationResult`. `CreateTranslation` is typed as `interface{}` in this client; round-trip through JSON is a reliable way to read `task_id` into `OrchestratorPipelineCallResult`.

```go theme={null}
raw, err := c.Translation.CreateTranslation(ctx, &cambai.CreateTranslationRequestPayload{
	Texts:          []string{"Hello, how are you?", "Welcome to Camb.ai."},
	SourceLanguage: cambai.LanguagesEnUs,
	TargetLanguage: cambai.LanguagesFrFr,
})
if err != nil {
	panic(err)
}

// CreateTranslation returns interface{}; round-trip through JSON to read task_id.
b, _ := json.Marshal(raw)
var started cambai.OrchestratorPipelineCallResult
json.Unmarshal(b, &started)
taskID := *started.TaskID

for {
	time.Sleep(2 * time.Second)
	status, err := c.Translation.GetTranslationTaskStatus(
		ctx, taskID, &cambai.GetTranslationTaskStatusTranslateTaskIDGetRequest{},
	)
	if err != nil {
		panic(err)
	}
	if status.Status == cambai.TaskStatusSuccess && status.RunID != nil {
		result, err := c.Translation.GetTranslationResult(
			ctx, status.RunID, &cambai.GetTranslationResultTranslationResultRunIDGetRequest{},
		)
		if err != nil {
			panic(err)
		}
		fmt.Println(result.Texts)
		return
	}
	if status.Status == cambai.TaskStatusError {
		panic("translation failed")
	}
}
```

***

## Transcription

Pass a remote URL with `MediaURL` on `BodyCreateTranscriptionTranscribePost`. Poll `GetTranscriptionTaskStatus`, then call `GetTranscriptionResult`.

```go theme={null}
resp, err := c.Transcription.CreateTranscription(ctx, &cambai.BodyCreateTranscriptionTranscribePost{
	Language: cambai.LanguagesEnUs,
	MediaURL: cambai.String("https://example.com/audio.mp3"),
})
if err != nil {
	panic(err)
}
taskID := *resp.TaskID

for {
	time.Sleep(3 * time.Second)
	status, err := c.Transcription.GetTranscriptionTaskStatus(
		ctx, taskID, &cambai.GetTranscriptionTaskStatusTranscribeTaskIDGetRequest{},
	)
	if err != nil {
		panic(err)
	}
	if status.Status == cambai.TaskStatusSuccess && status.RunID != nil {
		result, err := c.Transcription.GetTranscriptionResult(
			ctx, status.RunID,
			&cambai.GetTranscriptionResultTranscriptionResultRunIDGetRequest{},
		)
		if err != nil {
			panic(err)
		}
		fmt.Println(result)
		return
	}
	if status.Status == cambai.TaskStatusError {
		panic("transcription failed")
	}
}
```

The generated transcription request type in this module exposes `MediaURL` (and deprecated `AudioURL`). If you need to upload a local file from Go, confirm the latest SDK supports the multipart fields your server expects, or use the REST API directly.

***

## Audio separation

The client exposes `AudioSeparation.CreateAudioSeparation`, `GetAudioSeparationStatus`, `GetAudioSeparationRunInfo`, and batch helpers. The generated `BodyCreateAudioSeparationAudioSeparationPost` type in this repository currently carries metadata fields only. For production uploads, validate the request type against [Audio separation](https://docs.camb.ai/api-reference) in your SDK version or call the REST endpoints until the generator includes the media parts you rely on.

***

## Text-to-voice

Text-to-voice creates candidate voices from a description. Submit with `TextToVoice.CreateTextToVoice`, poll `GetTextToVoiceStatus`, then read previews from `GetTextToVoiceResult`.

```go theme={null}
resp, err := c.TextToVoice.CreateTextToVoice(ctx, &cambai.CreateTextToVoiceRequestPayload{
	Text:             "A confident narrator introducing a documentary.",
	VoiceDescription: "Deep, measured baritone with a slight gravel. Calm and authoritative.",
})
if err != nil {
	panic(err)
}
taskID := *resp.TaskID

for {
	time.Sleep(2 * time.Second)
	status, err := c.TextToVoice.GetTextToVoiceStatus(
		ctx, taskID, &cambai.GetTextToVoiceStatusTextToVoiceTaskIDGetRequest{},
	)
	if err != nil {
		panic(err)
	}
	if status.Status == cambai.TaskStatusSuccess && status.RunID != nil {
		runID := *status.RunID
		out, err := c.TextToVoice.GetTextToVoiceResult(
			ctx, &runID, &cambai.GetTextToVoiceResultTextToVoiceResultRunIDGetRequest{},
		)
		if err != nil {
			panic(err)
		}
		fmt.Println(out.Previews)
		return
	}
	if status.Status == cambai.TaskStatusError {
		panic("text-to-voice failed")
	}
}
```

The `GetTextToVoiceResultOut` value includes `Previews` (URLs) you can audition before choosing a `voice_id` for TTS.

***

## Text-to-audio

Text-to-audio generates sound from a prompt. The pattern matches other async jobs: `CreateTextToAudio`, `GetTextToAudioStatus`, then `GetTextToAudioResult` as an `io.Reader`.

```go theme={null}
resp, err := c.TextToAudio.CreateTextToAudio(ctx, &cambai.CreateTextToAudioRequestPayload{
	Prompt:    "Heavy rain on a tin roof at night with distant thunder.",
	Duration:  cambai.Float64(15),
	AudioType: cambai.TextToAudioTypeSound.Ptr(),
})
if err != nil {
	panic(err)
}
taskID := *resp.TaskID

for {
	time.Sleep(3 * time.Second)
	status, err := c.TextToAudio.GetTextToAudioStatus(
		ctx, taskID, &cambai.GetTextToAudioStatusTextToSoundTaskIDGetRequest{},
	)
	if err != nil {
		panic(err)
	}
	if status.Status == cambai.TaskStatusSuccess && status.RunID != nil {
		runID := *status.RunID
		stream, err := c.TextToAudio.GetTextToAudioResult(
			ctx, &runID, &cambai.GetTextToAudioResultTextToSoundResultRunIDGetRequest{},
		)
		if err != nil {
			panic(err)
		}
		out, _ := os.Create("soundscape.wav")
		defer out.Close()
		io.Copy(out, stream)
		return
	}
	if status.Status == cambai.TaskStatusError {
		panic("text-to-audio failed")
	}
}
```

***

## Stories

`Story.CreateStory` returns `*CreateStoryStoryPostResponse`, a discriminated union over `OrchestratorPipelineCallResult` (async `task_id`) and `GetSetupStoryResultResponse` (immediate setup payload). Use `Accept` with `CreateStoryStoryPostResponseVisitor` to read whichever branch the API returned, then poll `GetStoryStatus` when you received a task id.

The generated `BodyCreateStoryStoryPost` struct lists the fields this client sends. If you rely on uploading a source document, compare that struct to the REST story endpoint for your SDK revision.

```go theme={null}
// storyKickoff implements CreateStoryStoryPostResponseVisitor to extract either
// a task_id (async) or an immediate run_id (sync setup response).
type storyKickoff struct {
	taskID string
	runID  int
	mode   string
}

func (v *storyKickoff) VisitOrchestratorPipelineCallResult(r *cambai.OrchestratorPipelineCallResult) error {
	v.taskID = *r.TaskID
	v.mode = "async"
	return nil
}

func (v *storyKickoff) VisitGetSetupStoryResultResponse(r *cambai.GetSetupStoryResultResponse) error {
	v.runID = r.RunID
	v.mode = "sync"
	return nil
}

created, err := c.Story.CreateStory(ctx, &cambai.BodyCreateStoryStoryPost{
	SourceLanguage: cambai.LanguagesEnUs,
	Title:          cambai.String("My story"),
})
if err != nil {
	panic(err)
}

var kick storyKickoff
if err := created.Accept(&kick); err != nil {
	panic(err)
}

if kick.mode == "async" {
	for {
		time.Sleep(5 * time.Second)
		status, err := c.Story.GetStoryStatus(ctx, kick.taskID, &cambai.GetStoryStatusStoryTaskIDGetRequest{})
		if err != nil {
			panic(err)
		}
		if status.Status == cambai.TaskStatusSuccess && status.RunID != nil {
			runID := *status.RunID
			info, err := c.Story.GetStoryRunInfo(ctx, &runID, &cambai.GetStoryRunInfoStoryResultRunIDGetRequest{})
			if err != nil {
				panic(err)
			}
			fmt.Println(info)
			return
		}
		if status.Status == cambai.TaskStatusError {
			panic("story failed")
		}
	}
}
```

***

## Translated TTS

`TranslatedTts.CreateTranslatedTts` returns `CreateTranslatedTtsOut` with a string `TaskID`. Poll with `GetTranslatedTtsTaskStatus` until `Status` is success or error.

```go theme={null}
out, err := c.TranslatedTts.CreateTranslatedTts(ctx, &cambai.CreateTranslatedTtsRequestPayload{
	Text:           "Good morning, welcome to our service.",
	VoiceID:        147320,
	SourceLanguage: cambai.LanguagesEnUs,
	TargetLanguage: cambai.LanguagesHiIn,
})
if err != nil {
	panic(err)
}

for {
	time.Sleep(3 * time.Second)
	status, err := c.TranslatedTts.GetTranslatedTtsTaskStatus(
		ctx, out.TaskID, &cambai.GetTranslatedTtsTaskStatusTranslatedTtsTaskIDGetRequest{},
	)
	if err != nil {
		panic(err)
	}
	if status.Status == cambai.TaskStatusSuccess {
		fmt.Println(status)
		return
	}
	if status.Status == cambai.TaskStatusError {
		panic("translated tts failed")
	}
}
```

***

## Dictionaries

`Dictionaries.GetDictionaries` lists dictionaries. `AddTermToDictionary` accepts `TermTranslationInput` entries (`Translation` string plus `Language`). IDs are integers.

```go theme={null}
dicts, err := c.Dictionaries.GetDictionaries(ctx, &cambai.GetDictionariesDictionariesGetRequest{})
if err != nil {
	panic(err)
}
dictionaryID := dicts[0].ID

_, err = c.Dictionaries.AddTermToDictionary(ctx, dictionaryID, &cambai.AddDictionaryTermPayload{
	Translations: []*cambai.TermTranslationInput{
		{Translation: "कैम्ब.एआई", Language: cambai.LanguagesHiIn},
	},
})
if err != nil {
	panic(err)
}
```

`DeleteDictionaryTerm` and `DeleteDictionary` take integer IDs and optional `RunID` query parameters on their request structs. The `CreateDictionaryFromFile` helper in this module builds multipart metadata only; for CSV-based creation, prefer the REST contract in the API reference until the client matches it.

***

## Folders

`Folders.ListFolders` and `Folders.CreateFolder` organize runs in Studio-compatible projects. Pass the generated request structs from the `cambai` package for optional filters.

***

## Error handling

API failures surface as `error` values. Validation responses decode to `*cambai.UnprocessableEntityError`, which embeds `*core.APIError`. Use `errors.As` to inspect status codes and optional `Body` details.

```go theme={null}
package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"os"

	"github.com/camb-ai/cambai-go-sdk"
	"github.com/camb-ai/cambai-go-sdk/client"
	"github.com/camb-ai/cambai-go-sdk/core"
	"github.com/camb-ai/cambai-go-sdk/option"
)

func main() {
	c := client.NewClient(option.WithAPIKey(os.Getenv("CAMB_API_KEY")))
	ctx := context.Background()

	request := &cambai.CreateStreamTtsRequestPayload{
		Text:        "Hello world.",
		VoiceID:     147320,
		Language:    cambai.CreateStreamTtsRequestPayloadLanguageEnUs,
		SpeechModel: cambai.CreateStreamTtsRequestPayloadSpeechModelMarsFlash.Ptr(),
		OutputConfiguration: &cambai.StreamTtsOutputConfiguration{
			Format: cambai.OutputFormatWav.Ptr(),
		},
	}

	stream, err := c.TextToSpeech.Tts(ctx, request)
	if err != nil {
		var validation *cambai.UnprocessableEntityError
		if errors.As(err, &validation) {
			fmt.Println("validation:", validation.Body)
			os.Exit(1)
		}
		var apiErr *core.APIError
		if errors.As(err, &apiErr) {
			fmt.Println("status:", apiErr.StatusCode)
			os.Exit(1)
		}
		panic(err)
	}
	_, _ = io.Copy(io.Discard, stream)
}
```

Per-request tuning uses functional options from `github.com/camb-ai/cambai-go-sdk/option`, for example `option.WithMaxAttempts(3)`.

***

## Custom provider (Baseten)

The Go SDK does **not** mirror the TypeScript `ttsProvider` constructor flag on the main client. Instead, implement `provider.TtsProvider` from `github.com/camb-ai/cambai-go-sdk/provider` and call `Tts` yourself (or inject the implementation into your own stack). See the [baseten-provider example](https://github.com/camb-ai/cambai-go-sdk/blob/master/examples/baseten-provider/main.go) in the Go SDK repository for a complete `BasetenProvider` struct, HTTP wiring, and streaming output to disk.

```go theme={null}
package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strings"

	cambai "github.com/camb-ai/cambai-go-sdk"
	"github.com/camb-ai/cambai-go-sdk/provider"
)

// BasetenProvider implements provider.TtsProvider for the Baseten Mars8-Flash model.
// API reference: https://www.baseten.co/library/mars8-flash/
type BasetenProvider struct {
	APIKey            string
	URL               string
	ReferenceAudio    string
	ReferenceLanguage string
}

// CreateTts is a stub because Baseten does not support async TTS.
func (b *BasetenProvider) CreateTts(ctx context.Context, request *cambai.CreateTtsRequestPayload) (*cambai.CreateTtsOut, error) {
	return nil, fmt.Errorf("Baseten custom hosting provider does not support async CreateTts; use Tts (streaming) instead")
}

// Tts calls the Baseten Mars8-Flash endpoint and returns the audio as an io.Reader.
func (b *BasetenProvider) Tts(ctx context.Context, request *cambai.CreateStreamTtsRequestPayload) (io.Reader, error) {
	langStr := strings.ToLower(strings.ReplaceAll(string(request.Language), "_", "-"))

	payload := map[string]interface{}{
		"text":               request.Text,
		"language":           langStr,
		"output_duration":    nil,
		"reference_audio":    b.ReferenceAudio,
		"reference_language": b.ReferenceLanguage,
		"output_format":      "flac",
		"apply_ner_nlp":      false,
	}

	payloadBytes, err := json.Marshal(payload)
	if err != nil {
		return nil, fmt.Errorf("failed to marshal payload: %w", err)
	}

	req, err := http.NewRequestWithContext(ctx, "POST", b.URL, bytes.NewBuffer(payloadBytes))
	if err != nil {
		return nil, fmt.Errorf("failed to create request: %w", err)
	}
	req.Header.Set("Authorization", "Api-Key "+b.APIKey)
	req.Header.Set("Content-Type", "application/json")

	httpClient := &http.Client{}
	resp, err := httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("request failed: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return nil, fmt.Errorf("baseten error (%d): %s", resp.StatusCode, string(body))
	}

	var buf bytes.Buffer
	if _, err = io.Copy(&buf, resp.Body); err != nil {
		return nil, fmt.Errorf("failed to read response body: %w", err)
	}

	return &buf, nil
}

var _ provider.TtsProvider = (*BasetenProvider)(nil)
```

See [Custom Cloud Providers](/custom-cloud-providers) for deployment context and Baseten library links.

***

## Next steps

<CardGroup>
  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice agents with Pipecat
  </Card>

  <Card title="LiveKit Integration" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit">
    Create voice agents with LiveKit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Explore the full TTS API
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>

***

## Resources

* [GitHub: camb-ai/cambai-go-sdk](https://github.com/camb-ai/cambai-go-sdk)
* [SDK examples](https://github.com/camb-ai/cambai-go-sdk/tree/master/examples)
* [API reference](https://docs.camb.ai/api-reference/endpoint/create-tts-stream)


# Java SDK
Source: https://docs.camb.ai/sdk-guides/java-sdk

Install and use the Java SDK with builder patterns and typed async polling

The official Java SDK for Camb.ai provides convenient access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, and audio generation. Requests use a fluent builder pattern; async jobs follow a typed submit-poll-fetch workflow with `TaskStatus` enums.

## Installation

### Gradle

Add the dependency to your `build.gradle`:

```groovy theme={null}
dependencies {
  implementation 'ai.camb:cambai-java-sdk:1.5.9'
}
```

### Maven

Add the dependency to your `pom.xml`:

```xml theme={null}
<dependency>
  <groupId>ai.camb</groupId>
  <artifactId>cambai-java-sdk</artifactId>
  <version>1.5.9</version>
</dependency>
```

***

## Authentication

Get your API key from [CAMB.AI Studio](https://studio.camb.ai/) and set it as an environment variable:

```bash theme={null}
export CAMB_API_KEY=your_api_key_here
```

***

## Quick Start

### Streaming Text-to-Speech

The SDK returns an `InputStream` for TTS audio so you can stream the response directly to disk:

<Note>
  The generated SDK classes in this repository are in the default Java package (no `package ...;` declaration). To keep this snippet runnable without extra packaging changes, put `Main` in the default package too.
</Note>

```java theme={null}
import resources.texttospeech.requests.CreateStreamTtsRequestPayload;
import resources.texttospeech.types.CreateStreamTtsRequestPayloadLanguage;
import resources.texttospeech.types.CreateStreamTtsRequestPayloadSpeechModel;
import types.OutputFormat;
import types.StreamTtsOutputConfiguration;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;

public class Main {
  private static void saveStreamToFile(InputStream stream, String filename) throws IOException {
    try (InputStream in = stream; FileOutputStream out = new FileOutputStream(filename)) {
      byte[] buffer = new byte[4096];
      int bytesRead;
      while ((bytesRead = in.read(buffer)) != -1) {
        out.write(buffer, 0, bytesRead);
      }
    }
  }

  public static void main(String[] args) {
    String apiKey = System.getenv("CAMB_API_KEY");
    if (apiKey == null || apiKey.isEmpty()) {
      throw new IllegalStateException("Missing CAMB_API_KEY environment variable.");
    }

    CambApiClient client = CambApiClient.builder()
      .apiKey(apiKey)
      .build();

    InputStream audioStream = client.textToSpeech().tts(
      CreateStreamTtsRequestPayload.builder()
        .text("Hello! Welcome to Camb.ai text-to-speech.")
        .language(CreateStreamTtsRequestPayloadLanguage.EN_US)
        .voiceId(147320)
        .speechModel(CreateStreamTtsRequestPayloadSpeechModel.MARSFLASH)
        .outputConfiguration(StreamTtsOutputConfiguration.builder().format(OutputFormat.WAV).build())
        .build()
    );

    try {
      saveStreamToFile(audioStream, "output.wav");
      System.out.println("Audio saved to output.wav");
    } catch (IOException e) {
      throw new RuntimeException("Failed to save TTS output file", e);
    }
  }
}
```

The snippets in the sections below assume `client` is already initialized as shown above.

***

## Models / Configuration

Camb.ai uses MARS models configured through `speechModel` on the streaming TTS request:

<CodeGroup>
  ```java MARS Flash theme={null}
  .speechModel(CreateStreamTtsRequestPayloadSpeechModel.MARSFLASH)
  // Sample rate: 22.05kHz
  ```

  ```java MARS Pro theme={null}
  .speechModel(CreateStreamTtsRequestPayloadSpeechModel.MARSPRO)
  // Sample rate: 48kHz
  ```

  ```java MARS Instruct theme={null}
  CreateStreamTtsRequestPayload payload = CreateStreamTtsRequestPayload.builder()
    .text("[warm, friendly] Great to meet you!")
    .language(CreateStreamTtsRequestPayloadLanguage.EN_US)
    .voiceId(147320)
    .speechModel(CreateStreamTtsRequestPayloadSpeechModel.MARSINSTRUCT)
    .userInstructions("Speak in a warm, friendly tone")
    .outputConfiguration(StreamTtsOutputConfiguration.builder().format(OutputFormat.WAV).build())
    .build();
  // Sample rate: 22.05kHz
  ```
</CodeGroup>

To control the output encoding, set `outputConfiguration.format` with `types.OutputFormat`:

| `OutputFormat`      | Value sent to the API |
| ------------------- | --------------------- |
| `OutputFormat.WAV`  | `wav`                 |
| `OutputFormat.FLAC` | `flac`                |
| `OutputFormat.MP3`  | `mp3`                 |
| `OutputFormat.ADTS` | `adts`                |

***

## TTS Options

`textToSpeech().tts(...)` accepts `CreateStreamTtsRequestPayload`. Set the core request fields plus optional controls with the request builder.

| Builder method                            | Description                                                                                                |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `.text(...)`                              | Text to synthesize. For MARS Instruct, you can include inline emotion or pacing tags in the text.          |
| `.language(...)`                          | Locale such as `CreateStreamTtsRequestPayloadLanguage.EN_US`.                                              |
| `.voiceId(...)`                           | Voice profile ID from `voiceCloning().listVoices()`.                                                       |
| `.speechModel(...)`                       | Model to use, such as `MARSFLASH`, `MARSPRO`, or `MARSINSTRUCT`.                                           |
| `.userInstructions(...)`                  | Adds style, tone, pronunciation, or delivery guidance for the request. Available only with `MARSINSTRUCT`. |
| `.outputConfiguration(...)`               | Output settings such as audio format.                                                                      |
| `.voiceSettings(...)`                     | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.              |
| `.inferenceOptions(...)`                  | Advanced generation controls for supported models.                                                         |
| `.enhanceNamedEntitiesPronunciation(...)` | Improves pronunciation for names and other named entities when supported.                                  |

***

## Text-to-Speech

The `textToSpeech().tts(...)` call streams audio as an `InputStream`. Add `userInstructions` when using `MARSINSTRUCT` to control delivery style:

```java theme={null}
InputStream audioStream = client.textToSpeech().tts(
  CreateStreamTtsRequestPayload.builder()
    .text("A warm greeting, delivered naturally.")
    .language(CreateStreamTtsRequestPayloadLanguage.EN_US)
    .voiceId(147320)
    .speechModel(CreateStreamTtsRequestPayloadSpeechModel.MARSINSTRUCT)
    .userInstructions("Speak with a friendly, upbeat tone.")
    .outputConfiguration(StreamTtsOutputConfiguration.builder().format(OutputFormat.WAV).build())
    .build()
);
// Write audioStream to a file using saveStreamToFile as shown in Quick Start.
```

***

## Voice Cloning

Voice cloning uses the voice library to list available voices and create custom clones from short reference audio samples:

### List voices

```java theme={null}
List<ListVoicesListVoicesGetResponseItem> voices = client.voiceCloning().listVoices();
for (ListVoicesListVoicesGetResponseItem item : voices) {
  item.visit(new ListVoicesListVoicesGetResponseItem.Visitor<Void>() {
    @Override
    public Void visit(Voice voice) {
      System.out.println("ID: " + voice.getId() + ", Name: " + voice.getVoiceName());
      return null;
    }
    @Override
    public Void visit(Map<String, Object> value) { return null; }
  });
}
```

### Create a custom voice

Upload a reference recording along with a display name and a `gender` identifier:

```java theme={null}
File referenceFile = new File("reference.wav");

CreateCustomVoiceOut created = client.voiceCloning().createCustomVoice(
  referenceFile,
  BodyCreateCustomVoiceCreateCustomVoicePost.builder()
    .voiceName("My Custom Voice")
    .gender(1) // gender values are API-defined; see endpoint docs for mapping
    .description("Warm and conversational.")
    .enhanceAudio(true)
    .language(Languages.EN_US.getValue())
    .build()
);
System.out.println("Created voice_id: " + created.getVoiceId());
```

***

## Dubbing

Dubbing is an asynchronous pipeline: you submit a job, poll until it succeeds, then fetch dubbed run information:

```java theme={null}
OrchestratorPipelineCallResult submitted = client.dub().endToEndDubbing(
  EndToEndDubbingRequestPayload.builder()
    .videoUrl("https://example.com/video.mp4")
    .sourceLanguage(Languages.EN_US.getValue())
    .targetLanguages(Collections.singletonList(Languages.HI_IN.getValue()))
    .build()
);

String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.dub().getEndToEndDubbingStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Dubbing failed");
  Thread.sleep(5000);
}

GetDubbedRunInfoDubResultRunIdGetResponse result = client.dub().getDubbedRunInfo(Optional.of(runId));
result.visit(new GetDubbedRunInfoDubResultRunIdGetResponse.Visitor<Void>() {
  @Override
  public Void visit(DubbingResult r) {
    System.out.println("audio_url: " + r.getAudioUrl());
    return null;
  }
  @Override
  public Void visit(Map<String, DubbingResult> map) {
    map.forEach((lang, r) -> System.out.println(lang + ": " + r.getAudioUrl()));
    return null;
  }
});
```

***

## Translation

Translation is asynchronous: create a task, poll status, then fetch translated text:

```java theme={null}
// createTranslation returns Object; convert via ObjectMappers to read task_id.
Object submittedObj = client.translation().createTranslation(
  CreateTranslationRequestPayload.builder()
    .texts(Arrays.asList("Hello, how are you?", "Welcome to Camb.ai."))
    .sourceLanguage(Languages.EN_US.getValue())
    .targetLanguage(Languages.FR_FR.getValue())
    .build()
);

OrchestratorPipelineCallResult submitted =
  ObjectMappers.JSON_MAPPER.convertValue(submittedObj, OrchestratorPipelineCallResult.class);
String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.translation().getTranslationTaskStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Translation failed");
  Thread.sleep(2000);
}

TranslationResult result = client.translation().getTranslationResult(Optional.of(runId));
result.getTexts().forEach(System.out::println);
```

***

## Transcription

Transcription is an asynchronous pipeline. Submit an audio URL, poll until success, then fetch the structured transcript:

```java theme={null}
OrchestratorPipelineCallResult submitted = client.transcription().createTranscription(
  Optional.empty(),
  Optional.empty(),
  BodyCreateTranscriptionTranscribePost.builder()
    .language(Languages.EN_US.getValue())
    .mediaUrl("https://example.com/audio.mp3")
    .build()
);

String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.transcription().getTranscriptionTaskStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Transcription failed");
  Thread.sleep(3000);
}

TranscriptionResult result = client.transcription().getTranscriptionResult(
  Optional.of(runId),
  GetTranscriptionResultTranscriptionResultRunIdGetRequest.builder().build()
);
result.getTranscript().forEach(t ->
  System.out.println(t.getStart() + " - " + t.getEnd() + ": " + t.getText())
);
```

***

## Audio separation

Audio separation uploads a local file, polls completion, then returns download URLs for the separated stems:

```java theme={null}
OrchestratorPipelineCallResult submitted =
  client.audioSeparation().createAudioSeparation(Optional.of(new File("track.mp3")));

String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.audioSeparation().getAudioSeparationStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Audio separation failed");
  Thread.sleep(3000);
}

GetAudioSeparationResultOut result = client.audioSeparation().getAudioSeparationRunInfo(Optional.of(runId));
System.out.println("foreground: " + result.getForegroundAudioUrl());
System.out.println("background: " + result.getBackgroundAudioUrl());
```

***

## Text-to-voice

Text-to-voice is asynchronous. Create a voice from a description, poll until success, then read preview URLs:

```java theme={null}
OrchestratorPipelineCallResult submitted = client.textToVoice().createTextToVoice(
  CreateTextToVoiceRequestPayload.builder()
    .text("A confident narrator introducing a documentary.")
    .voiceDescription("A smooth, rich baritone voice with gentle warmth.")
    .build()
);

String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.textToVoice().getTextToVoiceStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Text-to-voice failed");
  Thread.sleep(2000);
}

GetTextToVoiceResultOut result = client.textToVoice().getTextToVoiceResult(Optional.of(runId));
result.getPreviews().forEach(url -> System.out.println("Preview: " + url));
```

***

## Text-to-audio

Text-to-audio is asynchronous. Submit a prompt, poll until it succeeds, then download the resulting audio stream:

```java theme={null}
OrchestratorPipelineCallResult submitted = client.textToAudio().createTextToAudio(
  CreateTextToAudioRequestPayload.builder()
    .prompt("Heavy rain on a tin roof at night with distant thunder.")
    .duration(15.0)
    .audioType(TextToAudioType.SOUND)
    .build()
);

String taskId = submitted.getTaskId().orElseThrow();

Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.textToAudio().getTextToAudioStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Text-to-audio failed");
  Thread.sleep(3000);
}

InputStream audioStream = client.textToAudio().getTextToAudioResult(Optional.of(runId));
saveStreamToFile(audioStream, "soundscape.wav"); // saveStreamToFile defined in Quick Start
```

***

## Stories

The Stories endpoint ingests a document file and generates narrated audio asynchronously. The client returns a union response for submission, so you extract `task_id` with `visit(...)`:

```java theme={null}
CreateStoryStoryPostResponse submitted = client.story().createStory(
  new File("story.pdf"),
  BodyCreateStoryStoryPost.builder()
    .sourceLanguage(Languages.EN_US.getValue())
    .title("My Story")
    .build()
);

final String[] taskIdHolder = new String[1];
submitted.visit(new CreateStoryStoryPostResponse.Visitor<Void>() {
  @Override
  public Void visit(OrchestratorPipelineCallResult value) {
    taskIdHolder[0] = value.getTaskId().orElseThrow();
    return null;
  }
  @Override
  public Void visit(GetSetupStoryResultResponse value) {
    throw new RuntimeException("Unexpected setup response");
  }
});

String taskId = taskIdHolder[0];
Integer runId = null;
while (true) {
  OrchestratorPipelineResult status = client.story().getStoryStatus(taskId);
  if (status.getStatus() == TaskStatus.SUCCESS) {
    runId = status.getRunId().orElseThrow();
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Stories task failed");
  Thread.sleep(5000);
}

Map<String, Object> runInfo = client.story().getStoryRunInfo(Optional.of(runId));
System.out.println("Story run info: " + runInfo);
```

***

## Translated TTS

Translated TTS is asynchronous. Create a translated TTS task, poll until success, then inspect the success payload via `OrchestratorPipelineResult.getAdditionalProperties()`:

```java theme={null}
CreateTranslatedTtsOut created = client.translatedTts().createTranslatedTts(
  CreateTranslatedTtsRequestPayload.builder()
    .text("Good morning, welcome to our service.")
    .voiceId(147320)
    .sourceLanguage(Languages.EN_US.getValue())
    .targetLanguage(Languages.HI_IN.getValue())
    .build()
);

while (true) {
  OrchestratorPipelineResult status =
    client.translatedTts().getTranslatedTtsTaskStatus(created.getTaskId());
  if (status.getStatus() == TaskStatus.SUCCESS) {
    System.out.println(status.getAdditionalProperties());
    break;
  }
  if (status.getStatus() == TaskStatus.ERROR) throw new RuntimeException("Translated TTS failed");
  Thread.sleep(3000);
}
```

***

## Dictionaries

Dictionaries are shared term mappings that APIs can use to handle terminology consistently across transcription, dubbing, and translation:

### List dictionaries

```java theme={null}
List<DictionaryWithTerms> dictionaries = client.dictionaries().getDictionaries();
dictionaries.forEach(d -> System.out.println(d.getId() + ": " + d.getName()));
```

### Create from file and manage terms

```java theme={null}
// Create a dictionary from a CSV file.
Object created = client.dictionaries().createDictionaryFromFile(
  new File("terms.csv"),
  BodyCreateDictionaryFromFileDictionariesCreateFromFilePost.builder()
    .dictionaryName("Product Terms")
    .dictionaryDescription("Brand-specific terminology.")
    .build()
);

// Add a term to an existing dictionary.
int dictionaryId = 123;
client.dictionaries().addTermToDictionary(
  dictionaryId,
  AddDictionaryTermPayload.builder()
    .translations(Arrays.asList(
      TermTranslationInput.builder()
        .translation("Camb.ai")
        .language(Languages.HI_IN.getValue())
        .build()
    ))
    .build()
);

// Remove a specific term.
client.dictionaries().deleteDictionaryTerm(dictionaryId, /* termId */ 456);
```

***

## Custom Providers

Custom hosting providers are implemented as `ITtsProvider` instances. You call `provider.tts(request, requestOptions)` directly instead of routing through `CambApiClient`:

```java theme={null}
import core.RequestOptions;
import resources.texttospeech.requests.CreateStreamTtsRequestPayload;
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

import java.io.InputStream;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Minimal Baseten provider implementation (based on the SDK example).
class BasetenProvider implements ITtsProvider {
  private final String apiKey;
  private final String url;
  private final String referenceAudio;
  private final String referenceLanguage;
  private final OkHttpClient httpClient;
  private final ObjectMapper objectMapper;

  public BasetenProvider(String apiKey, String url, String referenceAudio, String referenceLanguage) {
    this.apiKey = apiKey;
    this.url = url;
    this.referenceAudio = referenceAudio;
    this.referenceLanguage = referenceLanguage;
    this.httpClient = new OkHttpClient();
    this.objectMapper = new ObjectMapper();
  }

  @Override
  public InputStream tts(CreateStreamTtsRequestPayload request, RequestOptions requestOptions) {
    String language = request.getLanguage().toString().toLowerCase().replace("_", "-");

    Map<String, Object> payload = new HashMap<>();
    payload.put("text", request.getText());
    payload.put("language", language);
    payload.put("output_duration", null);
    payload.put("reference_audio", referenceAudio);
    payload.put("reference_language", referenceLanguage);
    payload.put("output_format", "flac");
    payload.put("apply_ner_nlp", false);

    request.getOutputConfiguration().ifPresent(config -> {
      config.getFormat().ifPresent(f -> payload.put("output_format", f.toString().toLowerCase()));
    });

    try {
      String json = objectMapper.writeValueAsString(payload);
      RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

      Request req = new Request.Builder()
        .url(this.url)
        .addHeader("Authorization", "Api-Key " + this.apiKey)
        .post(body)
        .build();

      Response response = httpClient.newCall(req).execute();
      if (!response.isSuccessful()) {
        String errorBody = response.body() != null ? response.body().string() : "<no body>";
        throw new RuntimeException("Baseten API error " + response.code() + ": " + errorBody);
      }

      return response.body().byteStream();
    } catch (IOException e) {
      throw new RuntimeException("Network error calling Baseten: " + e.getMessage(), e);
    }
  }
}

// Usage: instantiate the provider and call tts() directly.
ITtsProvider provider = new BasetenProvider(
  System.getenv("BASETEN_API_KEY"),
  System.getenv("BASETEN_URL"),
  System.getenv("BASETEN_REFERENCE_AUDIO"),
  "en-us"
);

InputStream audioStream = provider.tts(
  CreateStreamTtsRequestPayload.builder()
    .text("Hello from Java via Baseten Mars8-Flash!")
    .language(CreateStreamTtsRequestPayloadLanguage.EN_US)
    .voiceId(1)
    .build(),
  null
);
saveStreamToFile(audioStream, "baseten_output.wav");
```

***

## Next Steps

<CardGroup>
  <Card icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat" title="Voice Agents">
    Build real-time voice agents with Pipecat
  </Card>

  <Card icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit" title="LiveKit Integration">
    Create voice agents with LiveKit
  </Card>

  <Card icon="code" href="/api-reference/endpoint/create-tts-stream" title="API Reference">
    Explore the full TTS API
  </Card>

  <Card icon="speech" href="/api-reference/endpoint/list-voices" title="Voice Library">
    Browse available voices
  </Card>
</CardGroup>

## Resources

* [GitHub: camb-ai/cambai-java-sdk](https://github.com/Camb-ai/cambai-java-sdk)
* [SDK Examples](https://github.com/Camb-ai/cambai-java-sdk/tree/master/examples)
* [API Reference](https://docs.camb.ai/api-reference/endpoint/create-tts-stream)


# PHP SDK
Source: https://docs.camb.ai/sdk-guides/php-sdk

Install and use the Camb.ai PHP SDK with PHP 8.1+ and Composer

The official PHP SDK for Camb.ai provides access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, and audio generation through `CambAIClient` for common workflows and generated API classes for the rest of the HTTP surface. The SDK is synchronous: call APIs from your PHP process or queue workers and poll until asynchronous jobs finish.

## Installation

Requires PHP 8.1 or later and Composer. Add the Camb.ai repository and package to your `composer.json`:

```json theme={null}
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/Camb-ai/cambai-php-sdk.git"
    }
  ],
  "require": {
    "camb-ai/cambai-php-sdk": "*@dev"
  }
}
```

Then run:

```bash theme={null}
composer install
```

***

## Authentication

Get your API key from [Camb.ai Studio](https://studio.camb.ai) and read it from an environment variable so it never appears in source control.

`CambAIClient` wires TTS (via a provider), Text-to-Voice, Text-to-Audio, and Dubbing. Other endpoints use generated `*Api` classes with a shared `Configuration` and Guzzle client. There is no separate async client in PHP: run blocking calls in requests or workers.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Configuration;
use GuzzleHttp\Client;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);
```

<Tip>
  Load `CAMB_API_KEY` from a `.env` file during local development with [vlucas/phpdotenv](https://github.com/vlucas/phpdotenv) or your framework’s env layer.
</Tip>

The sections below that use `$httpClient` and `$config` assume you built them as shown. `CambAIClient` already applies the same API key and timeout internally.

***

## Quick Start

Streaming TTS returns a readable stream. `DefaultTtsProvider::tts()` maps to the streaming endpoint. Read the stream in chunks and write them to disk.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Model\CreateStreamTTSRequestPayload;
use Camb\Ai\Model\StreamTTSOutputConfiguration;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$outputConfig = new StreamTTSOutputConfiguration();
$outputConfig->setFormat('wav');

$payload = new CreateStreamTTSRequestPayload();
$payload->setText('Hello from Camb.ai.');
$payload->setVoiceId(147320);
$payload->setLanguage(CreateStreamTTSRequestPayload::LANGUAGE_EN_US);
$payload->setSpeechModel(CreateStreamTTSRequestPayload::SPEECH_MODEL_MARS_FLASH);
$payload->setOutputConfiguration($outputConfig);

$audioStream = $client->tts()->tts($payload);
$outputFile = 'output.wav';
$file = fopen($outputFile, 'w');
if ($file) {
    while (!$audioStream->eof()) {
        fwrite($file, $audioStream->fread(8192));
    }
    fclose($file);
}
```

### Non-streaming TTS

If you need a task-based TTS job instead of streaming, call `createTts()` on the same provider, poll task status, then fetch run metadata.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Model\CreateTTSRequestPayload;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\OrchestratorPipelineResult;
use Camb\Ai\Model\TaskStatus;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$payload = new CreateTTSRequestPayload();
$payload->setText('Hello from Camb.ai.');
$payload->setVoiceId(147320);
$payload->setLanguage(Languages::EN_US);
$payload->setSpeechModel('mars-flash');

$created = $client->tts()->createTts($payload);
$taskId = $created->getTaskId();

while (true) {
    /** @var OrchestratorPipelineResult $status */
    $status = $client->textToSpeech->getTtsResultTtsTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $ttsRunInfo = $client->textToSpeech->getTtsRunInfoTtsResultRunIdGet($runId);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
    sleep(2);
}
```

When the loop exits with success, `$ttsRunInfo` holds download URLs and metadata for the synthesized audio.

***

## Models

Camb.ai offers MARS models tuned for different quality and latency requirements. Pass `speech_model` on streaming payloads using `CreateStreamTTSRequestPayload` constants or string literals. If you omit it, the API applies its default model.

| Model                 | Sample Rate | Best For                                                                     |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `mars-8.1-flash-beta` | 48 kHz      | Faster MARS 8.1 generation; same quality improvements as `mars-8.1-pro-beta` |
| `mars-8.1-pro-beta`   | 48 kHz      | Improved pronunciation, expressiveness, and prosody over `mars-pro`          |
| `mars-flash`          | 22.05 kHz   | Low-latency real-time applications and conversational AI                     |
| `mars-pro`            | 48 kHz      | High-fidelity audio production and long-form content                         |
| `mars-instruct`       | 22.05 kHz   | Fine-grained tone and style control via text instructions                    |

The tab snippets below reuse `$client` from [Quick Start](#quick-start).

<Tabs>
  <Tab title="MARS Flash">
    ```php theme={null}
    $payload = new CreateStreamTTSRequestPayload();
    $payload->setText('Hey, I can respond much faster.');
    $payload->setVoiceId(147320);
    $payload->setLanguage(CreateStreamTTSRequestPayload::LANGUAGE_EN_US);
    $payload->setSpeechModel(CreateStreamTTSRequestPayload::SPEECH_MODEL_MARS_FLASH);
    $payload->setOutputConfiguration($outputConfig);

    $stream = $client->tts()->tts($payload);
    ```
  </Tab>

  <Tab title="MARS Pro">
    ```php theme={null}
    $payload = new CreateStreamTTSRequestPayload();
    $payload->setText('High-fidelity audio for production use.');
    $payload->setVoiceId(147320);
    $payload->setLanguage(CreateStreamTTSRequestPayload::LANGUAGE_EN_US);
    $payload->setSpeechModel(CreateStreamTTSRequestPayload::SPEECH_MODEL_MARS_PRO);
    $payload->setOutputConfiguration($outputConfig);

    $stream = $client->tts()->tts($payload);
    ```
  </Tab>

  <Tab title="MARS Instruct">
    ```php theme={null}
    $payload = new CreateStreamTTSRequestPayload();
    $payload->setText('[warm, friendly] Great to meet you!');
    $payload->setVoiceId(147320);
    $payload->setLanguage(CreateStreamTTSRequestPayload::LANGUAGE_EN_US);
    $payload->setSpeechModel(CreateStreamTTSRequestPayload::SPEECH_MODEL_MARS_INSTRUCT);
    $payload->setUserInstructions('Speak warmly and with enthusiasm.');
    $payload->setOutputConfiguration($outputConfig);

    $stream = $client->tts()->tts($payload);
    ```
  </Tab>
</Tabs>

For beta models, pass the string on the payload when no constant exists:

```php theme={null}
$payload->setSpeechModel('mars-8.1-flash-beta');
```

***

## TTS Options

Streaming TTS uses `CreateStreamTTSRequestPayload`. Set the core request fields plus optional controls before calling `$client->tts()->tts($payload)`.

| Setter                                      | Description                                                                                                |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `setText(...)`                              | Text to synthesize. For MARS Instruct, you can include inline emotion or pacing tags in the text.          |
| `setLanguage(...)`                          | Locale such as `CreateStreamTTSRequestPayload::LANGUAGE_EN_US`.                                            |
| `setVoiceId(...)`                           | Voice profile ID from `listVoicesListVoicesGet()`.                                                         |
| `setSpeechModel(...)`                       | Model to use, such as `SPEECH_MODEL_MARS_FLASH`, `SPEECH_MODEL_MARS_PRO`, or `SPEECH_MODEL_MARS_INSTRUCT`. |
| `setUserInstructions(...)`                  | Adds style, tone, pronunciation, or delivery guidance for the request. Available only with MARS Instruct.  |
| `setOutputConfiguration(...)`               | Output settings such as audio format.                                                                      |
| `setVoiceSettings(...)`                     | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.              |
| `setInferenceOptions(...)`                  | Advanced generation controls for supported models.                                                         |
| `setEnhanceNamedEntitiesPronunciation(...)` | Improves pronunciation for names and other named entities when supported.                                  |

***

## Voices

`VoiceCloningApi` lists voices and creates custom voices. Instantiate it with `$httpClient` and `$config` from [Authentication](#authentication).

### List voices

Call `listVoicesListVoicesGet()` to retrieve voices on your account. The `id` field is the `voice_id` you pass to TTS.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\VoiceCloningApi;
use Camb\Ai\Configuration;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$voiceApi = new VoiceCloningApi($httpClient, $config);
$voices = $voiceApi->listVoicesListVoicesGet();

foreach ($voices as $voice) {
    echo 'ID: ' . $voice->getId() . ', Name: ' . $voice->getVoiceName() . PHP_EOL;
}
```

### Create a custom voice

Upload a reference clip as [`SplFileObject`](https://www.php.net/manual/en/class.splfileobject.php). Set `Gender` using the numeric enum values exposed on the model class (for example `Gender::NUMBER_1`). Optional `enhance_audio` helps noisy recordings.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\VoiceCloningApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\Gender;
use Camb\Ai\Model\Languages;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$voiceApi = new VoiceCloningApi($httpClient, $config);
$file = new \SplFileObject(__DIR__ . '/reference.wav');

$result = $voiceApi->createCustomVoiceCreateCustomVoicePost(
    'My Custom Voice',
    Gender::NUMBER_1,
    $file,
    null,
    'Warm and conversational.',
    null,
    30,
    Languages::EN_US,
    true
);
```

***

## Language Support

Camb.ai supports up to 312 languages depending on the MARS model — see [Language Support](/language-support) for the full per-model locale list. Prefer `Languages` enum values on payloads so editors catch invalid codes.

```php theme={null}
use Camb\Ai\Model\Languages;

$payload->setLanguage(Languages::EN_US);
$payload->setLanguage(Languages::FR_FR);
```

To fetch supported languages at runtime, use `LanguagesApi` with the same configuration pattern as voice cloning.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\LanguagesApi;
use Camb\Ai\Configuration;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$langApi = new LanguagesApi($httpClient, $config);

$sourceLanguages = $langApi->getSourceLanguagesSourceLanguagesGet();
$targetLanguages = $langApi->getTargetLanguagesTargetLanguagesGet();
```

Per-model language lists are documented under [MARS Models](/models).

***

## Dubbing

End-to-end dubbing takes a public video URL, translates the track, and synthesizes speech that matches the speaker. Submit the job, poll status, then read URLs from the dubbing result.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Model\EndToEndDubbingRequestPayload;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TaskStatus;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$payload = new EndToEndDubbingRequestPayload();
$payload->setVideoUrl('https://example.com/video.mp4');
$payload->setSourceLanguage(Languages::EN_US);
$payload->setTargetLanguages([Languages::HI_IN, Languages::FR_FR]);

$queued = $client->dub->endToEndDubbingDubPost($payload);
$taskId = $queued->getTaskId();

while (true) {
    sleep(5);
    $statusResult = $client->dub->getEndToEndDubbingStatusDubTaskIdGet($taskId);
    $status = $statusResult->getStatus();

    if ($status === TaskStatus::SUCCESS) {
        $runId = $statusResult->getRunId();
        $dubResult = $client->dub->getDubbedRunInfoDubResultRunIdGet($runId);
        $videoUrl = $dubResult->getDubbingResult()->getVideoUrl();
        break;
    }

    if ($status === TaskStatus::ERROR) {
        break;
    }
}
```

### Get transcript

After a successful dub, fetch the transcript for a target language using `getDubbedRunTranscriptTranscriptRunIdLanguageGet()`.

```php theme={null}
$transcript = $client->dub->getDubbedRunTranscriptTranscriptRunIdLanguageGet(
    $runId,
    Languages::HI_IN
);
```

***

## Translation

Translation accepts an ordered list of strings and returns translations in the same order. Submit a job, poll `getTranslationTaskStatusTranslateTaskIdGet()`, then load results with `getTranslationResultTranslationResultRunIdGet()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\TranslationApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\CreateTranslationRequestPayload;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TaskStatus;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$translationApi = new TranslationApi($httpClient, $config);

$payload = new CreateTranslationRequestPayload();
$payload->setTexts(['Hello, how are you?', 'Welcome to Camb.ai.']);
$payload->setSourceLanguage(Languages::EN_US);
$payload->setTargetLanguage(Languages::FR_FR);

$submit = $translationApi->createTranslationTranslatePost($payload);
$taskId = $submit->task_id;

while (true) {
    sleep(2);
    $status = $translationApi->getTranslationTaskStatusTranslateTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $result = $translationApi->getTranslationResultTranslationResultRunIdGet($runId);
        foreach ($result->getTexts() as $text) {
            echo $text . PHP_EOL;
        }
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

<Note>
  `createTranslationTranslatePost()` processes every string in `texts` in a single job and preserves ordering in the result. The OpenAPI client types this response as `mixed`, so the JSON-decoded object exposes `task_id` as a property rather than `getTaskId()`.
</Note>

***

## Transcription

Send audio or video by URL or as an uploaded file. Poll `getTranscriptionTaskStatusTranscribeTaskIdGet()`, then call `getTranscriptionResultTranscriptionResultRunIdGet()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\TranscriptionApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TaskStatus;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$transcriptionApi = new TranscriptionApi($httpClient, $config);

$queued = $transcriptionApi->createTranscriptionTranscribePost(
    Languages::EN_US,
    null,
    null,
    'https://example.com/audio.mp3'
);
$taskId = $queued->getTaskId();

while (true) {
    sleep(3);
    $status = $transcriptionApi->getTranscriptionTaskStatusTranscribeTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $result = $transcriptionApi->getTranscriptionResultTranscriptionResultRunIdGet($runId, true);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

For a local file, pass [`SplFileObject`](https://www.php.net/manual/en/class.splfileobject.php) as the `file` argument (fifth parameter).

```php theme={null}
$file = new \SplFileObject(__DIR__ . '/audio.mp3');
$queued = $transcriptionApi->createTranscriptionTranscribePost(
    Languages::EN_US,
    null,
    null,
    null,
    $file
);
```

***

## Audio Separation

Separation splits a mixed recording into stems. Upload media with `createAudioSeparationAudioSeparationPost()`, poll `getAudioSeparationStatusAudioSeparationTaskIdGet()`, then read `getAudioSeparationRunInfoAudioSeparationResultRunIdGet()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\AudioSeparationApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\TaskStatus;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$audioSeparationApi = new AudioSeparationApi($httpClient, $config);
$media = new \SplFileObject(__DIR__ . '/track.mp3');

$queued = $audioSeparationApi->createAudioSeparationAudioSeparationPost(null, null, $media);
$taskId = $queued->getTaskId();

while (true) {
    sleep(3);
    $status = $audioSeparationApi->getAudioSeparationStatusAudioSeparationTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $result = $audioSeparationApi->getAudioSeparationRunInfoAudioSeparationResultRunIdGet($runId);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

***

## Text-to-Voice

Text-to-Voice generates a new voice from a written description. `CambAIClient` exposes `textToVoice`. Poll until `TaskStatus::SUCCESS`, then inspect previews from `getTextToVoiceResultTextToVoiceResultRunIdGet()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Model\CreateTextToVoiceRequestPayload;
use Camb\Ai\Model\TaskStatus;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$payload = new CreateTextToVoiceRequestPayload();
$payload->setText('A confident narrator introducing a documentary.');
$payload->setVoiceDescription('Deep, measured baritone with a slight gravel. Calm and authoritative.');

$queued = $client->textToVoice->createTextToVoiceTextToVoicePost($payload);
$taskId = $queued->getTaskId();

while (true) {
    sleep(2);
    $status = $client->textToVoice->getTextToVoiceStatusTextToVoiceTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $voiceResult = $client->textToVoice->getTextToVoiceResultTextToVoiceResultRunIdGet($runId);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

<Note>
  Preview URLs let you audition variations. Use the voice ID you choose with streaming TTS when you move to production.
</Note>

***

## Text-to-Audio

Text-to-Audio turns a descriptive prompt into sound effects or ambience. Use `textToAudio` on the client, poll status, then stream the WAV result to disk.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\CambAIClient;
use Camb\Ai\Model\CreateTextToAudioRequestPayload;
use Camb\Ai\Model\TaskStatus;
use Camb\Ai\Model\TextToAudioType;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$payload = new CreateTextToAudioRequestPayload();
$payload->setPrompt('Heavy rain on a tin roof at night with distant thunder.');
$payload->setDuration(15.0);
$payload->setAudioType(TextToAudioType::SOUND);

$queued = $client->textToAudio->createTextToAudioTextToSoundPost($payload);
$taskId = $queued->getTaskId();

while (true) {
    sleep(2);
    $status = $client->textToAudio->getTextToAudioStatusTextToSoundTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $audioStream = $client->textToAudio->getTextToAudioResultTextToSoundResultRunIdGet($runId);
        $out = fopen('soundscape.wav', 'w');
        while (!$audioStream->eof()) {
            fwrite($out, $audioStream->fread(8192));
        }
        fclose($out);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

***

## Stories

The Stories API ingests a document, builds narration, and returns audio output. Use `StoryApi` with `createStoryStoryPost()`, poll `getStoryStatusStoryTaskIdGet()`, then load `getStoryRunInfoStoryResultRunIdGet()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\StoryApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TaskStatus;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$storyApi = new StoryApi($httpClient, $config);
$file = new \SplFileObject(__DIR__ . '/story.pdf');

$queued = $storyApi->createStoryStoryPost($file, Languages::EN_US, null, 'My Story');
$taskId = $queued->getTaskId();

while (true) {
    sleep(5);
    $status = $storyApi->getStoryStatusStoryTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        $runId = $status->getRunId();
        $info = $storyApi->getStoryRunInfoStoryResultRunIdGet($runId);
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

***

## Translated TTS

Translated TTS runs translation and synthesis together. Use `TranslatedTTSApi`, poll `getTranslatedTtsTaskStatusTranslatedTtsTaskIdGet()`, and inspect the orchestrator payload when the job succeeds.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\TranslatedTTSApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\CreateTranslatedTTSRequestPayload;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TaskStatus;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$ttsApi = new TranslatedTTSApi($httpClient, $config);

$payload = new CreateTranslatedTTSRequestPayload();
$payload->setText('Good morning, welcome to our service.');
$payload->setVoiceId(147320);
$payload->setSourceLanguage(Languages::EN_US);
$payload->setTargetLanguage(Languages::HI_IN);

$queued = $ttsApi->createTranslatedTtsTranslatedTtsPost($payload);
$taskId = $queued->getTaskId();

while (true) {
    sleep(3);
    $status = $ttsApi->getTranslatedTtsTaskStatusTranslatedTtsTaskIdGet($taskId);
    if ($status->getStatus() === TaskStatus::SUCCESS) {
        break;
    }
    if ($status->getStatus() === TaskStatus::ERROR) {
        break;
    }
}
```

***

## Dictionaries

Dictionaries store term mappings for dubbing and translation workflows.

### List dictionaries

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\DictionariesApi;
use Camb\Ai\Configuration;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$dictApi = new DictionariesApi($httpClient, $config);
$dictionaries = $dictApi->getDictionariesDictionariesGet();

foreach ($dictionaries as $dictionary) {
    echo $dictionary->getId() . ': ' . $dictionary->getName() . PHP_EOL;
}
```

### Create from file

```php theme={null}
$dictionaryFile = new \SplFileObject(__DIR__ . '/terms.csv');
$dictApi->createDictionaryFromFileDictionariesCreateFromFilePost(
    $dictionaryFile,
    'Product Terms',
    null,
    'Brand-specific terminology for our product line.'
);
```

### Manage terms

`TermTranslationInput` pairs localized text with a `Languages` value. Build `AddDictionaryTermPayload` and call `addTermToDictionaryDictionariesDictionaryIdAddTermPost()`.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Camb\Ai\Api\DictionariesApi;
use Camb\Ai\Configuration;
use Camb\Ai\Model\AddDictionaryTermPayload;
use Camb\Ai\Model\Languages;
use Camb\Ai\Model\TermTranslationInput;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()->setApiKey('x-api-key', getenv('CAMB_API_KEY'));
$httpClient = new Client(['timeout' => 300.0]);

$dictApi = new DictionariesApi($httpClient, $config);

$termInput = new TermTranslationInput();
$termInput->setTranslation('कैम्ब.एआई');
$termInput->setLanguage(Languages::HI_IN);

$payload = new AddDictionaryTermPayload();
$payload->setTranslations([$termInput]);

$dictionaryId = 123;
$dictApi->addTermToDictionaryDictionariesDictionaryIdAddTermPost($dictionaryId, $payload);

$dictApi->deleteDictionaryTermDictionariesTermDictionaryIdTermIdDelete($dictionaryId, 'term_456');

$dictApi->deleteDictionaryDictionariesDictionaryIdDelete($dictionaryId);
```

***

## Custom Provider

If you self-host MARS on Baseten or another backend, implement `TtsProviderInterface` and register it with `setTtsProvider()`. See [Custom Cloud Providers](/custom-cloud-providers) for deployment details.

### Baseten

Point the provider at your deployment URL and supply credentials from the environment.

```php theme={null}
<?php
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/BasetenTtsProvider.php';

use Camb\Ai\CambAIClient;

$client = new CambAIClient(getenv('CAMB_API_KEY'));

$basetenProvider = new BasetenTtsProvider(
    getenv('BASETEN_API_KEY'),
    getenv('BASETEN_MODEL_URL')
);
$client->setTtsProvider($basetenProvider);
```

Copy [`BasetenTtsProvider.php`](https://github.com/Camb-ai/cambai-php-sdk/blob/master/examples/BasetenTtsProvider.php) from the SDK `examples` folder into your project (next to the script or on your include path) so the `require_once` resolves.

***

## Next Steps

<CardGroup>
  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice agents with Pipecat
  </Card>

  <Card title="LiveKit Integration" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit">
    Create voice agents with LiveKit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Explore the full TTS API
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>

***

## Resources

* [GitHub: camb-ai/cambai-php-sdk](https://github.com/Camb-ai/cambai-php-sdk)
* [SDK Examples](https://github.com/Camb-ai/cambai-php-sdk/tree/master/examples)
* [API Reference](/api-reference/endpoint/create-tts-stream)


# Python SDK
Source: https://docs.camb.ai/sdk-guides/python-sdk

Install and use the Python SDK with sync and async clients for Python 3.9+

The official Python SDK for Camb.ai provides convenient access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, and audio generation. It ships synchronous and asynchronous clients with streaming audio helpers and typed language enums.

## Installation

```bash theme={null}
pip install camb-sdk
```

Requires Python 3.9 or later.

***

## Authentication

Get your API key from [Camb.ai Studio](https://studio.camb.ai) and set it as an environment variable. The client reads it via `os.getenv("CAMB_API_KEY")` so your key never has to appear in source code.

The SDK ships two clients. Use `CambAI` for scripts, data pipelines, and anything thread-managed. Use `AsyncCambAI` for web servers (FastAPI, Sanic) and high-concurrency applications where blocking would hurt throughput.

```python theme={null}
import os
from camb.client import CambAI, AsyncCambAI

# Synchronous — for scripts and data pipelines
client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

# Asynchronous — for web servers and high-concurrency applications
async_client = AsyncCambAI(api_key=os.getenv("CAMB_API_KEY"))
```

***

## Quick Start

The quickest way to get started is streaming TTS audio directly to a file. `tts()` returns a byte iterator that `save_stream_to_file` writes in one call:

```python theme={null}
import os
from camb.client import CambAI, save_stream_to_file

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

stream = client.text_to_speech.tts(
    text="Hello from Camb.ai.",
    language="en-us",
    voice_id=147320,
    speech_model="mars-flash",
)
save_stream_to_file(stream, "output.wav")
```

For async applications, use `AsyncCambAI` and `save_async_stream_to_file`. The interface is identical to the sync client:

```python theme={null}
import asyncio
import os
from camb.client import AsyncCambAI, save_async_stream_to_file

client = AsyncCambAI(api_key=os.getenv("CAMB_API_KEY"))

async def main():
    stream = client.text_to_speech.tts(
        text="Hello from Camb.ai.",
        language="en-us",
        voice_id=147320,
        speech_model="mars-flash",
    )
    await save_async_stream_to_file(stream, "output.wav")

asyncio.run(main())
```

***

## Models

Camb.ai offers MARS models tuned for different quality and latency requirements. Pass the model name as `speech_model` in any TTS call. If you omit it, the API uses a default model.

| Model                 | Sample Rate | Best For                                                                     |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `mars-8.1-flash-beta` | 48 kHz      | Faster MARS 8.1 generation; same quality improvements as `mars-8.1-pro-beta` |
| `mars-8.1-pro-beta`   | 48 kHz      | Improved pronunciation, expressiveness, and prosody over `mars-pro`          |
| `mars-flash`          | 22.05 kHz   | Low-latency real-time applications and conversational AI                     |
| `mars-pro`            | 48 kHz      | High-fidelity audio production and long-form content                         |
| `mars-instruct`       | 22.05 kHz   | Fine-grained tone and style control via text instructions                    |

<Tabs>
  <Tab title="MARS Flash">
    ```python theme={null}
    stream = client.text_to_speech.tts(
        text="Hey, I can respond much faster.",
        language="en-us",
        voice_id=147320,
        speech_model="mars-flash",
    )
    ```

    **Best for:** Voice agents, real-time applications

    **Sample rate:** 22.05 kHz
  </Tab>

  <Tab title="MARS Pro">
    ```python theme={null}
    stream = client.text_to_speech.tts(
        text="High-fidelity audio for production use.",
        language="en-us",
        voice_id=147320,
        speech_model="mars-pro",
    )
    ```

    **Best for:** Audio production, dubbing, long-form content

    **Sample rate:** 48 kHz
  </Tab>

  <Tab title="MARS Instruct">
    ```python theme={null}
    stream = client.text_to_speech.tts(
        text="[warm, friendly] Great to meet you!",
        language="en-us",
        voice_id=147320,
        speech_model="mars-instruct",
        user_instructions="Speak warmly and with enthusiasm.",
    )
    ```

    **Best for:** Fine-grained control over tone and delivery

    **Sample rate:** 22.05 kHz
  </Tab>
</Tabs>

***

## TTS Options

The `text_to_speech.tts(...)` method accepts the core request fields plus optional controls for model behavior and output format.

| Option                                 | Type                           | Description                                                                                                                |
| -------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `text`                                 | string                         | Text to synthesize. For `mars-instruct`, you can include inline emotion or pacing tags in the text.                        |
| `language`                             | string                         | BCP-47 locale such as `en-us`.                                                                                             |
| `voice_id`                             | integer                        | Voice profile ID from `list_voices()`.                                                                                     |
| `speech_model`                         | string                         | Model to use, such as `mars-8.1-flash-beta`, `mars-pro`, or `mars-instruct`.                                               |
| `user_instructions`                    | string                         | Adds style, tone, pronunciation, or delivery guidance for the request. Available only with `speech_model="mars-instruct"`. |
| `output_configuration`                 | `StreamTtsOutputConfiguration` | Output settings such as audio format.                                                                                      |
| `voice_settings`                       | object                         | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.                              |
| `inference_options`                    | object                         | Advanced generation controls for supported models.                                                                         |
| `enhance_named_entities_pronunciation` | boolean                        | Improves pronunciation for names and other named entities when supported.                                                  |

Example with `mars-instruct` delivery guidance:

```python theme={null}
from camb.types import StreamTtsOutputConfiguration

stream = client.text_to_speech.tts(
    text="[warm, friendly] Great to meet you!",
    language="en-us",
    voice_id=147320,
    speech_model="mars-instruct",
    user_instructions="Speak warmly and with enthusiasm.",
    output_configuration=StreamTtsOutputConfiguration(format="wav"),
)
```

***

## Voices

### List Voices

Call `list_voices()` to retrieve all voices available on your account, including pre-built library voices and any custom voices you have created. The `id` field is what you pass as `voice_id` in TTS calls.

```python theme={null}
import os
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

voices = client.voice_cloning.list_voices()
for voice in voices:
    print(f"ID: {voice['id']}  Name: {voice['voice_name']}  Gender: {voice['gender']}")
```

### Create a Custom Voice

To clone a voice, upload a short reference audio sample alongside a name and gender. Setting `enhance_audio=True` applies preprocessing that improves cloning quality on recordings with background noise.

```python theme={null}
import os
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

with open("reference.wav", "rb") as f:
    result = client.voice_cloning.create_custom_voice(
        voice_name="My Custom Voice",
        gender="female",
        file=f,
        description="Warm and conversational.",
        enhance_audio=True,
    )

print(f"Voice created: {result}")
```

***

## Language Support

Camb.ai supports up to 312 languages depending on the MARS model — see [Language Support](/language-support) for the full per-model locale list. You can pass locale strings directly, but using the `Languages` enum is recommended because it provides autocomplete in your editor and prevents typos in language codes.

```python theme={null}
from camb.types.language_enums import Languages

print(Languages.EN_US)   # en-us
print(Languages.HI_IN)   # hi-in
print(Languages.FR_FR)   # fr-fr
print(Languages.DE_DE)   # de-de
print(Languages.JA_JP)   # ja-jp
```

To fetch the full list of supported languages at runtime, use the `languages` sub-client. Source languages are what you can transcribe or translate from; target languages are what you can translate or dub into.

```python theme={null}
import os
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

source_languages = client.languages.get_source_languages()
target_languages = client.languages.get_target_languages()

for lang in source_languages:
    print(lang)
```

Languages supported per model are listed at [MARS Models](/models).

***

## Dubbing

The dubbing pipeline takes a publicly accessible video URL, translates the audio track into your target language, and synthesizes speech using a clone of the original speaker's voice. Dubbing is asynchronous: you submit the job, poll for completion, and then fetch the result.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.dub.create_dub(
    video_url="https://example.com/video.mp4",
    source_language=Languages.EN_US,
    target_language=Languages.HI_IN,
)

while True:
    status = client.dub.get_dubbing_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.dub.get_dubbed_run_info(status.run_id)
        print(f"Video: {result.video_url}")
        print(f"Audio: {result.audio_url}")
        break
    time.sleep(5)
```

To dub into multiple languages in a single job, replace `target_language` with the `target_languages` list:

```python theme={null}
response = client.dub.create_dub(
    video_url="https://example.com/video.mp4",
    source_language=Languages.EN_US,
    target_languages=[Languages.HI_IN, Languages.FR_FR, Languages.DE_DE],
)
```

### Get Transcript

Once a dubbing job completes, you can retrieve the full transcript for any target language using the `run_id` returned by `get_dubbing_status`.

```python theme={null}
transcript = client.dub.get_dubbed_run_transcript(
    run_id=status.run_id,
    language=Languages.HI_IN,
)
print(transcript)
```

***

## Translation

The translation API accepts a list of text strings and returns them translated into the target language in the same order. Like dubbing, translation is asynchronous. You submit a job and poll until the status reaches `SUCCESS`.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.translation.create_translation(
    texts=["Hello, how are you?", "Welcome to Camb.ai."],
    source_language=Languages.EN_US,
    target_language=Languages.FR_FR,
)

while True:
    status = client.translation.get_translation_task_status(task_id=response["task_id"])
    if status.status == "SUCCESS":
        result = client.translation.get_translation_result(run_id=status.run_id)
        for text in result.texts:
            print(text)
        break
    time.sleep(2)
```

<Note>
  `create_translation` accepts a list of strings under `texts`. All strings are translated in a single job and returned in order.
</Note>

***

## Transcription

Submit an audio or video file for transcription and retrieve the result once processing completes. You can pass a remote URL via `media_url` or upload a local file via `media_file`.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.transcription.create_transcription(
    language=Languages.EN_US,
    media_url="https://example.com/audio.mp3",
)

while True:
    status = client.transcription.get_transcription_task_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.transcription.get_transcription_result(
            run_id=status.run_id,
        )
        print(result)
        break
    time.sleep(3)
```

To transcribe a local file rather than a URL, open it in binary mode and pass it via `media_file`:

```python theme={null}
with open("audio.mp3", "rb") as f:
    response = client.transcription.create_transcription(
        language=Languages.EN_US,
        media_file=f,
    )
```

### Subtitle-ready formatting

By default the transcript is segmented by natural speech patterns. Pass `formatting_options` to segment it into subtitle-ready cues instead, then request the export directly as `srt` or `vtt` on the result call:

```python theme={null}
from camb.types.subtitle_formatting_options import SubtitleFormattingOptions

formatting_options = SubtitleFormattingOptions(
    max_segment_duration_in_seconds=6,
    max_characters_in_segment=42,
)

response = client.transcription.create_transcription(
    language=Languages.EN_US,
    media_url="https://example.com/audio.mp3",
    formatting_options=formatting_options,
)

# ... after polling reaches SUCCESS
result = client.transcription.get_transcription_result(
    status.run_id,
    format_type="srt",
    data_type="raw_data",
)
print(result.transcript)
```

<Note>
  With `format_type`/`data_type` set, `get_transcription_result` returns a `TranscriptExportResult` with a single `transcript` string instead of the segment array.
</Note>

***

## Subtitles

The subtitles pipeline transcribes the source language, translates into any number of target languages, and, when you pass `formatting_options`, segments every language into subtitle-ready cues, in a single job. It's asynchronous like transcription: submit a `media_url` (local file upload is not supported), poll, then retrieve the result per language.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.subtitles.create_subtitle(
    source_language=Languages.EN_US,
    target_languages=[Languages.ES_ES],
    media_url="https://example.com/audio.mp3",
)

while True:
    status = client.subtitles.get_subtitle_task_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.subtitles.get_subtitle_result_for_language(
            run_id=status.run_id,
            language=Languages.ES_ES,
        )
        transcript = result["transcript"] if isinstance(result, dict) else result.transcript
        print(transcript)
        break
    time.sleep(5)
```

<Note>
  `target_languages` is required and must be a non-empty list, even for a single language (`[Languages.ES_ES]`). Subtitle results come back as a plain dict, not a typed model, so the `isinstance` check above is the safe way to read `transcript` regardless of shape.
</Note>

Pass `formatting_options` the same way as transcription to get subtitle-ready cues, and request a direct export with `format_type`/`data_type`:

```python theme={null}
from camb.types.subtitle_formatting_options import SubtitleFormattingOptions

formatting_options = SubtitleFormattingOptions(
    max_segment_duration_in_seconds=6,
    max_characters_in_segment=42,
)

response = client.subtitles.create_subtitle(
    source_language=Languages.EN_US,
    target_languages=[Languages.ES_ES],
    media_url="https://example.com/audio.mp3",
    formatting_options=formatting_options,
)

# ... after polling reaches SUCCESS
result = client.subtitles.get_subtitle_result_for_language(
    run_id=status.run_id,
    language=Languages.ES_ES,
    format_type="vtt",
    data_type="raw_data",
)
print(result["transcript"] if isinstance(result, dict) else result.transcript)
```

To fetch every target language on the run in one call, drop the `language` argument and call `client.subtitles.get_subtitle_result(run_id=status.run_id)` instead.

***

## Audio Separation

Audio separation splits a mixed audio track into its vocal and background components. After the job completes, the result contains separate download URLs for each stem so you can use them independently.

```python theme={null}
import os
import time
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

with open("track.mp3", "rb") as f:
    response = client.audio_separation.create_audio_separation(media_file=f)

while True:
    status = client.audio_separation.get_audio_separation_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.audio_separation.get_audio_separation_run_info(run_id=status.run_id)
        print(result)
        break
    time.sleep(3)
```

***

## Text-to-Voice

Text-to-Voice creates a brand-new synthetic voice from a written description of the desired vocal characteristics. The API generates several audio samples so you can audition variations before deciding which voice ID to use in production.

```python theme={null}
import os
import time
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.text_to_voice.create_text_to_voice(
    text="A confident narrator introducing a documentary.",
    voice_description="Deep, measured baritone with a slight gravel. Calm and authoritative.",
)

while True:
    status = client.text_to_voice.get_text_to_voice_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.text_to_voice.get_text_to_voice_result(run_id=status.run_id)
        print(result)
        break
    time.sleep(3)
```

<Note>
  The result contains multiple sample audio URLs. Preview them and use the `voice_id` of your preferred sample with `client.text_to_speech.tts`.
</Note>

***

## Text-to-Audio

Text-to-Audio generates sound effects or ambient soundscapes from a descriptive text prompt. The job is asynchronous, and the result is a streamable audio file you can save with `save_stream_to_file` once processing completes.

```python theme={null}
import os
import time
from camb.client import CambAI, save_stream_to_file

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.text_to_audio.create_text_to_audio(
    prompt="Heavy rain on a tin roof at night with distant thunder.",
    duration=15,
    audio_type="sound",
)

while True:
    status = client.text_to_audio.get_text_to_audio_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        stream = client.text_to_audio.get_text_to_audio_result(run_id=status.run_id)
        save_stream_to_file(stream, "soundscape.mp3")
        print("Saved to soundscape.mp3")
        break
    time.sleep(3)
```

***

## Stories

The Stories API takes a document file, structures its content into a narrative, and returns a fully narrated audio output. You can provide a custom narrator voice ID; if omitted, the API selects a default voice appropriate for the source language.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

with open("story.pdf", "rb") as f:
    response = client.story.create_story(
        file=f,
        source_language=Languages.EN_US,
        title="My Story",
    )

while True:
    status = client.story.get_story_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        result = client.story.get_story_run_info(run_id=status.run_id)
        print(result)
        break
    time.sleep(5)
```

***

## Translated TTS

Translated TTS combines translation and speech synthesis into a single asynchronous job. The text is translated into the target language and then spoken using the voice you specify, without needing to run translation and TTS as separate steps.

```python theme={null}
import os
import time
from camb.client import CambAI
from camb.types.language_enums import Languages

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

response = client.translated_tts.create_translated_tts(
    text="Good morning, welcome to our service.",
    voice_id=147320,
    source_language=Languages.EN_US,
    target_language=Languages.HI_IN,
)

while True:
    status = client.translated_tts.get_translated_tts_task_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        print(status)
        break
    time.sleep(3)
```

***

## Dictionaries

Dictionaries contain custom term mappings that the API applies automatically when running dubbing or translation jobs. They are particularly useful for brand names, product terminology, and proper nouns that need consistent handling across languages.

### List Dictionaries

Call `get_dictionaries()` to retrieve all dictionaries on your account along with their metadata:

```python theme={null}
import os
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

dictionaries = client.dictionaries.get_dictionaries()
for d in dictionaries:
    print(f"{d.id}: {d.name}")
```

### Create from File

Upload a CSV file to create a new dictionary. The file should contain source and target term pairs in a format the API expects:

```python theme={null}
with open("terms.csv", "rb") as f:
    client.dictionaries.create_dictionary_from_file(
        dictionary_file=f,
        dictionary_name="Product Terms",
        dictionary_description="Brand-specific terminology for our product line.",
    )
```

### Manage Terms

Use `add_term_to_dictionary` to insert individual term translations and `delete_dictionary_term` to remove them by ID. Each term takes a `source`, a `target`, and the language the target is in:

```python theme={null}
from camb.types import TermTranslationInput

# Add a term
client.dictionaries.add_term_to_dictionary(
    dictionary_id="dict_123",
    translations=[
        TermTranslationInput(source="Camb.ai", target="कैम्ब.एआई", language="hi-in")
    ],
)

# Delete a term
client.dictionaries.delete_dictionary_term(
    dictionary_id="dict_123",
    term_id="term_456",
)

# Delete the dictionary
client.dictionaries.delete_dictionary(dictionary_id="dict_123")
```

***

## Custom Provider

If you are running MARS on your own infrastructure through Baseten, you can initialize the client with a provider configuration instead of a Camb.ai API key. See [Custom Cloud Providers](/custom-cloud-providers) for deployment instructions.

### Baseten

Deploy the MARS model to your Baseten account, then point the client at your deployment URL. Baseten calls require a base64-encoded reference audio sample to be passed with every request:

```python theme={null}
import base64
import os
from camb.client import CambAI, save_stream_to_file

client = CambAI(
    tts_provider="baseten",
    provider_params={
        "api_key": os.getenv("BASETEN_API_KEY"),
        "mars_pro_url": "https://model-xxxxxx.api.baseten.co/environments/production/predict",
    },
)

with open("reference.wav", "rb") as f:
    reference_audio = base64.b64encode(f.read()).decode("utf-8")

stream = client.text_to_speech.tts(
    text="Hello from a self-hosted MARS deployment.",
    language="en-us",
    speech_model="mars-pro",
    request_options={
        "additional_body_parameters": {
            "reference_audio": reference_audio,
            "reference_language": "en-us",
        },
        "timeout_in_seconds": 300,
    },
)
save_stream_to_file(stream, "output.mp3")
```

<Note>
  Baseten deployments require `reference_audio` (base64-encoded WAV) and `reference_language` in `additional_body_parameters`.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice agents with Pipecat
  </Card>

  <Card title="LiveKit Integration" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit">
    Create voice agents with LiveKit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Explore the full TTS API
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>

***

## Resources

* [GitHub: camb-ai/cambai-python-sdk](https://github.com/camb-ai/cambai-python-sdk)
* [SDK Examples](https://github.com/camb-ai/cambai-python-sdk/tree/main/examples)
* [API Reference](/api-reference/endpoint/create-tts-stream)


# Rust SDK
Source: https://docs.camb.ai/sdk-guides/rust-sdk

Install and use the Camb.ai Rust SDK with async Tokio and typed request payloads

The official Rust SDK for Camb.ai provides access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, audio generation, stories, translated TTS, translated stories, dictionaries, folders, project setup, and streaming pipelines. The client is async-only and built on Tokio.

## Installation

Add the crate and Tokio to your `Cargo.toml`:

```toml theme={null}
[dependencies]
camb_api = { git = "https://github.com/Camb-ai/cambai-rust-sdk" }
tokio = { version = "1.0", features = ["full"] }
futures = "0.3"
```

The `camb_api` package name matches the crate defined in the SDK repository.

***

## Authentication

Get your API key from [Camb.ai Studio](https://studio.camb.ai) and read it from the environment so it never appears in source control. Build the client with `APIClient::new` and `ClientConfig`.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;

    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    Ok(())
}
```

<Tip>
  For local development, load `CAMB_API_KEY` from a `.env` file with a crate such as [dotenvy](https://crates.io/crates/dotenvy) at process startup.
</Tip>

***

## Quick Start

Streaming TTS returns a `ByteStream`. The SDK does not include a file helper, so write chunks with `std::io::Write` after each `try_next` call on the stream.

```rust theme={null}
use camb_api::prelude::*;
use std::io::Write;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let mut stream = client
        .text_to_speech
        .tts(
            &CreateStreamTtsRequestPayload {
                text: "Hello from Camb.ai.".to_string(),
                voice_id: 147320,
                language: CreateStreamTtsRequestPayloadLanguage::EnUs,
                speech_model: Some(CreateStreamTtsRequestPayloadSpeechModel::Mars8Flash),
                user_instructions: None,
                enhance_named_entities_pronunciation: None,
                output_configuration: Some(StreamTtsOutputConfiguration {
                    format: Some(OutputFormat::Wav),
                    duration: None,
                    apply_enhancement: None,
                }),
                voice_settings: None,
                inference_options: None,
            },
            None,
        )
        .await?;

    let mut file = std::fs::File::create("output.wav")?;
    while let Some(chunk) = stream.try_next().await? {
        file.write_all(&chunk)?;
    }

    Ok(())
}
```

***

## Models

Streaming TTS accepts `speech_model` as `CreateStreamTtsRequestPayloadSpeechModel`. The Rust enum serializes to the wire values in the table. If you omit `speech_model`, the API applies its default.

| Variant         | Wire value        | Notes                                                                |
| --------------- | ----------------- | -------------------------------------------------------------------- |
| `Auto`          | `auto`            | Server-selected model                                                |
| `Mars6`         | `mars-6`          | Earlier MARS generation                                              |
| `Mars7`         | `mars-7`          | MARS 7 generation                                                    |
| `Mars8`         | `mars-8`          | MARS 8 generation                                                    |
| `Mars8Flash`    | `mars-8-flash`    | Lower-latency MARS 8                                                 |
| `Mars8Instruct` | `mars-8-instruct` | Instruction-style control via `user_instructions` and bracketed text |

Per-model language coverage is listed at [Language Support](/language-support).

<Tabs>
  <Tab title="Mars8Flash">
    ```rust theme={null}
    speech_model: Some(CreateStreamTtsRequestPayloadSpeechModel::Mars8Flash)
    ```
  </Tab>

  <Tab title="Mars8">
    ```rust theme={null}
    speech_model: Some(CreateStreamTtsRequestPayloadSpeechModel::Mars8)
    ```
  </Tab>

  <Tab title="Mars8Instruct">
    ```rust theme={null}
    let payload = CreateStreamTtsRequestPayload {
        text: "[warm, friendly] Great to meet you!".to_string(),
        voice_id: 147320,
        language: CreateStreamTtsRequestPayloadLanguage::EnUs,
        speech_model: Some(CreateStreamTtsRequestPayloadSpeechModel::Mars8Instruct),
        user_instructions: Some(Some("Speak warmly and clearly.".to_string())),
        enhance_named_entities_pronunciation: None,
        output_configuration: Some(StreamTtsOutputConfiguration {
            format: Some(OutputFormat::Wav),
            duration: None,
            apply_enhancement: None,
        }),
        voice_settings: None,
        inference_options: None,
    };
    ```
  </Tab>
</Tabs>

***

## TTS Options

`text_to_speech.tts(...)` accepts `CreateStreamTtsRequestPayload` with the core request fields plus optional controls for model behavior and output format.

| Field                                  | Type                                               | Description                                                                                                 |
| -------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `text`                                 | `String`                                           | Text to synthesize. For MARS Instruct, you can include inline emotion or pacing tags in the text.           |
| `language`                             | enum                                               | Locale such as `CreateStreamTtsRequestPayloadLanguage::EnUs`.                                               |
| `voice_id`                             | integer                                            | Voice profile ID from the voice list APIs.                                                                  |
| `speech_model`                         | `Option<CreateStreamTtsRequestPayloadSpeechModel>` | Model to use, such as `Mars8Flash`, `Mars8`, or `Mars8Instruct`.                                            |
| `user_instructions`                    | `Option<Option<String>>`                           | Adds style, tone, pronunciation, or delivery guidance for the request. Available only with `Mars8Instruct`. |
| `output_configuration`                 | `Option<StreamTtsOutputConfiguration>`             | Output settings such as audio format.                                                                       |
| `voice_settings`                       | object                                             | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.               |
| `inference_options`                    | object                                             | Advanced generation controls for supported models.                                                          |
| `enhance_named_entities_pronunciation` | boolean option                                     | Improves pronunciation for names and other named entities when supported.                                   |

***

## Text-to-Speech

### Streaming

`text_to_speech.tts` posts to `tts-stream` and returns audio chunks as `ByteStream`, as shown in [Quick Start](#quick-start).

### Submit, poll, and fetch

Non-streaming TTS uses `create_tts` to obtain a `task_id`, polls `get_tts_result` until `TaskStatus::Success`, then reads the run with `get_tts_run_info`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .text_to_speech
        .create_tts(
            &CreateTtsRequestPayload {
                project_name: None,
                project_description: None,
                folder_id: None,
                text: "Hello from batch TTS.".to_string(),
                voice_id: 147320,
                language: Languages::EN_US,
                gender: None,
                age: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .text_to_speech
            .get_tts_result(
                &task_id,
                &GetTtsResultQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(2)).await;
    }

    if let Some(rid) = run_id {
        let info = client
            .text_to_speech
            .get_tts_run_info(
                &Some(rid),
                &GetTtsRunInfoQueryRequest::default(),
                None,
            )
            .await?;
        println!("{:?}", info);
    }

    Ok(())
}
```

***

## Voices

### List voices

`voice_cloning.list_voices` returns a vector of `ListVoicesListVoicesGetResponseItem` values. Print or deserialize each entry to read fields such as identifiers for use in TTS.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let voices = client
        .voice_cloning
        .list_voices(&ListVoicesQueryRequest::default(), None)
        .await?;

    for voice in voices {
        println!("{:?}", voice);
    }

    Ok(())
}
```

### Create a custom voice

`create_custom_voice` sends multipart form data. Load reference audio into a `Vec<u8>`. `Gender` is a numeric newtype: use the value expected by your account and endpoint documentation (for example `Gender(1)`).

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let file_bytes = std::fs::read("reference.wav")?;

    let result = client
        .voice_cloning
        .create_custom_voice(
            &CreateCustomVoiceRequest {
                voice_name: "My Custom Voice".to_string(),
                gender: Gender(1),
                description: Some(Some("Warm and conversational.".to_string())),
                publish_voice_to_market_place: None,
                age: None,
                language: None,
                enhance_audio: Some(Some(true)),
                file: file_bytes,
                run_id: None,
            },
            None,
        )
        .await?;

    println!("{:?}", result);

    Ok(())
}
```

***

## Language support

Dubbing, translation, transcription, and related jobs use `Languages`, a newtype around `i64` with constants such as `Languages::EN_US` and `Languages::HI_IN`.

Streaming TTS uses the separate enum `CreateStreamTtsRequestPayloadLanguage` (for example `CreateStreamTtsRequestPayloadLanguage::EnUs`), which serializes to locale strings.

```rust theme={null}
use camb_api::prelude::*;

fn main() {
    println!("{:?}", Languages::EN_US);
    println!("{:?}", Languages::HI_IN);
}
```

To fetch supported languages at runtime, call `languages.get_source_languages` and `languages.get_target_languages`.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let source = client
        .languages
        .get_source_languages(&GetSourceLanguagesQueryRequest::default(), None)
        .await?;
    let target = client
        .languages
        .get_target_languages(&GetTargetLanguagesQueryRequest::default(), None)
        .await?;

    println!("{:?}", source);
    println!("{:?}", target);

    Ok(())
}
```

***

## Dubbing

`dub.end_to_end_dubbing` starts a job. Poll `dub.get_end_to_end_dubbing_status` until `status` is `TaskStatus::Success`, then call `get_dubbed_run_info` with the `run_id` from the status payload. Optional `get_dubbed_run_transcript` returns transcript data for a target language.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .dub
        .end_to_end_dubbing(
            &EndToEndDubbingRequestPayload {
                video_url: "https://example.com/video.mp4".to_string(),
                source_language: Languages::EN_US,
                target_languages: Some(vec![Languages::HI_IN]),
                target_language: None,
                project_name: None,
                project_description: None,
                folder_id: None,
                selected_audio_tracks: None,
                add_output_as_an_audio_track: None,
                chosen_dictionaries: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.ok_or("missing task_id")?;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .dub
            .get_end_to_end_dubbing_status(
                &task_id,
                &GetEndToEndDubbingStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }

    if let Some(rid) = run_id {
        let info = client.dub.get_dubbed_run_info(&Some(rid), None).await?;
        println!("{:?}", info);

        let transcript = client
            .dub
            .get_dubbed_run_transcript(
                &Some(rid),
                &Languages::HI_IN,
                &GetDubbedRunTranscriptQueryRequest::default(),
                None,
            )
            .await?;
        println!("{:?}", transcript);
    }

    Ok(())
}
```

For multiple targets in one job, set `target_languages` to `Some(Some(vec![Languages::FR_FR, Languages::ES_ES]))` and set `target_language` to `None`.

***

## Translation

`translation.create_translation` returns `serde_json::Value`. Read `task_id` from the JSON, poll `get_translation_task_status`, then call `get_translation_result` with the resolved `run_id`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .translation
        .create_translation(
            &CreateTranslationRequestPayload {
                project_name: None,
                project_description: None,
                folder_id: None,
                texts: vec![
                    "Hello, how are you?".to_string(),
                    "Welcome to Camb.ai.".to_string(),
                ],
                age: None,
                formality: None,
                gender: None,
                source_language: Languages::EN_US,
                target_language: Languages::FR_FR,
                chosen_dictionaries: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted
        .get("task_id")
        .and_then(|v| v.as_str())
        .ok_or("missing task_id")?
        .to_string();

    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .translation
            .get_translation_task_status(
                &task_id,
                &GetTranslationTaskStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(2)).await;
    }

    if let Some(rid) = run_id {
        let result = client
            .translation
            .get_translation_result(&Some(rid), None)
            .await?;
        for text in result.texts {
            println!("{}", text);
        }
    }

    Ok(())
}
```

<Note>
  For streaming translation over a single string, use `translation.translation_stream` with `CreateTranslationStreamRequestPayload` and inspect the returned `serde_json::Value` shape for your integration.
</Note>

***

## Transcription

`transcription.create_transcription` accepts multipart fields including `media_url` or `media_file`. Poll `get_transcription_task_status`, then `get_transcription_result`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .transcription
        .create_transcription(
            &CreateTranscriptionRequest {
                language: Languages::EN_US,
                media_file: None,
                media_url: Some(Some("https://example.com/audio.mp3".to_string())),
                file: None,
                audio_url: None,
                project_name: None,
                project_description: None,
                folder_id: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.ok_or("missing task_id")?;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .transcription
            .get_transcription_task_status(
                &task_id,
                &GetTranscriptionTaskStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(3)).await;
    }

    if let Some(rid) = run_id {
        let result = client
            .transcription
            .get_transcription_result(
                &Some(rid),
                &GetTranscriptionResultQueryRequest::default(),
                None,
            )
            .await?;
        println!("{:?}", result);
    }

    Ok(())
}
```

To transcribe a local file, set `media_file` to `Some(bytes)` and clear `media_url`.

***

## Audio separation

Upload `media_file` via multipart, poll `get_audio_separation_status`, then read `get_audio_separation_run_info`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let bytes = std::fs::read("track.mp3")?;

    let submitted = client
        .audio_separation
        .create_audio_separation(
            &CreateAudioSeparationRequest {
                media_file: Some(bytes),
                project_name: None,
                project_description: None,
                folder_id: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.ok_or("missing task_id")?;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .audio_separation
            .get_audio_separation_status(
                &task_id,
                &GetAudioSeparationStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(3)).await;
    }

    if let Some(rid) = run_id {
        let info = client
            .audio_separation
            .get_audio_separation_run_info(&Some(rid), None)
            .await?;
        println!("{:?}", info);
    }

    Ok(())
}
```

***

## Text-to-voice

Create a job with `create_text_to_voice`, poll `get_text_to_voice_status`, then load previews and identifiers from `get_text_to_voice_result`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .text_to_voice
        .create_text_to_voice(
            &CreateTextToVoiceRequestPayload {
                text: "A confident narrator introducing a documentary.".to_string(),
                voice_description: "Deep, measured baritone. Calm and authoritative.".to_string(),
                project_name: None,
                project_description: None,
                folder_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.ok_or("missing task_id")?;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .text_to_voice
            .get_text_to_voice_status(
                &task_id,
                &GetTextToVoiceStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(3)).await;
    }

    if let Some(rid) = run_id {
        let result = client
            .text_to_voice
            .get_text_to_voice_result(&Some(rid), None)
            .await?;
        println!("{:?}", result);
    }

    Ok(())
}
```

<Note>
  Inspect `get_text_to_voice_result` for preview URLs and the `voice_id` to pass into `text_to_speech.tts` for production speech.
</Note>

***

## Text-to-audio

`create_text_to_audio` starts an asynchronous sound or music generation job. After success, `get_text_to_audio_result` returns a `ByteStream` for the audio bytes.

```rust theme={null}
use camb_api::prelude::*;
use std::io::Write;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .text_to_audio
        .create_text_to_audio(
            &CreateTextToAudioRequestPayload {
                project_name: None,
                project_description: None,
                folder_id: None,
                prompt: "Heavy rain on a tin roof at night with distant thunder.".to_string(),
                duration: Some(15.0),
                audio_type: Some(TextToAudioType::Sound),
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.ok_or("missing task_id")?;
    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .text_to_audio
            .get_text_to_audio_status(
                &task_id,
                &GetTextToAudioStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(3)).await;
    }

    if let Some(rid) = run_id {
        let mut stream = client
            .text_to_audio
            .get_text_to_audio_result(
                &Some(rid),
                &GetTextToAudioResultQueryRequest::default(),
                None,
            )
            .await?;

        let mut file = std::fs::File::create("soundscape.wav")?;
        while let Some(chunk) = stream.try_next().await? {
            file.write_all(&chunk)?;
        }
    }

    Ok(())
}
```

***

## Stories

`story.create_story` uploads a document as multipart data. The response is `CreateStoryStoryPostResponse`; the common async path exposes `OrchestratorPipelineCallResult` with a `task_id`. Poll `get_story_status`, then call `get_story_run_info`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let file_bytes = std::fs::read("story.pdf")?;

    let submitted = client
        .story
        .create_story(
            &CreateStoryRequest {
                file: file_bytes,
                source_language: Languages::EN_US,
                title: Some(Some("My Story".to_string())),
                description: None,
                narrator_voice_id: None,
                folder_id: None,
                chosen_dictionaries: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted
        .into_orchestratorpipelinecallresult()
        .and_then(|r| r.task_id)
        .ok_or("missing task_id")?;

    let mut run_id: Option<i64> = None;
    loop {
        let status = client
            .story
            .get_story_status(&task_id, &GetStoryStatusQueryRequest::default(), None)
            .await?;
        if status.status == TaskStatus::Success {
            run_id = status.run_id.flatten();
            break;
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }

    if let Some(rid) = run_id {
        let info = client
            .story
            .get_story_run_info(
                &Some(rid),
                &GetStoryRunInfoQueryRequest::default(),
                None,
            )
            .await?;
        println!("{:?}", info);
    }

    Ok(())
}
```

***

## Translated TTS

`translated_tts.create_translated_tts` returns `CreateTranslatedTtsOut` with a `task_id`. Poll `get_translated_tts_task_status` until the status is success.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .translated_tts
        .create_translated_tts(
            &CreateTranslatedTtsRequestPayload {
                project_name: None,
                project_description: None,
                folder_id: None,
                text: "Good morning, welcome to our service.".to_string(),
                voice_id: 147320,
                age: None,
                formality: None,
                gender: None,
                source_language: Languages::EN_US,
                target_language: Languages::HI_IN,
                chosen_dictionaries: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id;
    loop {
        let status = client
            .translated_tts
            .get_translated_tts_task_status(
                &task_id,
                &GetTranslatedTtsTaskStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            println!("{:?}", status);
            break;
        }
        tokio::time::sleep(Duration::from_secs(3)).await;
    }

    Ok(())
}
```

***

## Translated story

Add a target language to an existing story run with `create_translation_for_existing_story`. Poll `get_translated_story_status`, then read `get_translated_story_run_info` using the original story `run_id` and the target `Languages` value.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let story_run_id: i64 = 12345;

    let submitted = client
        .translated_story
        .create_translation_for_existing_story(
            &Some(story_run_id),
            &CreateTranslationForExistingStoryRequestPayload {
                target_language: Languages::FR_FR,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id.flatten().ok_or("missing task_id")?;

    loop {
        let status = client
            .translated_story
            .get_translated_story_status(
                &task_id,
                &GetTranslatedStoryStatusQueryRequest::default(),
                None,
            )
            .await?;
        if status.status == TaskStatus::Success {
            break;
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }

    let info = client
        .translated_story
        .get_translated_story_run_info(
            &Some(story_run_id),
            &Languages::FR_FR,
            &GetTranslatedStoryRunInfoQueryRequest::default(),
            None,
        )
        .await?;

    println!("{:?}", info);

    Ok(())
}
```

***

## Dictionaries

### List dictionaries

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let dictionaries = client
        .dictionaries
        .get_dictionaries(&GetDictionariesQueryRequest::default(), None)
        .await?;

    for d in dictionaries {
        println!("{:?}", d);
    }

    Ok(())
}
```

### Create from file

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let csv = std::fs::read("terms.csv")?;

    client
        .dictionaries
        .create_dictionary_from_file(
            &CreateDictionaryFromFileRequest {
                dictionary_file: csv,
                dictionary_name: "Product Terms".to_string(),
                dictionary_description: Some(Some(
                    "Brand-specific terminology for our product line.".to_string(),
                )),
                run_id: None,
            },
            None,
        )
        .await?;

    Ok(())
}
```

### Manage terms

`TermTranslationInput` pairs a `translation` string with a `Languages` value. Dictionary and term identifiers are numeric.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let dictionary_id: i64 = 123;
    let term_id: i64 = 456;

    client
        .dictionaries
        .add_term_to_dictionary(
            dictionary_id,
            &AddDictionaryTermPayload {
                translations: vec![TermTranslationInput {
                    translation: "कैम्ब.एआई".to_string(),
                    language: Languages::HI_IN,
                }],
                run_id: None,
            },
            None,
        )
        .await?;

    client
        .dictionaries
        .update_term_translation_in_dictionary_using_term_id(
            dictionary_id,
            term_id,
            &UpdateTermTranslationsPayload {
                translations: vec![TermTranslationInput {
                    translation: "कैम्ब.एआई".to_string(),
                    language: Languages::HI_IN,
                }],
                run_id: None,
            },
            None,
        )
        .await?;

    client
        .dictionaries
        .delete_dictionary_term(
            dictionary_id,
            term_id,
            &DeleteDictionaryTermQueryRequest::default(),
            None,
        )
        .await?;

    client
        .dictionaries
        .delete_dictionary(
            dictionary_id,
            &DeleteDictionaryQueryRequest::default(),
            None,
        )
        .await?;

    Ok(())
}
```

***

## Folders

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let folders = client
        .folders
        .list_folders(&ListFoldersQueryRequest::default(), None)
        .await?;
    println!("{:?}", folders);

    client
        .folders
        .create_folder(
            &CreateFolderPayload {
                folder_name: "My runs".to_string(),
                run_id: None,
            },
            None,
        )
        .await?;

    Ok(())
}
```

***

## Project setup

`project_setup.create_project` accepts a public `media_url`, a `source_language`, and a `target_languages` list. The call returns `CreateProjectSetupOut` with a `task_id`. Poll `create_project_setup_task_status` until the returned vector includes a row, read `run_id` from that row, then call `get_project_setup_result`.

```rust theme={null}
use camb_api::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let submitted = client
        .project_setup
        .create_project(
            &CreateProjectSetupRequestPayload {
                project_name: None,
                project_description: None,
                folder_id: None,
                media_url: "https://example.com/video.mp4".to_string(),
                source_language: Languages::EN_US,
                target_languages: vec![Languages::HI_IN],
                selected_audio_tracks: None,
                add_output_as_an_audio_track: None,
                chosen_dictionaries: None,
                run_id: None,
            },
            None,
        )
        .await?;

    let task_id = submitted.task_id;
    let mut run_id: Option<i64> = None;
    loop {
        let rows = client
            .project_setup
            .create_project_setup_task_status(
                &task_id,
                &CreateProjectSetupTaskStatusQueryRequest::default(),
                None,
            )
            .await?;
        if let Some(first) = rows.first() {
            run_id = Some(first.run_id);
            break;
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }

    if let Some(rid) = run_id {
        if let Some(result) = client
            .project_setup
            .get_project_setup_result(&Some(rid), None)
            .await?
        {
            println!("{:?}", result);
        }
    }

    Ok(())
}
```

***

## Streaming pipelines

The `streaming` client manages long-running stream resources: `create_stream`, `get_stream_result`, `patch_stream_data`, `destroy_stream`, and `get_probe_stream`. `CreateStreamRequestPayload` ties together `ConfigStream`, `SourceStream`, and one or more `TargetStream` values. `StreamType` is a numeric newtype (`StreamType(i64)`); use the stream type codes from your deployment or API reference.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let created = client
        .streaming
        .create_stream(
            &CreateStreamRequestPayload {
                name: None,
                description: None,
                initial_delay: None,
                timeout_in_mins: None,
                voices: vec![147320],
                dictionaries: vec![],
                config: ConfigStream {
                    pipeline: None,
                    mixing: None,
                },
                source_stream: SourceStream {
                    language: Languages::EN_US,
                    url: "rtmp://example.com/in".to_string(),
                    category: None,
                    passphrase: None,
                    streamid: None,
                    number_of_streams: None,
                    audio_stream: None,
                    background_audio_stream: None,
                    latency: None,
                    relay_input: None,
                },
                target_streams: vec![TargetStream {
                    languages: vec![Languages::HI_IN],
                    url: "rtmp://example.com/out".to_string(),
                    r#type: StreamType(1),
                    passphrase: None,
                    streamid: None,
                    pids: None,
                    transcode_video: None,
                    embed_subtitles: None,
                    audio_codec: None,
                    audio_bitrate: None,
                    audio_channel_layout: None,
                    latency: None,
                    constant_bitrate: None,
                    relay_output: None,
                }],
                start_time: None,
                end_time: None,
                timezone: None,
            },
            None,
        )
        .await?;

    let stream_id = created.stream_id;

    let snapshot = client
        .streaming
        .get_stream_result(
            stream_id,
            &StreamingGetStreamResultQueryRequest::default(),
            None,
        )
        .await?;
    println!("{:?}", snapshot);

    client
        .streaming
        .patch_stream_data(
            stream_id,
            &UpdateStreamDataRequestPayload::default(),
            None,
        )
        .await?;

    client
        .streaming
        .destroy_stream(stream_id, &DestroyStreamQueryRequest::default(), None)
        .await?;

    let probe = client
        .streaming
        .get_probe_stream(
            &GetProbeStreamRequest {
                run_id: None,
                body: GetProbeStreamIn {
                    url: "rtmp://example.com/in".to_string(),
                    passphrase: None,
                    stream_id: None,
                },
            },
            None,
        )
        .await?;
    println!("{:?}", probe);

    Ok(())
}
```

***

## Error handling

Failures surface as `ApiError`. Match on `ApiError::UnprocessableEntityError` for validation-style `422` responses, `ApiError::Http` for other status codes, and `ApiError::Network` for transport errors.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let payload = CreateStreamTtsRequestPayload {
        text: "Hello world.".to_string(),
        voice_id: 147320,
        language: CreateStreamTtsRequestPayloadLanguage::EnUs,
        speech_model: None,
        user_instructions: None,
        enhance_named_entities_pronunciation: None,
        output_configuration: Some(StreamTtsOutputConfiguration {
            format: Some(OutputFormat::Wav),
            duration: None,
            apply_enhancement: None,
        }),
        voice_settings: None,
        inference_options: None,
    };

    match client.text_to_speech.tts(&payload, None).await {
        Ok(mut stream) => {
            while let Some(chunk) = stream.try_next().await? {
                let _ = chunk;
            }
        }
        Err(ApiError::UnprocessableEntityError { message, .. }) => {
            eprintln!("validation error: {}", message);
        }
        Err(e) => eprintln!("error: {}", e),
    }

    Ok(())
}
```

Pass `RequestOptions` as the last argument to tune timeouts and retries for a single call.

```rust theme={null}
use camb_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("CAMB_API_KEY")?;
    let client = APIClient::new(ClientConfig {
        api_key: Some(api_key),
        ..ClientConfig::default()
    })?;

    let opts = RequestOptions::new()
        .timeout_seconds(300)
        .max_retries(3);

    let _stream = client
        .text_to_speech
        .tts(
            &CreateStreamTtsRequestPayload {
                text: "Hello world.".to_string(),
                voice_id: 147320,
                language: CreateStreamTtsRequestPayloadLanguage::EnUs,
                speech_model: None,
                user_instructions: None,
                enhance_named_entities_pronunciation: None,
                output_configuration: Some(StreamTtsOutputConfiguration {
                    format: Some(OutputFormat::Wav),
                    duration: None,
                    apply_enhancement: None,
                }),
                voice_settings: None,
                inference_options: None,
            },
            Some(opts),
        )
        .await?;

    Ok(())
}
```

***

## Custom provider

Self-hosted MARS on Baseten can call the `TtsProvider` trait. `BasetenProvider::new` takes the Baseten API key and an optional deployment URL. See [Custom Cloud Providers](/custom-cloud-providers) for deployment details.

```rust theme={null}
use camb_api::prelude::*;
use camb_api::provider::{BasetenProvider, TtsProvider};
use std::io::Write;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("BASETEN_API_KEY")?;
    let url = std::env::var("BASETEN_URL").ok();

    let provider = BasetenProvider::new(api_key, url);

    let mut stream = provider
        .tts(
            &CreateStreamTtsRequestPayload {
                text: "Hello from a custom provider.".to_string(),
                voice_id: 0,
                language: CreateStreamTtsRequestPayloadLanguage::EnUs,
                speech_model: None,
                user_instructions: None,
                enhance_named_entities_pronunciation: None,
                output_configuration: None,
                voice_settings: None,
                inference_options: None,
            },
            None,
        )
        .await?;

    let mut file = std::fs::File::create("baseten_output.mp3")?;
    while let Some(chunk) = stream.try_next().await? {
        file.write_all(&chunk)?;
    }

    Ok(())
}
```

<Warning>
  The bundled `BasetenProvider` builds a minimal JSON body for Baseten. Production deployments require valid reference audio, correct language fields, and URLs that match your Baseten model card. Treat the provider as a pattern you extend rather than a drop-in for every deployment.
</Warning>

***

## Next steps

<CardGroup>
  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice agents with Pipecat
  </Card>

  <Card title="LiveKit Integration" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit">
    Create voice agents with LiveKit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Explore the full TTS API
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>

***

## Resources

* [GitHub: camb-ai/cambai-rust-sdk](https://github.com/Camb-ai/cambai-rust-sdk)
* [SDK examples](https://github.com/Camb-ai/cambai-rust-sdk/tree/master/examples)
* [API Reference](/api-reference/endpoint/create-tts-stream)


# TypeScript SDK
Source: https://docs.camb.ai/sdk-guides/typescript-sdk

Install and use the TypeScript SDK for Node.js 18+ with a promise-based API

The official TypeScript SDK for Camb.ai provides convenient access to text-to-speech, dubbing, translation, transcription, audio separation, voice cloning, and audio generation. Every method returns a promise, the package ships as ES modules, and `saveStreamToFile` handles audio output in one call.

## Installation

```bash theme={null}
npm install @camb-ai/sdk
```

```bash theme={null}
yarn add @camb-ai/sdk
```

```bash theme={null}
pnpm add @camb-ai/sdk
```

Requires Node.js 18 or higher. The package is published as `@camb-ai/sdk` and ships as ES modules.

***

## Authentication

Get your API key from [Camb.ai Studio](https://studio.camb.ai) and read it from `process.env.CAMB_API_KEY` so it never appears in source control.

Every API call on `CambClient` returns a promise. There is no synchronous client: wrap usage in `async` functions and use `await` throughout.

```typescript theme={null}
import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});
```

<Tip>
  Use [dotenv](https://www.npmjs.com/package/dotenv) to load `CAMB_API_KEY` from a `.env` file during local development.
</Tip>

***

## Quick Start

Streaming TTS returns binary data that `saveStreamToFile` writes to disk. `await client.textToSpeech.tts(...)` resolves to a stream object the helper understands.

```typescript theme={null}
import { CambClient, CambApi, saveStreamToFile } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  const stream = await client.textToSpeech.tts({
    text: "Hello from Camb.ai.",
    language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
    voice_id: 147320,
    speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsFlash,
    output_configuration: { format: "wav" },
  });

  await saveStreamToFile(stream, "output.wav");
  console.log("Audio saved to output.wav");
}

void main();
```

***

## Models

Camb.ai offers MARS models tuned for different quality and latency requirements. Pass `speech_model` using `CambApi.CreateStreamTtsRequestPayload.SpeechModel`. If you omit it, the API applies its default model.

| Model                 | Sample Rate | Best For                                                                     |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `mars-8.1-flash-beta` | 48 kHz      | Faster MARS 8.1 generation; same quality improvements as `mars-8.1-pro-beta` |
| `mars-8.1-pro-beta`   | 48 kHz      | Improved pronunciation, expressiveness, and prosody over `mars-pro`          |
| `mars-flash`          | 22.05 kHz   | Low-latency real-time applications and conversational AI                     |
| `mars-pro`            | 48 kHz      | High-fidelity audio production and long-form content                         |
| `mars-instruct`       | 22.05 kHz   | Fine-grained tone and style control via text instructions                    |

The tab snippets below assume the same `client` and `CambApi` imports as in [Quick Start](#quick-start).

<Tabs>
  <Tab title="MARS Flash">
    ```typescript theme={null}
    const stream = await client.textToSpeech.tts({
      text: "Hey, I can respond much faster.",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      voice_id: 147320,
      speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsFlash,
      output_configuration: { format: "wav" },
    });
    ```

    **Best for:** Voice agents, real-time applications

    **Sample rate:** 22.05 kHz
  </Tab>

  <Tab title="MARS Pro">
    ```typescript theme={null}
    const stream = await client.textToSpeech.tts({
      text: "High-fidelity audio for production use.",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      voice_id: 147320,
      speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsPro,
      output_configuration: { format: "wav" },
    });
    ```

    **Best for:** Audio production, dubbing, long-form content

    **Sample rate:** 48 kHz
  </Tab>

  <Tab title="MARS Instruct">
    ```typescript theme={null}
    const stream = await client.textToSpeech.tts({
      text: "[warm, friendly] Great to meet you!",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      voice_id: 147320,
      speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsInstruct,
      user_instructions: "Speak warmly and with enthusiasm.",
      output_configuration: { format: "wav" },
    });
    ```

    **Best for:** Fine-grained control over tone and delivery

    **Sample rate:** 22.05 kHz
  </Tab>
</Tabs>

***

## TTS Options

The `client.textToSpeech.tts(...)` method accepts the core request fields plus optional controls for model behavior and output format.

| Option                                 | Type        | Description                                                                                                              |
| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `text`                                 | string      | Text to synthesize. For `mars-instruct`, you can include inline emotion or pacing tags in the text.                      |
| `language`                             | enum        | Locale such as `CambApi.CreateStreamTtsRequestPayload.Language.EnUs`.                                                    |
| `voice_id`                             | number      | Voice profile ID from `listVoices()`.                                                                                    |
| `speech_model`                         | enum/string | Model to use, such as `Mars81FlashBeta`, `MarsPro`, or `MarsInstruct`.                                                   |
| `user_instructions`                    | string      | Adds style, tone, pronunciation, or delivery guidance for the request. Available only with `speech_model: MarsInstruct`. |
| `output_configuration`                 | object      | Output settings such as `{ format: "wav" }`.                                                                             |
| `voice_settings`                       | object      | Voice behavior controls such as speaking rate, reference enhancement, or accent preservation.                            |
| `inference_options`                    | object      | Advanced generation controls for supported models.                                                                       |
| `enhance_named_entities_pronunciation` | boolean     | Improves pronunciation for names and other named entities when supported.                                                |

***

## Voices

### List voices

`listVoices()` returns every voice available to your account, including library voices and custom clones. Use the returned `id` (or equivalent field from the typed response) as `voice_id` in TTS calls.

```typescript theme={null}
import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  const voices = await client.voiceCloning.listVoices();
  for (const voice of voices) {
    console.log(voice);
  }
}

void main();
```

### Create a custom voice

Upload a short reference clip with a display name and gender. Set `enhance_audio` when the recording may contain noise so the API can preprocess the clip before cloning.

```typescript theme={null}
import { createReadStream } from "node:fs";
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  const result = await client.voiceCloning.createCustomVoice({
    voice_name: "My Custom Voice",
    gender: 1 as CambApi.Gender,
    file: createReadStream("reference.wav"),
    description: "Warm and conversational.",
    enhance_audio: true,
  });

  console.log(result);
}

void main();
```

***

## Language support

TTS requests use string locale values through `CambApi.CreateStreamTtsRequestPayload.Language` (for example `Language.EnUs` maps to `"en-us"`). See [Language Support](/language-support) for the full per-model locale list. Dubbing, translation, transcription, and several other endpoints use the numeric `CambApi.Languages` enum so the wire format matches the REST API exactly.

```typescript theme={null}
import { CambApi } from "@camb-ai/sdk";

console.log(CambApi.CreateStreamTtsRequestPayload.Language.EnUs);
console.log(CambApi.Languages.EN_US, CambApi.Languages.HI_IN, CambApi.Languages.FR_FR);
```

Fetch the canonical list of supported languages from the API when you need to populate UI or validate user input.

```typescript theme={null}
import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  const source = await client.languages.getSourceLanguages();
  const target = await client.languages.getTargetLanguages();
  console.log(source, target);
}

void main();
```

Languages supported per model are listed at [MARS Models](/models).

***

## Dubbing

The dubbing client translates the audio track of a remote video and resynthesizes speech with cloned voices. In TypeScript the entry point is `endToEndDubbing`, not the Python name `create_dub`. You submit a job, poll `getEndToEndDubbingStatus` until `status` is success, then read URLs from `getDubbedRunInfo`.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.dub.endToEndDubbing({
    video_url: "https://example.com/video.mp4",
    source_language: CambApi.Languages.EN_US,
    target_language: CambApi.Languages.HI_IN,
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from endToEndDubbing");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.dub.getEndToEndDubbingStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(5000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const info = await client.dub.getDubbedRunInfo({ run_id: runId });
  console.log(info);
}

void main();
```

To dub into several targets in one job, pass `target_languages` instead of `target_language`.

### Get transcript

After a successful run, `getDubbedRunTranscript` returns transcript text keyed by field name for the requested target language.

```typescript theme={null}
const transcript = await client.dub.getDubbedRunTranscript({
  run_id: runId,
  language: CambApi.Languages.HI_IN,
});
console.log(transcript);
```

***

## Translation

`createTranslation` accepts an array of strings and returns translations in the same order. The workflow matches dubbing: create a task, poll `getTranslationTaskStatus`, then call `getTranslationResult` with the `run_id` from the status payload.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.translation.createTranslation({
    texts: ["Hello, how are you?", "Welcome to Camb.ai."],
    source_language: CambApi.Languages.EN_US,
    target_language: CambApi.Languages.FR_FR,
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createTranslation");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.translation.getTranslationTaskStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(2000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const result = await client.translation.getTranslationResult({ run_id: runId });
  for (const text of result.texts ?? []) {
    console.log(text);
  }
}

void main();
```

<Note>
  For streaming translation over a single string, see `client.translation.translationStream` in the generated client types.
</Note>

***

## Transcription

Send either `media_url` or a local `media_file`. Poll until the task succeeds, then request the structured text from `getTranscriptionResult`.

```typescript theme={null}
import { createReadStream } from "node:fs";
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.transcription.createTranscription({
    language: CambApi.Languages.EN_US,
    media_url: "https://example.com/audio.mp3",
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createTranscription");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.transcription.getTranscriptionTaskStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(3000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const result = await client.transcription.getTranscriptionResult({
    run_id: runId,
  });
  console.log(result);
}

void main();
```

To transcribe a local file, pass a stream or buffer-compatible upload as `media_file` instead of `media_url`.

### Subtitle-ready formatting

By default the transcript is segmented by natural speech patterns. Pass `formatting_options` to segment it into subtitle-ready cues instead, then request the export directly as `srt` or `vtt` on the result call:

```typescript theme={null}
const submitted = await client.transcription.createTranscription({
  language: CambApi.Languages.EN_US,
  media_url: "https://example.com/audio.mp3",
  formatting_options: {
    max_segment_duration_in_seconds: 7, // Default: 7 seconds; caps each segment length.
    min_segment_duration_in_seconds: 1, // Default: 1 second; avoids very short segments when possible.
    max_characters_in_segment: 42, // Default: 42 characters; keeps subtitle-style lines readable.
  },
});

// ... after polling reaches success
const result = await client.transcription.getTranscriptionResult({
  run_id: runId,
  format_type: CambApi.TranscriptFileFormat.Srt,
  data_type: CambApi.TranscriptDataType.RawData,
});
console.log(result.transcript);
```

<Note>
  With `format_type`/`data_type` set, `getTranscriptionResult` resolves to a `TranscriptExportResult` with a single `transcript` string instead of the segment array.
</Note>

***

## Subtitles

The subtitles client transcribes the source language, translates into any number of target languages, and, when you pass `formatting_options`, segments every language into subtitle-ready cues, in a single job. It follows the same create/poll/retrieve shape as transcription and dubbing. Pass a `media_url` — local file upload is not supported for subtitles.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.subtitles.createSubtitle({
    source_language: CambApi.Languages.EN_US,
    target_languages: [CambApi.Languages.ES_ES],
    media_url: "https://example.com/audio.mp3",
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createSubtitle");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.subtitles.getSubtitleTaskStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(5000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const result = await client.subtitles.getSubtitleResultForLanguage({
    run_id: runId,
    language: CambApi.Languages.ES_ES,
  });
  console.log(result.transcript);
}

void main();
```

<Note>
  `target_languages` is required and must be a non-empty array, even for a single language (`[CambApi.Languages.ES_ES]`).
</Note>

Pass `formatting_options` the same way as transcription to get subtitle-ready cues, and request a direct export with `format_type`/`data_type`:

```typescript theme={null}
const submitted = await client.subtitles.createSubtitle({
  source_language: CambApi.Languages.EN_US,
  target_languages: [CambApi.Languages.ES_ES],
  media_url: "https://example.com/audio.mp3",
  formatting_options: {
    max_segment_duration_in_seconds: 7, // Default: 7 seconds; caps each subtitle segment length.
    min_segment_duration_in_seconds: 1, // Default: 1 second; avoids very short subtitle flashes.
    max_characters_in_segment: 42, // Default: 42 characters; keeps subtitle lines readable.
  },
});

// ... after polling reaches success
const result = await client.subtitles.getSubtitleResultForLanguage({
  run_id: runId,
  language: CambApi.Languages.ES_ES,
  format_type: CambApi.TranscriptFileFormat.Vtt,
  data_type: CambApi.TranscriptDataType.RawData,
});
console.log(result.transcript);
```

To fetch every target language on the run in one call, drop `language` and call `client.subtitles.getSubtitleResult({ run_id: runId })` instead.

***

## Audio separation

Audio separation splits a mixed recording into stems. Upload `media_file`, poll `getAudioSeparationStatus`, then read stem metadata from `getAudioSeparationRunInfo`.

```typescript theme={null}
import { createReadStream } from "node:fs";
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.audioSeparation.createAudioSeparation({
    media_file: createReadStream("track.mp3"),
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createAudioSeparation");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.audioSeparation.getAudioSeparationStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(3000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const info = await client.audioSeparation.getAudioSeparationRunInfo({ run_id: runId });
  console.log(info);
}

void main();
```

***

## Text-to-voice

Text-to-voice synthesizes a new voice timbre from a written description and sample line. The pipeline is asynchronous: create the job, poll status, then inspect `getTextToVoiceResult` for preview URLs and identifiers you can feed back into TTS.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.textToVoice.createTextToVoice({
    text: "A confident narrator introducing a documentary.",
    voice_description:
      "Deep, measured baritone with a slight gravel. Calm and authoritative.",
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createTextToVoice");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.textToVoice.getTextToVoiceStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(3000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const result = await client.textToVoice.getTextToVoiceResult({ run_id: runId });
  console.log(result);
}

void main();
```

<Note>
  Inspect the `getTextToVoiceResult` payload for preview URLs and the `voice_id` you should pass into `textToSpeech.tts` for production speech.
</Note>

***

## Text-to-audio

Text-to-audio generates sound effects or ambient beds from a prompt. The create call returns a `task_id`. After polling succeeds, `getTextToAudioResult` returns streaming audio that `saveStreamToFile` can persist.

```typescript theme={null}
import { CambClient, CambApi, saveStreamToFile } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.textToAudio.createTextToAudio({
    prompt: "Heavy rain on a tin roof at night with distant thunder.",
    duration: 15,
    audio_type: CambApi.TextToAudioType.Sound,
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createTextToAudio");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.textToAudio.getTextToAudioStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(3000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const stream = await client.textToAudio.getTextToAudioResult({ run_id: runId });
  await saveStreamToFile(stream, "soundscape.mp3");
  console.log("Saved to soundscape.mp3");
}

void main();
```

***

## Stories

The story endpoint ingests a text or Word document, builds narration, and returns run metadata when processing completes. Pass `source_language` as `CambApi.Languages` and stream the document as `file`.

```typescript theme={null}
import { createReadStream } from "node:fs";
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.story.createStory({
    file: createReadStream("story.pdf"),
    source_language: CambApi.Languages.EN_US,
    title: "My Story",
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createStory");
  }

  let runId: number | null | undefined;
  while (true) {
    const status = await client.story.getStoryStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      runId = status.run_id ?? undefined;
      break;
    }
    await sleep(5000);
  }

  if (runId == null) {
    throw new Error("No run_id after success");
  }

  const info = await client.story.getStoryRunInfo({ run_id: runId });
  console.log(info);
}

void main();
```

***

## Translated TTS

Translated TTS translates text and renders speech in the target language in one pipeline. The TypeScript client exposes `createTranslatedTts` and `getTranslatedTtsTaskStatus`. When the status reports success, inspect the status object and the [API reference](/api-reference) for URLs or identifiers your integration should download.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function main() {
  const submitted = await client.translatedTts.createTranslatedTts({
    text: "Good morning, welcome to our service.",
    voice_id: 147320,
    source_language: CambApi.Languages.EN_US,
    target_language: CambApi.Languages.HI_IN,
  });

  const taskId = submitted.task_id;
  if (!taskId) {
    throw new Error("No task_id returned from createTranslatedTts");
  }

  while (true) {
    const status = await client.translatedTts.getTranslatedTtsTaskStatus({ task_id: taskId });
    if (status.status === CambApi.TaskStatus.Success) {
      console.log(status);
      break;
    }
    await sleep(3000);
  }
}

void main();
```

***

## Dictionaries

Dictionaries store glossary rows that dubbing and translation jobs can consume automatically. Upload bulk CSV files or manage individual terms through the JSON endpoints.

### List dictionaries

```typescript theme={null}
import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  const dictionaries = await client.dictionaries.getDictionaries();
  for (const d of dictionaries) {
    console.log(d.id, d.name);
  }
}

void main();
```

### Create from file

```typescript theme={null}
import { createReadStream } from "node:fs";
import { CambClient } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  await client.dictionaries.createDictionaryFromFile({
    dictionary_file: createReadStream("terms.csv"),
    dictionary_name: "Product Terms",
    dictionary_description: "Brand-specific terminology for our product line.",
  });
}

void main();
```

### Manage terms

Each translation row pairs a string with a `CambApi.Languages` value. Use numeric dictionary and term identifiers returned by previous API calls.

```typescript theme={null}
import { CambClient, CambApi } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  await client.dictionaries.addTermToDictionary({
    dictionary_id: 123,
    translations: [
      { translation: "कैम्ब.एआई", language: CambApi.Languages.HI_IN },
    ],
  });

  await client.dictionaries.deleteDictionaryTerm({
    dictionary_id: 123,
    term_id: 456,
  });

  await client.dictionaries.deleteDictionary({ dictionary_id: 123 });
}

void main();
```

### Folders

List or create folders with `client.folders.listFolders({})` and `client.folders.createFolder({ folder_name: "..." })` when you need to organize runs in Studio.

***

## Error handling

Failed HTTP responses throw `CambApiError`. Validation failures surface as `CambApi.UnprocessableEntityError`, which extends `CambApiError` and carries the parsed `body`.

```typescript theme={null}
import { CambClient, CambApi, CambApiError, saveStreamToFile } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
});

async function main() {
  try {
    const stream = await client.textToSpeech.tts({
      text: "Hello world.",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      voice_id: 147320,
      output_configuration: { format: "wav" },
    });
    await saveStreamToFile(stream, "out.wav");
  } catch (error) {
    if (error instanceof CambApi.UnprocessableEntityError) {
      console.error("Validation error", error.statusCode, error.body);
    } else if (error instanceof CambApiError) {
      console.error("API error", error.statusCode, error.body);
    } else {
      console.error(error);
    }
  }
}

void main();
```

Pass `requestOptions` on any call to override timeouts or retries for that request.

```typescript theme={null}
await client.textToSpeech.tts(
  {
    text: "Hello world.",
    language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
    voice_id: 147320,
    output_configuration: { format: "wav" },
  },
  { timeoutInSeconds: 30, maxRetries: 3 },
);
```

***

## Custom provider

Self-hosted MARS on Baseten reuses `textToSpeech.tts`, but you must construct `CambClient` with `ttsProvider: "baseten"` and supply `providerParams`. Baseten also requires base64 `reference_audio` and a `reference_language` entry inside `additional_body_parameters` on each TTS request. See [Custom Cloud Providers](/custom-cloud-providers) for deployment details.

### Baseten

```typescript theme={null}
import { readFileSync } from "node:fs";
import { CambClient, CambApi, CambApiError, saveStreamToFile } from "@camb-ai/sdk";

const client = new CambClient({
  apiKey: process.env.CAMB_API_KEY,
  ttsProvider: "baseten",
  providerParams: {
    api_key: process.env.BASETEN_API_KEY,
    mars_pro_url: process.env.BASETEN_URL,
  },
});

async function main() {
  try {
    const referenceAudio = readFileSync("reference.wav").toString("base64");
    const payload = {
      text: "Hello from a self-hosted MARS deployment.",
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      voice_id: 1,
      speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsPro,
      output_configuration: { format: "mp3" },
      additional_body_parameters: {
        reference_audio: referenceAudio,
        reference_language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      },
    } as CambApi.CreateStreamTtsRequestPayload & {
      additional_body_parameters: Record<string, string>;
    };

    const stream = await client.textToSpeech.tts(payload, { timeoutInSeconds: 300 });
    await saveStreamToFile(stream, "output.mp3");
  } catch (error) {
    if (error instanceof CambApiError) {
      console.error(error.statusCode, error.body);
    } else {
      console.error(error);
    }
  }
}

void main();
```

<Note>
  Baseten validates `reference_audio` and `reference_language`. You can supply only `ttsProvider` and `providerParams` if you never call the default Camb.ai API, or include `apiKey` when you use both hosted and Baseten routes in one process.
</Note>

***

## Next steps

<CardGroup>
  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice agents with Pipecat
  </Card>

  <Card title="LiveKit Integration" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/livekit-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=c750fcee9b1de69e3c1d0d6ec7eb6b3f" href="/integrations/livekit">
    Create voice agents with LiveKit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Explore the full TTS API
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>

***

## Resources

* [GitHub: camb-ai/cambai-node-sdk](https://github.com/Camb-ai/cambai-node-sdk)
* [SDK examples](https://github.com/Camb-ai/cambai-node-sdk/tree/main/examples)
* [API Reference](/api-reference/endpoint/create-tts-stream)


# Audio separation
Source: https://docs.camb.ai/tutorials/audio-separation-with-sdk

Split mixed audio into foreground and background stems using the Python or TypeScript SDK

## Overview

Separate a mixed recording into two stems: **foreground** (vocals, speech, or lead elements) and **background** (accompaniment, ambience, or supporting sounds). This is useful for remixing, isolation, accessibility, and cleaning up recordings.

The pipeline is asynchronous: you upload an audio file, poll until processing finishes, then download URLs for both stems.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def separate_audio():
      # Replace with your mixed audio file (WAV, MP3, FLAC, or AAC)
      audio_path = "mix.wav"

      # Step 1: Submit the separation job (multipart upload)
      response = client.audio_separation.create_audio_separation(
          media_file=open(audio_path, "rb"),
          project_name="my-separation-job",
      )

      task_id = response.task_id
      print(f"Audio separation task created: {task_id}")

      # Step 2: Poll until complete
      max_attempts = 60
      attempt = 0
      while attempt < max_attempts:
          status = client.audio_separation.get_audio_separation_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Step 3: Retrieve download URLs for both stems
              result = client.audio_separation.get_audio_separation_run_info(status.run_id)
              print(f"Foreground URL: {result.foreground_audio_url}")
              print(f"Background URL: {result.background_audio_url}")
              break
          elif status.status == "ERROR":
              print(f"Separation failed: {status.exception_reason}")
              break

          time.sleep(5)
          attempt += 1

  separate_audio()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient } from '@camb-ai/sdk';
  import * as fs from 'fs';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function separateAudio() {
      const audioPath = 'mix.wav'; // Replace with your mixed audio file

      if (!fs.existsSync(audioPath)) {
          console.error('Audio file not found:', audioPath);
          return;
      }

      // Step 1: Submit the separation job (multipart upload)
      const response = await client.audioSeparation.createAudioSeparation({
          media_file: fs.createReadStream(audioPath),
          project_name: 'my-separation-job'
      });

      const taskId = response.task_id;
      console.log(`Audio separation task created: ${taskId}`);

      if (!taskId) {
          console.error('No task ID returned.');
          return;
      }

      // Step 2: Poll until complete
      const maxAttempts = 60;
      let attempt = 0;

      while (attempt < maxAttempts) {
          const status = await client.audioSeparation.getAudioSeparationStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Step 3: Retrieve download URLs for both stems
              const result = await client.audioSeparation.getAudioSeparationRunInfo({
                  run_id: status.run_id
              });

              console.log(`Foreground URL: ${result.foreground_audio_url}`);
              console.log(`Background URL: ${result.background_audio_url}`);
              break;
          } else if (status.status === 'ERROR') {
              console.error(`Separation failed: ${status.exception_reason}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 5000));
          attempt++;
      }

      if (attempt >= maxAttempts) {
          console.error('Timeout waiting for separation to complete.');
      }
  }

  separateAudio();
  ```
</CodeGroup>

***

## Parameters

### Required

| Parameter    | Type        | Description                                               |
| ------------ | ----------- | --------------------------------------------------------- |
| `media_file` | file stream | Mixed audio to separate (uploaded as multipart form data) |

### Optional

| Parameter             | Type    | Description                         |
| --------------------- | ------- | ----------------------------------- |
| `project_name`        | string  | Label for the job in your dashboard |
| `project_description` | string  | Notes for the job                   |
| `folder_id`           | integer | Folder to organize the run under    |
| `run_id`              | integer | Optional run identifier for tracing |
| `traceparent`         | string  | Distributed tracing header value    |

***

## Tips

* **Formats:** FLAC, MP3, WAV, and AAC are supported; lossless or high-quality sources generally separate better than heavily compressed files.
* **Length:** Roughly 10 seconds to 10 minutes often works well; very long files may take more processing time.
* **Polling:** Cap your loop (for example 60 attempts × 5 seconds) and treat timeout as a separate failure path from `ERROR`.
* **Mix balance:** Foreground and background should both be audible in the original mix for cleaner stems.

***

## Next Steps

<CardGroup>
  <Card title="Create Audio Separation" icon="book" href="/api-reference/endpoint/create-audio-separation">
    Multipart upload and task creation API reference.
  </Card>

  <Card title="Get Separation Status" icon="clock" href="/api-reference/endpoint/get-audio-separation-status">
    Poll task status with `task_id`.
  </Card>

  <Card title="Get Separation Result" icon="audio-waveform" href="/api-reference/endpoint/get-audio-separation-run-info">
    Retrieve `foreground_audio_url` and `background_audio_url`.
  </Card>

  <Card title="Dubbing" icon="video" href="/tutorials/dubbing-with-sdk">
    Translate video audio with the SDK.
  </Card>
</CardGroup>


# Dubbing
Source: https://docs.camb.ai/tutorials/dubbing-with-sdk

Dub a video into another language using the Python or TypeScript SDK

## Overview

Translate the audio of any video into another language while preserving the original speaker's voice characteristics. Dubbing is useful for content localization, accessibility, and reaching global audiences without re-recording.

The dubbing pipeline is asynchronous: you submit a job, poll until it completes, then retrieve the dubbed output.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  response = client.dub.create_dub(
      video_url="your_accessible_video_url",
      source_language=Languages.EN_US,  # English (or check client.languages.get_source_languages())
      target_languages=[Languages.HI_IN],  # list of Languages, e.g. [Languages.HI_IN, Languages.FR_FR]
      transcription_mode="fast",
  )
  task_id = response.task_id
  print(f"Dub Task created with ID: {task_id}")

  while True:
      status_response = client.dub.get_dubbing_status(task_id=task_id)
      print(f"Current Status: {status_response.status}")
      if status_response.status == "SUCCESS":
          dubbed_run_info = client.dub.get_dubbed_run_info(run_id=status_response.run_id)
          print(f"Audio URL: {dubbed_run_info.audio_url}")
          print(f"Transcript: {dubbed_run_info.transcript}")
          print(f"Video URL: {dubbed_run_info.video_url}")
          break
      time.sleep(5)
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function dubVideo() {
      // Step 1: Submit the dubbing job
      const response = await client.dub.endToEndDubbing({
          video_url: 'your_accessible_video_url',
          source_language: CambApi.Languages.EN_US,
          target_languages: [CambApi.Languages.HI_IN], // pass an array, e.g. [HI_IN, FR_FR]
          transcription_mode: 'fast'
      });

      const taskId = response.task_id;
      console.log(`Dub Task created with ID: ${taskId}`);

      // Step 2: Poll until complete
      while (true) {
          const statusResponse = await client.dub.getEndToEndDubbingStatus({
              task_id: taskId
          });
          console.log(`Current Status: ${statusResponse.status}`);

          if (statusResponse.status === 'SUCCESS') {
              const dubbedRunInfo = await client.dub.getDubbedRunInfo({
                  run_id: statusResponse.run_id
              });
              console.log(`Audio URL: ${dubbedRunInfo.audio_url}`);
              console.log(`Transcript: ${dubbedRunInfo.transcript}`);
              console.log(`Video URL: ${dubbedRunInfo.video_url}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 5000));
      }
  }

  dubVideo();
  ```
</CodeGroup>

***

## Use Your Own SRT Transcript or Translation (Python)

Supply an original-language transcript with `source_transcript`, translated
dialogue with `target_transcripts`, or both. Read local `.srt` files as UTF-8 and
send their **contents**, not paths, URLs, base64 strings, or segment arrays.

<Note>
  This example requires a Python SDK release containing `DubSRTInput` and
  `DubTargetSRTInput` ([SDK change](https://github.com/Camb-ai/cambai-python-sdk/pull/44))
  and an API deployment supporting custom SRT input. If these imports are unavailable,
  check the SDK release before running this example. The example below is Python-only;
  it does not assume matching TypeScript SDK support.
</Note>

Save these files beside your script, using timestamps that match your source video:

<CodeGroup>
  ```text original.srt theme={null}
  1
  00:00:01,000 --> 00:00:03,000
  Hello, and welcome to our demo.
  ```

  ```text spanish.srt theme={null}
  1
  00:00:01,000 --> 00:00:03,000
  Hola, bienvenidos a nuestra demostración.
  ```
</CodeGroup>

Set `CAMB_API_KEY` and replace the video URL with your publicly accessible media.
This example submits both files, polls for up to ten minutes, and retrieves the result:

```python Python theme={null}
import os
import time
from pathlib import Path

from camb import DubSRTInput, DubTargetSRTInput
from camb.client import CambAI
from camb.errors import UnprocessableEntityError
from camb.types.language_enums import Languages

client = CambAI(api_key=os.environ["CAMB_API_KEY"])

try:
    response = client.dub.create_dub(
        video_url="https://example.com/your-video.mp4",
        source_language=Languages.EN_US,
        target_languages=[Languages.ES_ES],
        source_transcript=DubSRTInput(
            content=Path("original.srt").read_text(encoding="utf-8"),
        ),
        target_transcripts=[
            DubTargetSRTInput(
                language=Languages.ES_ES,
                content=Path("spanish.srt").read_text(encoding="utf-8"),
            )
        ],
    )
except UnprocessableEntityError as exc:
    print("Invalid dubbing input:", exc.body.detail)
    raise

print(f"Dub task: {response.task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    status = client.dub.get_dubbing_status(task_id=response.task_id)
    if status.status == "SUCCESS":
        if status.run_id is None:
            raise RuntimeError("Completed task returned no run ID")
        result = client.dub.get_dubbed_run_info(run_id=status.run_id)
        print(f"Audio URL: {result.audio_url}")
        print(f"Video URL: {result.video_url}")
        print(f"Transcript: {result.transcript}")
        break
    if status.status == "ERROR":
        raise RuntimeError(f"Dubbing failed: {status.exception_reason}")
    time.sleep(5)
else:
    raise TimeoutError(
        f"Still processing task {response.task_id}; resume polling instead of submitting again"
    )
```

* For a custom transcript only, omit `target_transcripts`; translations are generated automatically.
* For custom translations only, omit `source_transcript`. Include it when available to provide source-language context.
* For multiple translations, add one `DubTargetSRTInput` per language and include each language in `target_languages`, using `Languages` enums throughout. Targets without a supplied translation use automatic translation.
* Omit both fields to retain the automatic dubbing workflow. The same input arguments work with `AsyncCambAI`.

`format` defaults to `"srt"`. The API validates SRT parsing and requires at least
one cue, with limits of 2 MiB UTF-8 per script, 10 MiB combined, and 100 target
scripts. Target languages must be unique and included in `target_languages`.
Overlapping and out-of-order cues are allowed. API validation failures raise
`UnprocessableEntityError` (HTTP 422); `exc.body.detail` identifies the invalid fields.
See the [dubbing API reference](/api-reference/endpoint/end-to-end-dubbing) for the request contract.

***

## Parameters

### Required

| Parameter          | Type             | Description                                                                                                                                                |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `video_url`        | string           | Publicly accessible URL of the source video (YouTube links and direct URLs are supported)                                                                  |
| `source_language`  | `Languages` enum | Language spoken in the source video                                                                                                                        |
| `target_languages` | `Languages[]`    | List of languages to dub into. Pass a single-element list (`[Languages.HI_IN]`) for one target, or multiple to dub into several languages in a single job. |

### Optional

| Parameter                      | Type                               | Description                                                                                                                                                        |
| ------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `target_language`              | `Languages` enum                   | Single-language convenience alternative to `target_languages`. Prefer `target_languages=[Languages.HI_IN]` — `target_language` exists for backwards compatibility. |
| `project_name`                 | string                             | Label for the job in your dashboard                                                                                                                                |
| `project_description`          | string                             | Additional notes for the job                                                                                                                                       |
| `selected_audio_tracks`        | integer\[]                         | Specific audio track indices from the source video                                                                                                                 |
| `add_output_as_an_audio_track` | boolean                            | Attach the dubbed audio as an extra track instead of replacing the original                                                                                        |
| `source_transcript`            | `DubSRTInput` (Python)             | Original-language SRT contents; optional `format` defaults to `"srt"`.                                                                                             |
| `target_transcripts`           | `list[DubTargetSRTInput]` (Python) | Translated SRT contents, at most one per requested target language. Use `Languages` enums for `language`.                                                          |

### Language Enum

Use the `Languages` enum (Python) or `CambApi.Languages` (TypeScript) to specify languages:

<CodeGroup>
  ```python Python theme={null}
  from camb.types.language_enums import Languages

  # Examples
  Languages.EN_US   # English (US)
  Languages.ES_ES   # Spanish (Spain)
  Languages.FR_FR   # French
  Languages.DE_DE   # German
  Languages.HI_IN   # Hindi
  Languages.JA_JP   # Japanese
  Languages.ZH_CN   # Chinese (Simplified)
  ```

  ```javascript TypeScript theme={null}
  import { CambApi } from '@camb-ai/sdk';

  // Examples
  CambApi.Languages.EN_US   // English (US)
  CambApi.Languages.ES_ES   // Spanish (Spain)
  CambApi.Languages.FR_FR   // French
  CambApi.Languages.DE_DE   // German
  CambApi.Languages.HI_IN   // Hindi
  CambApi.Languages.JA_JP   // Japanese
  CambApi.Languages.ZH_CN   // Chinese (Simplified)
  ```
</CodeGroup>

***

## Tips

* **Video URL:** The URL must be publicly accessible. YouTube video links and direct file URLs (MP4, WebM) are both supported.
* **Polling timeout:** For long videos, cap your polling loop (e.g. 60 attempts × 5s = 5 minutes) and handle the timeout gracefully.
* **Multiple targets:** `target_languages` accepts an array — pass several languages to dub into all of them in a single job, which is more efficient than submitting separate jobs.
* **Transcripts:** The result object includes a `transcript` field with per-segment timing data, useful for subtitle generation.

***

## Next Steps

<CardGroup>
  <Card title="End-to-End Dubbing API" icon="book" href="/api-reference/endpoint/end-to-end-dubbing">
    Full API reference for the dubbing endpoint.
  </Card>

  <Card title="Get Dubbing Status" icon="clock" href="/api-reference/endpoint/get-end-to-end-dubbing-status">
    Status polling endpoint reference.
  </Card>

  <Card title="Get Dubbed Run Info" icon="film" href="/api-reference/endpoint/get-dubbed-run-info">
    Retrieve the dubbed output URLs and transcript.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Clone a custom voice for use in speech generation.
  </Card>
</CardGroup>


# Emotional Voice Control
Source: https://docs.camb.ai/tutorials/emotional-voice-control

Create emotionally nuanced speech with director-level control over tone, pacing, and character voice

MARS 8.1 Beta and `mars-instruct` both support expressive text controls, covering pronunciation overrides, non-verbal sounds, emotion tags, delivery hints, and SSML-style pauses. This page covers the syntax for each model.

## Hear the Examples

## MARS 8.1 Beta Text Controls

With `mars-8.1-flash-beta` and `mars-8.1-pro-beta`, you can add pronunciation and non-verbal controls directly in the text.

### Pronunciation Control (English)

Use CMU pronunciation dictionary phonemes in uppercase, wrapped in brackets, to override default English pronunciations.

```python Python theme={null}
response = client.text_to_speech.tts(
    text="Please [W AY1 N D] the clock before the strong [W IH1 N D] starts.",
    voice_id=147320,
    language="en-us",
    speech_model="mars-8.1-flash-beta",
    output_configuration=StreamTtsOutputConfiguration(format="wav")
)
```

```javascript TypeScript theme={null}
const response = await client.textToSpeech.tts({
  text: 'He plays the [B EY1 S] guitar while catching a [B AE1 S] fish.',
  voice_id: 147320,
  language: 'en-us',
  speech_model: 'mars-8.1-flash-beta',
  output_configuration: { format: 'wav' }
});
```

### Non-verbal Symbols

Insert supported tags directly in the text to add expressive non-verbal sounds.

```python Python theme={null}
response = client.text_to_speech.tts(
    text="[laughter] You really got me. I didn't see that coming at all.",
    voice_id=147320,
    language="en-us",
    speech_model="mars-8.1-flash-beta",
    output_configuration=StreamTtsOutputConfiguration(format="wav")
)
```

```javascript TypeScript theme={null}
const response = await client.textToSpeech.tts({
  text: '[laughter] You really got me. I didn\'t see that coming at all.',
  voice_id: 147320,
  language: 'en-us',
  speech_model: 'mars-8.1-flash-beta',
  output_configuration: { format: 'wav' }
});
```

## Supported tags for mars 8.1 :

Supported Tags: `[laughter]`, `[sigh]`, `[confirmation]`, `[question]`, `[surprise]`, `[dissatisfaction]`.

## Emotion Tags for Mars 8 Instruct:

`mars-instruct` accepts a richer set of inline tags for emotion, delivery, and sound effects. It also supports the `user_instructions` parameter for broader tone guidance across the whole request.

### Emotion Tone Tags

For emotional tone (happy, sad, angry), place inline tags directly in the `text` field and match your text content to the emotion. This is an alternative to `user_instructions`, not the same parameter.

| Inline tag | Example `text`                                          |
| ---------- | ------------------------------------------------------- |
| `[happy]`  | "\[happy] We won the match! This is the best day ever!" |
| `[sad]`    | "\[sad] I... I don't know if I can do this anymore..."  |

**Important:** The text content and punctuation must match the emotion for best results.

### Sound Effect Tags

Sound effect tags go **within** your sentence where the action naturally occurs:

| Tag          | Example                                                           | Notes                          |
| ------------ | ----------------------------------------------------------------- | ------------------------------ |
| `[laughing]` | "That's ridiculous! \[laughing] I can't believe that!"            | Produces laughter sound        |
| `[sighing]`  | "I guess we have to start over. \[sighing] Alright, let's begin." | Produces sigh sound            |
| `ahem ahem`  | "So what I was going to say is... ahem ahem... never mind."       | Produces throat-clearing sound |

## user\_instructions

The `user_instructions` parameter provides broader tone guidance for an entire `mars-instruct` speech request. Use it when you want the whole delivery to lean toward a style, mood, or character voice instead of controlling tone inline sentence by sentence.

| Instruction                    | Effect                             |
| ------------------------------ | ---------------------------------- |
| `shouting, angry, threatening` | Agitated, confrontational delivery |
| `whispering, secretive`        | Quiet, intimate delivery           |
| `empathetic, helpful`          | Caring, supportive delivery        |
| `happy, excited, promotional`  | Upbeat, promotional delivery       |
| `patient, teaching`            | Educational, measured delivery     |

## Delivery Tags

Delivery tags provide tone guidance for the words that follow them.

| Tag                              | Effect                             |
| -------------------------------- | ---------------------------------- |
| `[shouting, angry, threatening]` | Agitated, confrontational delivery |
| `[whispering, secretive]`        | Quiet, intimate delivery           |
| `[empathetic, helpful]`          | Caring, supportive delivery        |
| `[happy, excited, promotional]`  | Upbeat, promotional delivery       |
| `[patient, teaching]`            | Educational, measured delivery     |

## Emotion Tag Gradation Guide

### How To Use This

* Read each tag list from left to right.
* Left side means more balanced, subtle, or restrained.
* Right side means more extreme, forceful, or obvious.
* If you want the strongest controllable result, start from the rightmost tag.
* If you want a more natural or less exaggerated result, move one or two steps left.

This is a practical TTS guide, not a dictionary guide. Some tags are ordered by how strongly they tend to push delivery, not just by literal meaning.

### Examples Of Use

1. `[angry] Who stole my cash!`
2. `[trembling] I don't know who did it...`
3. `[cheerful] Welcome back. I saved you a seat.`
4. `[commanding] Stop right there and listen carefully.`

### Tag Ladders

Balanced -> Extreme

1. Nervousness: `[uneasy]` -> `[nervous]` -> `[anxious]` -> `[trembling]`
2. Fear: `[fearful]` -> `[scared]` -> `[terrified]` -> `[panicked]`
3. Anger: `[irritated]` -> `[angry]` -> `[furious]` -> `[enraged]`
4. Sadness: `[down]` -> `[sad]` -> `[melancholic]` -> `[depressed]`
5. Joy: `[cheerful]` -> `[happy]` -> `[joyful]` -> `[delighted]`
6. Excitement: `[energetic]` -> `[excited]` -> `[thrilled]` -> `[hyped]`
7. Calmness: `[relaxed]` -> `[calm]` -> `[peaceful]` -> `[serene]`
8. Confidence: `[assured]` -> `[confident]` -> `[certain]` -> `[bold]`
9. Doubt: `[uncertain]` -> `[doubtful]` -> `[hesitant]` -> `[skeptical]`
10. Surprise: `[surprised]` -> `[startled]` -> `[shocked]` -> `[astonished]`
11. Disgust: `[grossed_out]` -> `[disgusted]` -> `[repulsed]` -> `[revolted]`
12. Pride: `[satisfied]` -> `[accomplished]` -> `[proud]` -> `[fulfilled]`
13. Shame: `[embarrassed]` -> `[guilty]` -> `[ashamed]` -> `[humiliated]`
14. Love: `[warm]` -> `[affectionate]` -> `[loving]` -> `[tender]`
15. Flirtation: `[charming]` -> `[playful]` -> `[flirty]` -> `[teasing]`
16. Sarcasm: `[dry]` -> `[ironic]` -> `[sarcastic]` -> `[mocking]`
17. Determination: `[focused]` -> `[determined]` -> `[driven]` -> `[resolute]`
18. Frustration: `[annoyed]` -> `[irritated]` -> `[frustrated]` -> `[exasperated]`
19. Relief: `[calmed]` -> `[reassured]` -> `[relieved]` -> `[grateful]`
20. Curiosity: `[interested]` -> `[curious]` -> `[inquiring]` -> `[intrigued]`
21. Boredom: `[dull]` -> `[uninterested]` -> `[bored]` -> `[apathetic]`
22. Awe: `[inspired]` -> `[amazed]` -> `[awed]` -> `[wonderstruck]`
23. Suspicion: `[wary]` -> `[suspicious]` -> `[guarded]` -> `[distrustful]`
24. Urgency: `[urgent]` -> `[rushed]` -> `[intense]` -> `[pressured]`
25. Authority: `[firm]` -> `[authoritative]` -> `[directive]` -> `[commanding]`
26. Politeness: `[polite]` -> `[courteous]` -> `[respectful]` -> `[formal]`
27. Gratitude: `[appreciative]` -> `[thankful]` -> `[grateful]` -> `[warm]`
28. Confusion: `[uncertain]` -> `[puzzled]` -> `[confused]` -> `[lost]`
29. Hopelessness: `[resigned]` -> `[defeated]` -> `[hopeless]` -> `[despairing]`
30. Playfulness: `[lighthearted]` -> `[playful]` -> `[fun]` -> `[silly]`

### Practical Rule Of Thumb

* Use the leftmost tag when you want the emotion to be present but not overpower the sentence.
* Use the middle tags when you want clear emotional color without sounding theatrical.
* Use the rightmost tag when you need the emotion to come through strongly and consistently.

Example:

* Nervousness, subtle: `[uneasy]`
* Nervousness, clear: `[anxious]`
* Nervousness, strongest: `[trembling]`

### How To Generalize This To New Emotions

This same principle generalizes well to new emotions:

* Start with 3 to 4 tags for the same emotional family.
* Arrange them from balanced to extreme.
* Test them on the same sentence.
* Keep the tag that gives the clearest emotional control without distorting the sentence too much.
* When in doubt, the most extreme tag often gives the strongest controllability.

General rule:

`same emotion family + left-to-right intensity ladder + same test sentence = reliable controllable TTS`

## Combining Tags

For precise control, you can combine `user_instructions` with embedded emotion and delivery tags. Treat them as two controls: `user_instructions` guides the overall delivery, while inline tags guide specific moments in the text.

```python Python theme={null}
response = client.text_to_speech.tts(
    text="[sighing, secretive] I have a secret to tell you... [happy, excited] We're going to Paris!",
    voice_id=147320,
    language="en-us",
    speech_model="mars-instruct",
    user_instructions="emotional shifts from sad to excited",
    output_configuration=StreamTtsOutputConfiguration(format="wav")
)
```

```javascript TypeScript theme={null}
const response = await client.textToSpeech.tts({
  text: '[sighing, secretive] I have a secret to tell you... [happy, excited] We\'re going to Paris!',
  voice_id: 147320,
  language: 'en-us',
  speech_model: 'mars-instruct',
  user_instructions: 'emotional shifts from sad to excited',
  output_configuration: { format: 'wav' }
});
```

<AudioPlayer title="Hear the Example" />

## Pauses

Add SSML-style breaks anywhere in your text for dramatic pauses:

```text theme={null}
You... must... understand... this. <break time='600ms'/> The future begins NOW.
```

<div>
  <UseCaseCard title="Audiobook Narration" description="Warm, grandfatherly storytelling voice" icon="📚" />

  <UseCaseCard title="Game Dialogue" description="Shouting, angry, threatening villain" icon="🎮" />

  <UseCaseCard title="Marketing Voiceover" description="Energetic, enthusiastic promotion" icon="📣" />

  <UseCaseCard title="Educational Content" description="Patient, clear teaching style" icon="🎓" />

  <UseCaseCard title="Virtual Assistant" description="Empathetic, helpful response" icon="🤖" />

  <UseCaseCard title="Film Dubbing" description="Dramatic delivery with pauses" icon="🎬" />
</div>

## Best Practices

1. **Use specific tags** - Place concise delivery tags near the sentence they should affect
2. **Match content to emotion** - Text and punctuation should reflect the emotional tone
3. **Place sound effects naturally** - Tags like `[laughing]`, `[sighing]` work best within sentences
4. **Choose the right control** - Use inline tags for sentence-level emotion, or `user_instructions` for the overall speaking style
5. **Add pauses** - Use `<break time='600ms'/>` for dramatic effect

## Next Steps

<CardGroup>
  <Card title="Text to Speech" icon="audio-lines" href="/tutorials/tts-with-sdk">
    Get started with basic TTS using the Python or TypeScript SDK.
  </Card>

  <Card title="Choosing a Model" icon="bolt" href="/choosing-a-model">
    Compare mars-instruct with mars-flash and mars-pro.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Create custom voices for your emotional speech.
  </Card>

  <Card title="TTS with Accents" icon="globe" href="/tutorials/tts-with-accents">
    Generate speech in 140+ language accents.
  </Card>
</CardGroup>


# Live Transcription
Source: https://docs.camb.ai/tutorials/live-transcription-with-sdk

Stream microphone or file audio over a WebSocket and receive cumulative interim transcripts, word-level timing, and typed events from the Python or TypeScript SDK

<Note>
  **Beta.** Live transcription is available for testing in the Python and TypeScript SDKs. Event shapes, configuration options, and error semantics may change in backwards-incompatible ways before GA. Pin to the SDK versions you test against.
</Note>

## Overview

Stream raw audio bytes to CAMB over a single WebSocket and receive cumulative transcripts in real time. The session exposes a typed event dispatcher (`Ready`, `Results`, `Error`, `Closed`), a built-in microphone helper, and forward-compatible `onAny` subscription for events the server may add in future releases.

Key features:

* **Interim and final results** — interim `Results` (`is_final: false`) carry the cumulative transcript so far for the current utterance; render them as a live preview. A final `Results` (`is_final: true`) closes the utterance; commit it so each utterance is preserved instead of being overwritten by the next one.
* **Word-level timing** — the final `Results` (`is_final: true`) includes per-word start/end timestamps and confidence. Interim frames carry an empty `words` array.
* **Typed events** — the same typed event surface in both SDKs, with per-event typed payloads.
* **Easy extensibility** — new server event = one enum entry + one payload type + one parser entry. Nothing else changes.
* **Microphone helpers** — `sounddevice` in Python, `AudioWorklet` in the browser, `node-record-lpcm16` in Node.

### How segments and cumulative updates work

Speech arrives as a series of **utterances**. Within one utterance the server streams cumulative interim `Results` (`is_final: false`) — each adds whole words to the transcript so far (the model emits complete words, never partial-word fragments). After a short pause in the audio the server finalizes the utterance with a `Results` whose `is_final` is `true`, carrying the complete utterance; the next `Results` then starts a **brand-new utterance from an empty string**.

```text theme={null}
                             utterance 1                            utterance 2
Results     →  R            R            R*           R            R            R*
is_final    →  false        false        true         false        false        true
transcript  →  "good"       "good day"   "good day"   "see"        "see you"    "see you"
                                         └ commit ┘                             └ commit ┘
```

`R*` marks the final frame. Because **the transcript resets on every new utterance**, replacing your UI with the latest `transcript` and nothing else makes each utterance erase the previous one — the bug you see as text "rewriting the same line" after a pause. Instead, show the interim frames as a live preview, then **commit** the text when `is_final` is `true` (print it on its own line, or append it to a list) so finished utterances are preserved. When the client stops sending audio, the connection closes cleanly with WebSocket close code `1000`.

### Live Transcription SDK vs Async Transcription SDK

|           | Live Transcription                  | Async Transcription                |
| --------- | ----------------------------------- | ---------------------------------- |
| Transport | WebSocket (`/transcription/listen`) | REST (`/transcription/transcribe`) |
| Input     | Streamed PCM                        | File URL or upload                 |
| Latency   | \~hundreds of ms per partial        | Job-based polling                  |
| Use when  | Live captioning, voice UX, agents   | Recordings, batch jobs             |

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Get Started

### Create an API Key

Generate a key at [CAMB.AI Studio](https://studio.camb.ai) and export it as `CAMB_API_KEY` for the snippets below.

### Install

<CodeGroup>
  ```bash Python theme={null}
  pip install camb-sdk
  ```

  ```bash TypeScript (Node) theme={null}
  npm install @camb-ai/sdk node-record-lpcm16
  ```

  ```bash TypeScript (Browser) theme={null}
  npm install @camb-ai/sdk
  ```
</CodeGroup>

The Python SDK ships `sounddevice` as a regular dependency, so the `Microphone` helper works out of the box. In Node the microphone adapter additionally requires the host `sox` binary. The browser adapter needs no extra packages — it uses `getUserMedia` and an inlined `AudioWorklet`.

### Quickstart

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import os

  from camb.client import CambAI
  from camb.live_transcription import Microphone, ServerMessageType

  async def main():
      client = CambAI(api_key=os.environ["CAMB_API_KEY"])
      session = await client.live_transcription.connect(
          model="boli-v5",
          language="en-us",
          sample_rate=16000,
      )

      @session.on(ServerMessageType.RESULTS)
      def _(msg):
          text = msg.transcript.strip()
          if not text:
              return
          # Interim frames refine the current utterance; print them as they
          # arrive. On is_final the utterance is done — commit it on its own
          # line so the next utterance starts fresh instead of overwriting it.
          if not msg.is_final:
              print(f"[Interim] {text}\n", end="", flush=True)
          else:
              print(f"\r\033[K{text}\n", end="", flush=True)

      @session.on(ServerMessageType.CLOSED)
      def _(info):
          print(f"\nClosed code={info.code}")

      async with session:
          mic = Microphone(sample_rate=16000, chunk_size=1600)
          await session.stream_audio(mic)

  asyncio.run(main())
  ```

  ```ts TypeScript (Node) theme={null}
  import { CambClient, Microphone, ServerMessageType } from "@camb-ai/sdk";

  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });

  const session = await client.liveTranscription.connect({
      model: "boli-v5",
      language: "en-us",
      sampleRate: 16000,
  });

  session.on(ServerMessageType.Results, (msg) => {
      const text = msg.transcript.trim();
      if (!text) return;
      // Interim frames print as they arrive; commit the final on its own
      // line so the next utterance starts fresh instead of overwriting it.
      if (!msg.isFinal) {
          process.stdout.write(`[Interim] ${text}\n`);
      } else {
          process.stdout.write(`\r\x1b[K${text}\n`);
      }
  });

  const mic = Microphone.fromNode({ sampleRate: 16000 });
  await mic.start();
  await session.pipe(mic);
  ```

  ```ts TypeScript (Browser) theme={null}
  import { CambClient, Microphone, ServerMessageType } from "@camb-ai/sdk";

  const client = new CambClient({ apiKey: API_KEY });

  const session = await client.liveTranscription.connect({
      model: "boli-v5",
      language: "en-us",
  });

  // Keep finalized utterances; show the in-progress one live beneath them.
  let committed = "";
  session.on(ServerMessageType.Results, (msg) => {
      const text = msg.transcript.trim();
      const caption = document.getElementById("caption");
      if (msg.isFinal) {
          committed += (committed ? "\n" : "") + text;
          caption.innerText = committed;
      } else {
          caption.innerText = committed ? `${committed}\n${text}` : text;
      }
  });

  const mic = await Microphone.fromBrowser({ sampleRate: 16000 });
  await mic.start();
  await session.pipe(mic);
  ```
</CodeGroup>

***

## Events and Payloads

### Supported events

Both SDKs expose the typed events below through a single `ServerMessageType` enum. **Source** tells you who emits each one. `UtteranceEnd` is a raw wire event with no dedicated enum member — it arrives through the `onAny` catch-all.

| Event          | Wire `type`      | Source            | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------- | ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Ready`        | `"Ready"`        | Server            | Fires once, immediately after the WebSocket upgrade.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `Results`      | `"Results"`      | Server            | Fires many times. Carries the cumulative transcript for the current utterance. `is_final` is `false` for interim refinements and `true` on the frame that finalizes an utterance; the next `Results` after a final begins a new utterance. Per-word timing and confidence (`words[]`) are populated only on the final frame (`is_final: true`); interim frames carry an empty `words` array. Replace your in-progress line with `transcript`, then commit it when `is_final` is `true`. |
| `UtteranceEnd` | `"UtteranceEnd"` | Server (VAD)      | Boundary marker emitted around finals. No dedicated typed event — delivered via `on_any` / `onAny`. Prefer `is_final` on `Results` as your commit signal; use this only if you need the raw boundary.                                                                                                                                                                                                                                                                                   |
| `Error`        | `"Error"`        | Server **or** SDK | Server-side: protocol errors (invalid encoding, model failure, etc.). SDK-side: handler exceptions and transport-level failures are re-emitted through the same channel so applications have one place to look.                                                                                                                                                                                                                                                                         |
| `Closed`       | `"Closed"`       | SDK (synthetic)   | Emitted by the SDK when the underlying WebSocket closes. Carries the close `code` and `reason` (e.g. `1000` for a clean `CloseStream`, `1008` for an auth failure).                                                                                                                                                                                                                                                                                                                     |

**Catch-all subscription.** If a future server release adds a new event type before the SDK does, the dispatcher still delivers it to any handler registered via `session.on_any(...)` (Python) / `session.onAny(...)` (TypeScript) with the raw payload. Applications stay forward-compatible without forking the SDK.

### How events work

The session reads JSON frames off the WebSocket, looks up the wire `type` in a parser registry, builds the typed payload, and fans out to every handler registered for that event. Unknown event types are still delivered through `onAny` so applications keep working when the server adds new messages.

### Event payloads

<CodeGroup>
  ```json Ready theme={null}
  { "type": "Ready" }
  ```

  ```json Results (final — words populated) theme={null}
  {
    "type": "Results",
    "is_final": true,
    "start": 0.0,
    "duration": 1.24,
    "channel": {
      "alternatives": [{
        "transcript": "hello world",
        "confidence": 0.92,
        "words": [
          { "word": "hello", "start": 0.0, "end": 0.42, "confidence": 0.95 },
          { "word": "world", "start": 0.42, "end": 1.10, "confidence": 0.89 }
        ]
      }]
    },
    "metadata": {
      "request_id": "...",
      "model_info": { "name": "boli-v5", "version": "1.2.0" }
    }
  }
  ```

  ```json Results (interim — words empty) theme={null}
  {
    "type": "Results",
    "is_final": false,
    "channel": {
      "alternatives": [{ "transcript": "hello wor", "words": [] }]
    }
  }
  ```

  ```json Error theme={null}
  { "type": "Error", "code": "invalid_encoding", "message": "Unsupported encoding 'opus'" }
  ```

  ```json Closed (synthetic, emitted by SDK) theme={null}
  { "type": "Closed", "code": 1000, "reason": "" }
  ```
</CodeGroup>

A final `Results` (`is_final: true`) carries the same fields as an interim one, with one difference: **per-word timing is only populated on the final frame**. Interim frames carry an empty `words` array (`"words": []`); the final frame fills in each word's `start`, `end`, and `confidence`. There is no separate `Final` frame on the wire — finals arrive through the same `Results` handler — so branch on `msg.is_final` (Python) / `msg.isFinal` (TypeScript) to decide when to read word timing and commit an utterance.

### Subscribing to events

<CodeGroup>
  ```python Python theme={null}
  @session.on(ServerMessageType.RESULTS)
  def on_results(msg):
      # msg.is_final → interim refinement (False) vs finalized utterance (True)
      print(msg.is_final, msg.transcript, msg.words)

  @session.on(ServerMessageType.ERROR)
  def on_error(err):
      print(err.code, err.message)

  # Forward-compat: receive every event including new ones added later.
  @session.on_any
  def on_any(event_type, payload):
      print(event_type, payload)
  ```

  ```ts TypeScript theme={null}
  session.on(ServerMessageType.Results, (msg) => {
      // msg.isFinal → interim refinement (false) vs finalized utterance (true)
      console.log(msg.isFinal, msg.transcript, msg.words);
  });

  session.on(ServerMessageType.Error, (err) => {
      console.error(err.code, err.message);
  });

  session.onAny((event, payload) => {
      console.log(event, payload);
  });
  ```
</CodeGroup>

### Adding a custom event

If you fork the SDK or wrap it for an internal use-case, adding a new server event is a three-step change in either language:

1. Add a new member to `ServerMessageType`.
2. Define the payload (a Pydantic model in Python, an interface in TypeScript).
3. Register a parser in `PARSER_REGISTRY`.

No dispatch code outside the registry needs to change.

***

## Basic Configuration

Every option below is optional. Omit any to inherit the server default documented in [`api-reference/websockets/asyncapi.json`](/api-reference/websockets/listen).

| Option                       | Default                     | Description                                                                                                                                       |
| ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                      | `boli-v5`                   | Transcription model. `boli-v5` and `boli-v5-transcribe` are supported.                                                                            |
| `language`                   | `en-us`                     | Source language hint. Accepts BCP-47 codes (`en-us`, `pt-br`), the Languages enum name (`EN_US`), or its numeric ID. The model also auto-detects. |
| `encoding`                   | `linear16`                  | Audio encoding of the bytes you send. One of `linear16`, `linear32`, `alaw`, `mulaw`.                                                             |
| `sample_rate` / `sampleRate` | `16000`                     | Sample rate of the bytes you send. The server resamples internally.                                                                               |
| `channels`                   | `1`                         | Channel count of the bytes you send. Multi-channel input is downmixed to mono.                                                                    |
| `base_url` / `baseUrl`       | `wss://client.camb.ai/apis` | Override the WebSocket base URL.                                                                                                                  |

### Basic configuration example

<CodeGroup>
  ```python Python theme={null}
  session = await client.live_transcription.connect(
      model="boli-v5-transcribe",
      language="pt-br",
      encoding="linear16",
      sample_rate=48000,
      channels=1,
  )
  ```

  ```ts TypeScript theme={null}
  const session = await client.liveTranscription.connect({
      model: "boli-v5-transcribe",
      language: "pt-br",
      encoding: "linear16",
      sampleRate: 48000,
      channels: 1,
  });
  ```
</CodeGroup>

***

## Advanced Configuration

### KeepAlive

Some intermediaries (load balancers, browser proxies) close idle WebSocket connections after a few seconds of silence. If your audio pipeline can be bursty, send a `KeepAlive` frame between bursts.

<CodeGroup>
  ```python Python theme={null}
  await session.keep_alive()
  ```

  ```ts TypeScript theme={null}
  await session.keepAlive();
  ```
</CodeGroup>

### CloseStream

`session.close()` (Python: same name) sends `{"type": "CloseStream"}` and waits for the server's clean `1000` close. Always prefer this over just hanging up — it ensures the server flushes any pending transcript.

### Bring-your-own transport

The Python SDK's `connect()` accepts a `transport` argument implementing the `Transport` protocol. The TypeScript client accepts a `transport: () => Transport` factory. Use this to inject a mock during testing or to plug in a custom WebSocket implementation.

***

## Microphone Helpers

### Python — sounddevice

```python theme={null}
from camb.live_transcription import Microphone

mic = Microphone(sample_rate=16000, chunk_size=1600, device=None)
with mic:
    chunk = mic.read()  # blocking
```

`sounddevice` ships with `camb-sdk`, so no extra install step is needed. On Linux you may need to install PortAudio system libraries (e.g. `apt install libportaudio2`) — `sounddevice`'s docs cover platform prerequisites.

### TypeScript — browser

```ts theme={null}
const mic = await Microphone.fromBrowser({
    sampleRate: 16000,
    chunkMs: 100,
});
await mic.start();
```

Internally the helper requests the platform sample rate via `getUserMedia`, then downsamples to the requested rate inside an `AudioWorklet` so the server always sees PCM16 LE little-endian.

### TypeScript — Node

```ts theme={null}
const mic = Microphone.fromNode({ sampleRate: 16000 });
await mic.start();
```

The Node adapter is built on `node-record-lpcm16`, declared in `package.json` as an `optionalDependencies` entry. The host machine also needs the `sox` binary on `PATH`.

***

## Error Handling and Close Codes

### Server errors

Whenever the server cannot continue, it emits an `Error` frame and closes with a non-`1000` code:

```json theme={null}
{ "type": "Error", "code": "invalid_encoding", "message": "..." }
```

### Transport errors

Connection-level failures (DNS, TLS, mid-stream drops) are surfaced through the same `Error` event with `code: "transport_error"` (TypeScript) or `code: "handler_exception"` (Python), keeping a single observable channel for application code.

### Close codes

| Code    | Meaning                                                                            |
| ------- | ---------------------------------------------------------------------------------- |
| `1000`  | Normal close. Either side sent `CloseStream` / closed cleanly.                     |
| `1006`  | Abnormal close (transport dropped without a frame).                                |
| `4000+` | Application-specific. The server may use these for auth failures and quota errors. |

***

### Timeout

The Live Transcription API has an internal timeout of 1 hour. Please add retries to handle/create further connections.

## More Information

* [`/transcription/listen` WebSocket reference](/api-reference/websockets/listen) — the underlying wire protocol.
* [Python SDK](/sdk-guides/python-sdk) · [TypeScript SDK](/sdk-guides/typescript-sdk) — the full SDK guides.
* Source: [`cambai-python-sdk`](https://github.com/Camb-ai/cambai-python-sdk) · [`cambai-typescript-sdk`](https://github.com/Camb-ai/cambai-typescript-sdk).


# Realtime Speech To Speech
Source: https://docs.camb.ai/tutorials/realtime-translation-with-sdk

Stream microphone or file audio over a WebSocket and receive live transcripts, translated text, and translated speech audio from the Python and TypeScript SDKs

<Note>
  **Beta.** Realtime speech-to-speech translation is available for testing in the Python and TypeScript SDKs. Event shapes, configuration options, audio formats, and error semantics may change in backwards-incompatible ways before GA. Pin to the SDK version you test against.
</Note>

## Overview

Speak (or stream a file) in one language and receive the translation as **live text and synthesized speech** over a single WebSocket. The session exposes a typed event dispatcher, a built-in microphone helper, and a forward-compatible `on_any` subscription for events the server may add in future releases.

Key features:

* **Translated text and audio** — receive incremental translated text (`response.text.delta` / `response.text.done`) and translated speech audio (`response.audio.delta`) as you speak.
* **Typed events** — a single `ServerEventType` enum with per-event typed payloads.
* **Microphone + file helpers** — `Microphone` (via `sounddevice`) and `FileAudioSource` ship with the SDK.
* **Easy extensibility** — new server event = one enum entry + one payload type + one parser entry.

Audio is **PCM16, mono, 24 kHz in both directions** — the rate the realtime endpoint expects for input and emits for output.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Supported languages

`source_language` and `target_language` accept the BCP-47 tags below (case-insensitive). Pick any supported language as the source and any supported language as the target. See the [WebSocket API reference](/api-reference/websockets/realtime#supported-languages) for the authoritative list.

<Accordion title="Supported realtime languages (14)">
  | Code    | Language                       |
  | :------ | :----------------------------- |
  | `ar-ae` | Arabic (United Arab Emirates)  |
  | `ar-eg` | Arabic (Egypt)                 |
  | `ar-sa` | Arabic (Saudi Arabia)          |
  | `de-de` | German (Germany)               |
  | `en-gb` | English (United Kingdom)       |
  | `en-us` | English (United States)        |
  | `es-es` | Spanish (Spain)                |
  | `fr-ca` | French (Canada)                |
  | `fr-fr` | French (France)                |
  | `hi-in` | Hindi (India)                  |
  | `ja-jp` | Japanese (Japan)               |
  | `ko-kr` | Korean (Korea)                 |
  | `pt-br` | Portuguese (Brazil)            |
  | `zh-cn` | Chinese (Mandarin, Simplified) |
</Accordion>

***

## Get Started

### Create an API Key

Generate a key at [CAMB.AI Studio](https://studio.camb.ai) and export it as `CAMB_API_KEY` for the snippets below.

### Install

<CodeGroup>
  ```bash Python theme={null}
  pip install camb-sdk
  ```

  ```bash TypeScript (Node) theme={null}
  npm install @camb-ai/sdk node-record-lpcm16
  ```
</CodeGroup>

In Python, `sounddevice` ships with `camb-sdk`, so the `Microphone` and `Speaker` helpers work out of the box (on Linux you may need PortAudio, e.g. `apt install libportaudio2`). In Node, microphone capture uses `node-record-lpcm16` and audio playback uses the SDK's SoX-backed speaker — both need the host `sox` binary (e.g. `brew install sox`).

### Quickstart (microphone)

Speak into your mic; the translated speech plays back through your speakers and the translated text prints as it arrives.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import os
  import threading

  import sounddevice as sd

  from camb.client import CambAI
  from camb.live_transcription import Microphone
  from camb.realtime import ServerEventType

  SAMPLE_RATE = 24000  # PCM16 mono, both directions


  class Speaker:
      """Plays raw PCM16 mono bytes through the default output device."""

      def __init__(self, sample_rate: int = SAMPLE_RATE) -> None:
          self._buf = bytearray()
          self._lock = threading.Lock()
          self._stream = sd.RawOutputStream(
              samplerate=sample_rate, channels=1, dtype="int16", callback=self._cb
          )

      def _cb(self, outdata, frames, time_info, status) -> None:
          want = len(outdata)
          with self._lock:
              take = min(want, len(self._buf))
              outdata[:take] = bytes(self._buf[:take])
              del self._buf[:take]
          if take < want:
              outdata[take:] = b"\x00" * (want - take)  # underrun → silence

      def start(self):
          self._stream.start()

      def feed(self, pcm: bytes):
          with self._lock:
              self._buf.extend(pcm)

      def close(self):
          self._stream.stop()
          self._stream.close()


  async def main():
      client = CambAI(api_key=os.environ["CAMB_API_KEY"])
      session = await client.realtime.connect(
          source_language="en-us",
          target_language="de-de",
      )

      speaker = Speaker()

      @session.on(ServerEventType.TRANSCRIPT_COMPLETED)
      def _(event):
          print(f"\n[you]         {event.transcript}")

      @session.on(ServerEventType.TEXT_DONE)
      def _(event):
          print(f"[translation] {event.text}")

      @session.on(ServerEventType.AUDIO_DELTA)
      def _(event):
          speaker.feed(event.data)

      async with session:
          await session.wait_until_ready()
          speaker.start()
          mic = Microphone(sample_rate=SAMPLE_RATE, chunk_size=SAMPLE_RATE // 10)
          try:
              await session.stream_audio(mic)
          finally:
              speaker.close()


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import {
    CambClient,
    Microphone,
    RealtimeServerEventType,
    createSoxPcmSpeakerChecked,
  } from "@camb-ai/sdk";

  const SAMPLE_RATE = 24000; // PCM16 mono, both directions

  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });
  const session = await client.realtime.connect({
    sourceLanguage: "en-us",
    targetLanguage: "de-de",
  });

  // Plays raw PCM16 mono audio through SoX's `play` (install sox to hear it).
  const speaker = await createSoxPcmSpeakerChecked({ sampleRate: SAMPLE_RATE });

  session.on(RealtimeServerEventType.TranscriptCompleted, (event) =>
    console.log(`\n[you]         ${event.transcript}`),
  );
  session.on(RealtimeServerEventType.TextDone, (event) =>
    console.log(`[translation] ${event.text}`),
  );
  session.on(RealtimeServerEventType.AudioDelta, (event) =>
    speaker.feed(Buffer.from(event.data)),
  );

  await session.waitUntilReady();

  const mic = Microphone.fromNode({ sampleRate: SAMPLE_RATE });
  await mic.start();
  await session.stream(mic);
  await speaker.close();
  ```
</CodeGroup>

### Quickstart (file → file)

Useful on machines with no microphone (CI, servers). The input WAV must be 16-bit PCM, mono, 24 kHz; the translated audio is written to an output WAV.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import os
  import wave

  from camb.client import CambAI
  from camb.live_transcription import FileAudioSource
  from camb.realtime import ServerEventType

  SAMPLE_RATE = 24000


  async def main(in_path: str, out_path: str):
      client = CambAI(api_key=os.environ["CAMB_API_KEY"])
      session = await client.realtime.connect(
          source_language="en-us",
          target_language="de-de",
      )

      out_audio = bytearray()
      audio_done = asyncio.Event()

      @session.on(ServerEventType.TEXT_DONE)
      def _(event):
          print(f"[translation] {event.text}")

      @session.on(ServerEventType.AUDIO_DELTA)
      def _(event):
          out_audio.extend(event.data)

      @session.on(ServerEventType.AUDIO_DONE)
      def _(_):
          audio_done.set()

      async with session:
          await session.wait_until_ready()
          await session.stream_audio(FileAudioSource(in_path, real_time=True))
          try:
              await asyncio.wait_for(audio_done.wait(), timeout=30)
          except asyncio.TimeoutError:
              pass

      if out_audio:
          with wave.open(out_path, "wb") as out:
              out.setnchannels(1)
              out.setsampwidth(2)
              out.setframerate(SAMPLE_RATE)
              out.writeframes(bytes(out_audio))
          print(f"Wrote {len(out_audio) / (SAMPLE_RATE * 2):.1f}s to {out_path}")


  asyncio.run(main("input_24k_mono.wav", "translated_output.wav"))
  ```

  ```typescript TypeScript theme={null}
  import fs from "node:fs";

  import { CambClient, RealtimeServerEventType } from "@camb-ai/sdk";

  const SAMPLE_RATE = 24000;
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

  // Minimal 16-bit PCM mono WAV read/write.
  function readWav(path) {
    const buf = fs.readFileSync(path);
    let offset = 12;
    while (offset < buf.length - 8) {
      const id = buf.toString("ascii", offset, offset + 4);
      const size = buf.readUInt32LE(offset + 4);
      if (id === "data") return buf.subarray(offset + 8, offset + 8 + size);
      offset += 8 + size;
    }
    throw new Error("no data chunk in WAV");
  }

  function writeWav(path, pcm, sampleRate) {
    const h = Buffer.alloc(44);
    h.write("RIFF", 0); h.writeUInt32LE(36 + pcm.length, 4); h.write("WAVE", 8);
    h.write("fmt ", 12); h.writeUInt32LE(16, 16); h.writeUInt16LE(1, 20);
    h.writeUInt16LE(1, 22); h.writeUInt32LE(sampleRate, 24);
    h.writeUInt32LE(sampleRate * 2, 28); h.writeUInt16LE(2, 32); h.writeUInt16LE(16, 34);
    h.write("data", 36); h.writeUInt32LE(pcm.length, 40);
    fs.writeFileSync(path, Buffer.concat([h, pcm]));
  }

  const client = new CambClient({ apiKey: process.env.CAMB_API_KEY });
  const session = await client.realtime.connect({
    sourceLanguage: "en-us",
    targetLanguage: "de-de",
  });

  const outChunks = [];
  let resolveDone;
  const audioDone = new Promise((r) => (resolveDone = r));

  session.on(RealtimeServerEventType.TextDone, (event) =>
    console.log(`[translation] ${event.text}`),
  );
  session.on(RealtimeServerEventType.AudioDelta, (event) =>
    outChunks.push(Buffer.from(event.data)),
  );
  session.on(RealtimeServerEventType.AudioDone, () => resolveDone());

  await session.waitUntilReady();

  // Input WAV must be 16-bit PCM, mono, 24 kHz. Stream at real-time pace.
  const pcm = readWav("input_24k_mono.wav");
  const chunkSize = Math.floor(SAMPLE_RATE * 2 * 0.1); // 100 ms
  for (let i = 0; i < pcm.length; i += chunkSize) {
    await session.sendAudio(pcm.subarray(i, i + chunkSize));
    await sleep(100);
  }

  await Promise.race([audioDone, sleep(30_000)]);
  await session.close();

  writeWav("translated_output.wav", Buffer.concat(outChunks), SAMPLE_RATE);
  ```
</CodeGroup>

Re-encode any source file to the required format with:

```bash theme={null}
ffmpeg -i input.wav -ar 24000 -ac 1 -sample_fmt s16 input_24k_mono.wav
```

<Note>
  Feed the session **clear speech**. Music, silence, or noisy/low-quality audio may not be recognized by the speech model, in which case no transcript or translation is produced for that audio.
</Note>

***

## Events and Payloads

### Supported events

All events are exposed through the `ServerEventType` enum.

| Event                  | Wire `type`                                             | Notes                                                                                                                                 |
| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `SESSION_STARTING`     | `session.starting`                                      | Pipeline is booting (`slow` mode cold boot). Not yet ready for audio.                                                                 |
| `SESSION_CREATED`      | `session.created`                                       | Session is authorized and ready. `wait_until_ready()` resolves here.                                                                  |
| `SESSION_UPDATED`      | `session.updated`                                       | Echo of the active session configuration.                                                                                             |
| `TRANSCRIPT_DELTA`     | `conversation.item.input_audio_transcription.delta`     | Incremental transcript of the user's speech (source language); additive within one utterance.                                         |
| `TRANSCRIPT_COMPLETED` | `conversation.item.input_audio_transcription.completed` | Final transcript of a user utterance (source language).                                                                               |
| `TEXT_DELTA`           | `response.text.delta`                                   | Incremental translated text; additive within one response.                                                                            |
| `TEXT_DONE`            | `response.text.done`                                    | Complete translated text for the current response.                                                                                    |
| `AUDIO_DELTA`          | binary frame                                            | Chunk of synthesized translated speech. Synthesized by the SDK from the server's binary audio frame; `event.data` is raw PCM16 bytes. |
| `AUDIO_DONE`           | `response.audio.done`                                   | Current translated audio response is complete.                                                                                        |
| `ERROR`                | `error`                                                 | Server error, or a handler exception surfaced by the SDK.                                                                             |
| `CLOSED`               | `Closed`                                                | Synthetic — emitted by the SDK when the WebSocket closes. Carries `code` and `reason`.                                                |

<Note>
  Translated text arrives via `TEXT_DELTA` / `TEXT_DONE` and translated speech via `AUDIO_DELTA`. A source-language transcript (`TRANSCRIPT_COMPLETED`) is not emitted for every session, so don't rely on it as your only signal.
</Note>

**Catch-all subscription.** A future server event the SDK doesn't model yet is still delivered to any handler registered via `session.on_any(...)` with the raw payload, so applications stay forward-compatible.

### Subscribing to events

<CodeGroup>
  ```python Python theme={null}
  @session.on(ServerEventType.TEXT_DELTA)
  def on_text(event):
      print(event.delta, end="", flush=True)

  @session.on(ServerEventType.ERROR)
  def on_error(err):
      print("error:", err.message)

  # Forward-compat: receive every event, including ones added later.
  @session.on_any
  def on_any(event_type, payload):
      print(event_type, payload)
  ```

  ```typescript TypeScript theme={null}
  session.on(RealtimeServerEventType.TextDelta, (event) => {
    process.stdout.write(event.delta);
  });

  session.on(RealtimeServerEventType.Error, (err) => {
    console.error("error:", err.message);
  });

  // Forward-compat: receive every event, including ones added later.
  session.onAny((eventType, payload) => {
    console.log(eventType, payload);
  });
  ```
</CodeGroup>

***

## Configuration

| Option                 | Default             | Description                                                                                                    |
| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `source_language`      | — (required)        | BCP-47 tag of the input speech, e.g. `en-us`. Must be a [supported language](#supported-languages).            |
| `target_language`      | — (required)        | BCP-47 tag of the translation, e.g. `de-de`. Must be a [supported language](#supported-languages).             |
| `output_modalities`    | `["text", "audio"]` | Subset of `text` and `audio`.                                                                                  |
| `voice_id` / `voiceId` | built-in voice      | ID of one of your cloned voices to synthesize the translation with. Get it from `voice_cloning.list_voices()`. |

<CodeGroup>
  ```python Python theme={null}
  session = await client.realtime.connect(
      source_language="en-us",
      target_language="es-es",
      output_modalities=["text", "audio"],
      voice_id=147320,  # optional: one of your cloned voices
  )
  ```

  ```typescript TypeScript theme={null}
  const session = await client.realtime.connect({
    sourceLanguage: "en-us",
    targetLanguage: "es-es",
    outputModalities: ["text", "audio"],
    voiceId: 147320, // optional: one of your cloned voices
  });
  ```
</CodeGroup>

<Tip>
  **Voice selection.** Translated speech uses a built-in voice for the target
  language by default. Pass `voice_id` (`voiceId` in TypeScript) to synthesize
  it with one of your cloned voices instead. For the most natural-sounding
  results, choose a voice whose reference language matches `target_language`.
</Tip>

***

## More Information

* [Speech To Speech WebSocket reference](/api-reference/websockets/realtime) — the underlying wire protocol and full event list.
* [Python SDK](/sdk-guides/python-sdk) · [TypeScript SDK](/sdk-guides/typescript-sdk) — the full SDK guides.
* Source:
  [`cambai-python-sdk`](https://github.com/Camb-ai/cambai-python-sdk) (`examples/realtime_translation_microphone.py`, `examples/realtime_translation_file.py`) ·
  [`cambai-typescript-sdk`](https://github.com/Camb-ai/cambai-typescript-sdk) (`examples/realtime-translation-microphone.js`, `examples/realtime-translation-file.js`).


# Stories
Source: https://docs.camb.ai/tutorials/stories-with-sdk

Turn a text or Word document into narrated audio using the Python or TypeScript SDK

## Overview

Upload a `.txt` or `.docx` manuscript and produce **narrated audio**: full narration, an optional dialogue-only track, and optionally a time-coded transcript. Pick the narrator voice and source language, then run an asynchronous job and fetch URLs when it completes.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def narrate_story():
      # Replace with your story file (.txt or .docx)
      story_path = "story.txt"

      # Step 1: Submit the story job (multipart upload)
      response = client.story.create_story(
          file=open(story_path, "rb"),
          source_language=Languages.EN_US,
          title="My Story",
          description="Sample narrated story",
          narrator_voice_id=147320,
      )

      # Usually returns task_id for async processing (see Note below)
      task_id = getattr(response, "task_id", None)
      if not task_id:
          print("No task_id on response; if you received run_id directly, skip polling and call get_story_run_info.")
          return

      print(f"Story task created: {task_id}")

      # Step 2: Poll until complete
      max_attempts = 60
      attempt = 0
      while attempt < max_attempts:
          status = client.story.get_story_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Step 3: Full narration, dialogue track, optional transcript
              result = client.story.get_story_run_info(
                  status.run_id,
                  include_transcript=True,
              )
              print(f"Audio URL: {result.get('audio_url')}")
              print(f"Dialogue URL: {result.get('dialogue_url')}")
              transcript = result.get("transcript")
              if transcript:
                  for row in transcript[:2]:
                      print(f"[{row.get('start')}-{row.get('end')}ms] {row.get('speaker')}: {row.get('text')}")
              break
          elif status.status == "ERROR":
              print(f"Story failed: {status.exception_reason}")
              break

          time.sleep(5)
          attempt += 1

  narrate_story()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';
  import * as fs from 'fs';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function narrateStory() {
      const storyPath = 'story.txt'; // Replace with your .txt or .docx

      if (!fs.existsSync(storyPath)) {
          console.error('Story file not found:', storyPath);
          return;
      }

      // Step 1: Submit the story job (multipart upload)
      const response = await client.story.createStory({
          file: fs.createReadStream(storyPath),
          source_language: CambApi.Languages.EN_US,
          title: 'My Story',
          description: 'Sample narrated story',
          narrator_voice_id: 147320
      });

      // Usually returns task_id for async processing (see Note below)
      const taskId = 'task_id' in response && response.task_id ? response.task_id : null;
      if (!taskId) {
          console.error('No task_id on response; if you received run_id directly, skip polling and call getStoryRunInfo.');
          return;
      }

      console.log(`Story task created: ${taskId}`);

      // Step 2: Poll until complete
      const maxAttempts = 60;
      let attempt = 0;

      while (attempt < maxAttempts) {
          const status = await client.story.getStoryStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Step 3: Full narration, dialogue track, optional transcript
              const result = await client.story.getStoryRunInfo({
                  run_id: status.run_id,
                  include_transcript: true
              });

              console.log(`Audio URL: ${result['audio_url']}`);
              console.log(`Dialogue URL: ${result['dialogue_url']}`);
              const transcript = result['transcript'];
              if (Array.isArray(transcript)) {
                  for (const row of transcript.slice(0, 2)) {
                      const r = row;
                      console.log(
                          `[${r['start']}-${r['end']}ms] ${r['speaker']}: ${r['text']}`
                      );
                  }
              }
              break;
          } else if (status.status === 'ERROR') {
              console.error(`Story failed: ${status.exception_reason}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 5000));
          attempt++;
      }

      if (attempt >= maxAttempts) {
          console.error('Timeout waiting for story completion.');
      }
  }

  narrateStory();
  ```
</CodeGroup>

<Note>
  `create_story` / `createStory` may return either a **`task_id`** (poll as above) or, in some flows, a **`run_id`** immediately. If you already have `run_id`, call `get_story_run_info` / `getStoryRunInfo` without polling.
</Note>

***

## Parameters

### Required

| Parameter         | Type             | Description                                                                                                                                                 |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`            | file stream      | `.txt` or `.docx` content to narrate                                                                                                                        |
| `source_language` | `Languages` enum | Language of the manuscript (e.g. `Languages.EN_US`). The raw API also accepts locale-tag strings like `"en-us"`; numeric IDs still work but are deprecated. |

### Optional

| Parameter             | Type       | Description                                                                                                                                   |
| --------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`               | string     | Story title                                                                                                                                   |
| `description`         | string     | Short description                                                                                                                             |
| `narrator_voice_id`   | integer    | Voice ID for the narrator (use [list voices](/api-reference/endpoint/list-voices) or pick one from [Text to Speech](/tutorials/tts-with-sdk)) |
| `folder_id`           | integer    | Folder for organizing the run                                                                                                                 |
| `chosen_dictionaries` | integer\[] | Custom pronunciation dictionaries                                                                                                             |
| `run_id`              | integer    | Optional tracing / linkage                                                                                                                    |

***

## Tips

* **Formats:** Use `.txt` or `.docx` as described in the [Create Story](/api-reference/endpoint/create-story) reference.
* **Languages:** Use the SDK `Languages` enum (e.g. `Languages.EN_US`) for `source_language`. The raw API also accepts locale-tag strings like `"en-us"`. See [Get source languages](/api-reference/endpoint/get-source-languages) for the full list.
* **URLs:** Download links from `audio_url` and `dialogue_url` **expire after 24 hours**—fetch and store files promptly.
* **Polling:** Cap your loop (for example 60 attempts × 5 seconds) and handle timeouts separately from `ERROR` status.

***

## Next Steps

<CardGroup>
  <Card title="Create Story API" icon="book" href="/api-reference/endpoint/create-story">
    Multipart upload and story parameters.
  </Card>

  <Card title="Get Story Status" icon="clock" href="/api-reference/endpoint/get-story-status">
    Poll with `task_id`.
  </Card>

  <Card title="Get Story Run Info" icon="headphones" href="/api-reference/endpoint/get-story-run-info">
    `audio_url`, `dialogue_url`, and optional transcript.
  </Card>

  <Card title="Text to Speech" icon="audio-lines" href="/tutorials/tts-with-sdk">
    Generate speech and explore voices for `narrator_voice_id`.
  </Card>
</CardGroup>


# Subtitles
Source: https://docs.camb.ai/tutorials/subtitles-with-sdk

Generate cue-ready subtitles in one or more languages using the Python or TypeScript SDK

## Overview

Turn spoken media into cue-ready subtitles in the source language and any number of target languages, in a single job. The service transcribes the source, translates into each target language you request, and, when you ask for it, segments every language into cues sized for on-screen display. The pipeline is asynchronous: submit a job with a publicly accessible or signed media URL, poll until it completes, then retrieve the result for each language.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def create_subtitles():
      # Step 1: Submit the subtitle job
      response = client.subtitles.create_subtitle(
          source_language=Languages.EN_US,  # English (US)
          target_languages=[Languages.ES_ES],  # Spanish (Spain)
          media_url="https://example.com/meeting.mp3",
          transcription_mode="fast",
      )

      task_id = response.task_id
      print(f"Subtitle task created: {task_id}")

      # Step 2: Poll until complete
      while True:
          status = client.subtitles.get_subtitle_task_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Step 3: Retrieve the result for one target language
              result = client.subtitles.get_subtitle_result_for_language(
                  run_id=status.run_id,
                  language=Languages.ES_ES,
              )
              transcript = result["transcript"] if isinstance(result, dict) else result.transcript
              for segment in transcript[:3]:
                  print(f"[{segment['start']:.2f}-{segment['end']:.2f}] {segment['speaker']}: {segment['text']}")
              break
          elif status.status == "ERROR":
              print(f"Subtitle task failed: {status.exception_reason}")
              break

          time.sleep(5)

  create_subtitles()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function createSubtitles() {
      // Step 1: Submit the subtitle job
      const response = await client.subtitles.createSubtitle({
          source_language: CambApi.Languages.EN_US, // English (US)
          target_languages: [CambApi.Languages.ES_ES], // Spanish (Spain)
          media_url: 'https://example.com/meeting.mp3',
          transcription_mode: 'fast'
      });

      const taskId = response.task_id;
      console.log(`Subtitle task created: ${taskId}`);

      // Step 2: Poll until complete
      while (true) {
          const status = await client.subtitles.getSubtitleTaskStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Step 3: Retrieve the result for one target language
              const result = await client.subtitles.getSubtitleResultForLanguage({
                  run_id: status.run_id,
                  language: CambApi.Languages.ES_ES
              });

              for (const segment of result.transcript.slice(0, 3)) {
                  console.log(
                      `[${segment.start.toFixed(2)}-${segment.end.toFixed(2)}] ${segment.speaker}: ${segment.text}`
                  );
              }
              break;
          } else if (status.status === 'ERROR') {
              console.error(`Subtitle task failed: ${status.exception_reason}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 5000));
      }
  }

  createSubtitles();
  ```
</CodeGroup>

<Note>
  In the Python SDK, subtitle results come back as a plain dict (`result["transcript"]`), not a typed model like transcription's `get_transcription_result`. The `isinstance` check above handles that shape safely.
</Note>

### Generating multiple languages

List every locale you need in `target_languages` to translate and segment all of them from the same media URL:

<CodeGroup>
  ```python Python theme={null}
  response = client.subtitles.create_subtitle(
      source_language=Languages.EN_US,
      target_languages=[Languages.ES_ES, Languages.FR_FR],
      media_url="https://example.com/meeting.mp3",
  )
  ```

  ```javascript TypeScript theme={null}
  const response = await client.subtitles.createSubtitle({
      source_language: CambApi.Languages.EN_US,
      target_languages: [CambApi.Languages.ES_ES, CambApi.Languages.FR_FR],
      media_url: 'https://example.com/meeting.mp3'
  });
  ```
</CodeGroup>

Include the source language itself in `target_languages` if you also want same-language, subtitle-ready cues for the original speech.

To fetch every language on the run in one call instead of one at a time, drop the `language` argument:

<CodeGroup>
  ```python Python theme={null}
  result = client.subtitles.get_subtitle_result(run_id=status.run_id)
  ```

  ```javascript TypeScript theme={null}
  const result = await client.subtitles.getSubtitleResult({ run_id: status.run_id });
  ```
</CodeGroup>

With a single target language, this returns the same shape as `get_subtitle_result_for_language`. With more than one, it returns a result keyed by language.

***

## Subtitle Formatting

By default, target-language dialogue is translated but left unsegmented, the same speech-boundary segments you'd get from Translation, not subtitle-length cues. Pass `formatting_options` to segment every language into cues sized for on-screen display, and export directly as `srt` or `vtt`:

<CodeGroup>
  ```python Python theme={null}
  from camb.types.subtitle_formatting_options import SubtitleFormattingOptions

  formatting_options = SubtitleFormattingOptions(
      max_segment_duration_in_seconds=6,
      max_characters_in_segment=42,
  )

  response = client.subtitles.create_subtitle(
      source_language=Languages.EN_US,
      target_languages=[Languages.ES_ES],
      media_url="https://example.com/meeting.mp3",
      formatting_options=formatting_options,
  )
  ```

  ```javascript TypeScript theme={null}
  const response = await client.subtitles.createSubtitle({
      source_language: CambApi.Languages.EN_US,
      target_languages: [CambApi.Languages.ES_ES],
      media_url: 'https://example.com/meeting.mp3',
      formatting_options: {
          max_segment_duration_in_seconds: 7, // Default: 7 seconds; caps each subtitle segment length.
          min_segment_duration_in_seconds: 1, // Default: 1 second; avoids very short subtitle flashes.
          max_characters_in_segment: 42, // Default: 42 characters; keeps subtitle lines readable.
      }
  });
  ```
</CodeGroup>

* **`max_segment_duration_in_seconds`** (default `7.0`): the longest a single cue may stay on screen.
* **`min_segment_duration_in_seconds`** (default `1.0`): the shortest a single cue may stay on screen.
* **`max_characters_in_segment`** (default `42`): the maximum number of characters allowed in one cue.

Once the task succeeds, request the export directly by passing `format_type` (and optionally `data_type`) to the result call. The response then carries a single `transcript` string instead of a segment array:

<CodeGroup>
  ```python Python theme={null}
  result = client.subtitles.get_subtitle_result_for_language(
      run_id=status.run_id,
      language=Languages.ES_ES,
      format_type="vtt",
      data_type="raw_data",
  )
  print(result["transcript"] if isinstance(result, dict) else result.transcript)
  ```

  ```javascript TypeScript theme={null}
  const result = await client.subtitles.getSubtitleResultForLanguage({
      run_id: status.run_id,
      language: CambApi.Languages.ES_ES,
      format_type: CambApi.TranscriptFileFormat.Vtt,
      data_type: CambApi.TranscriptDataType.RawData
  });
  console.log(result.transcript);
  ```
</CodeGroup>

<Info>
  Need a plain transcript in a single language instead of translated, multi-language subtitles? Use the [Transcription](/tutorials/transcription-with-sdk) tutorial. It shares the same `formatting_options` field for subtitle-ready cues.
</Info>

***

## Parameters

### Required

| Parameter          | Type                | Description                                                                                                                                                                                       |
| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_language`  | `Languages` enum    | Language spoken in the source media (e.g. `Languages.EN_US`). The raw API also accepts locale-tag strings like `"en-us"`; numeric IDs still work but are deprecated. See [Languages](#languages). |
| `target_languages` | list of `Languages` | One or more output languages. Pass a single-item list when you only need one language (for example `[Languages.ES_ES]`).                                                                          |
| `media_url`        | string              | Publicly accessible or signed URL to the audio/video file. Local file upload is not supported for subtitles — host the file first.                                                                |

### Optional

| Parameter             | Type                                       | Description                                                                                                                                           |
| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_name`        | string                                     | Label for the job in your dashboard                                                                                                                   |
| `project_description` | string                                     | Additional notes for the job                                                                                                                          |
| `folder_id`           | integer                                    | Place the run inside a specific folder                                                                                                                |
| `transcription_mode`  | `fast` or `slow`                           | Choose a faster transcript or a more thorough pass for the source media; defaults to `fast`                                                           |
| `formatting_options`  | `SubtitleFormattingOptions` object or dict | Segments every language into subtitle-ready cues instead of leaving translated dialogue unsegmented. See [Subtitle Formatting](#subtitle-formatting). |

### Result shape

`get_subtitle_result_for_language` and `get_subtitle_result` return a `transcript` array for each language, with the same segment shape as transcription:

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `start`   | float  | Segment start time in seconds                  |
| `end`     | float  | Segment end time in seconds                    |
| `text`    | string | Transcribed or translated text for the segment |
| `speaker` | string | Speaker label (e.g. `Speaker 1`)               |

When a run has more than one language and you call `get_subtitle_result` without a `language`, the result is keyed by language instead of being a single `transcript` array. When you pass `format_type` and/or `data_type`, every returned language carries a single `transcript` string (the rendered `srt`/`vtt`/`txt` content or a presigned URL to it) instead of a segment array.

***

## Languages

The Python and TypeScript SDKs expect the `Languages` enum for both `source_language` and `target_languages`:

| Language         | Enum              | Locale (raw API) |
| ---------------- | ----------------- | ---------------- |
| English (US)     | `Languages.EN_US` | `en-us`          |
| Spanish (Spain)  | `Languages.ES_ES` | `es-es`          |
| French (France)  | `Languages.FR_FR` | `fr-fr`          |
| German (Germany) | `Languages.DE_DE` | `de-de`          |
| Mandarin Chinese | `Languages.ZH_CN` | `zh-cn`          |
| Japanese (Japan) | `Languages.JA_JP` | `ja-jp`          |
| Arabic           | `Languages.AR_SA` | `ar-sa`          |

If you're calling the API directly (not via the SDK), pass the locale tag. Numeric language IDs still work but are deprecated.

<Card icon="languages" href="/api-reference/endpoint/get-target-languages">
  For the full list of supported source and target languages, see the Source Languages and Target Languages reference.
</Card>

***

## Tips

* **Supported formats:** `.mp3`, `.wav`, `.aac`, `.flac`, `.mp4`, `.mov`, and `.mxf` (MXF is enterprise-only). For best quality use a lossless format like WAV or FLAC.
* **`media_url` is required:** host the recording and pass a publicly accessible or signed URL. Local file upload is not supported on the subtitle endpoint.
* **`target_languages` is required and non-empty:** always pass it as a list, even for a single language.
* **Polling timeout:** for long media, cap your polling loop (e.g. 60 attempts x 5s = 5 minutes) and handle the timeout gracefully.
* **Pick the right source language:** specifying the correct source language significantly improves both transcription and translation accuracy.

***

## Next Steps

<CardGroup>
  <Card title="Create Subtitle API" icon="book" href="/api-reference/endpoint/create-subtitle">
    Full API reference for the subtitle endpoint.
  </Card>

  <Card title="Poll Subtitle Result" icon="clock" href="/api-reference/endpoint/poll-subtitle-result">
    Status polling endpoint reference.
  </Card>

  <Card title="Get Subtitle Run Result" icon="captions" href="/api-reference/endpoint/get-subtitle-run-result">
    Retrieve subtitle segments and timing data for every language on a run.
  </Card>

  <Card title="Transcription" icon="captions" href="/tutorials/transcription-with-sdk">
    Transcribe a single language, with the same subtitle-ready formatting options.
  </Card>
</CardGroup>


# Text to Sound Effects
Source: https://docs.camb.ai/tutorials/text-to-sound

Generate sound effects and music from text prompts

## Overview

Generate royalty-free sound effects or music from natural language descriptions. Describe what you want to hear and get audio output.

### Listen to Examples

<AudioGrid>
  <AudioGridItem title="Sci-Fi Laser" />

  <AudioGridItem title="Rain" />

  <AudioGridItem title="Jazz" />

  <AudioGridItem title="Thunder" />

  <AudioGridItem title="Footsteps" />
</AudioGrid>

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI, save_stream_to_file

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def generate_sound():
      # Create sound effect from text prompt
      # audio_type: "sound" for effects, "music" for music
      response = client.text_to_audio.create_text_to_audio(
          prompt="Sword clashing against a metal shield in a medieval battle",
          duration=3.0,
          audio_type="sound"
      )

      task_id = response.task_id
      print(f"Task created: {task_id}")

      # Poll for completion
      while True:
          status = client.text_to_audio.get_text_to_audio_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              result = client.text_to_audio.get_text_to_audio_result(status.run_id)
              save_stream_to_file(result, "sound_effect.wav")
              print("Saved to sound_effect.wav")
              break
          elif status.status == "FAILED":
              print("Task failed!")
              break

          time.sleep(2)

  generate_sound()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, saveStreamToFile } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function generateSound() {
      // Create sound effect from text prompt
      // audio_type: "sound" for effects, "music" for music
      console.log('Creating sound effect...');
      const response = await client.textToAudio.createTextToAudio({
          prompt: 'Sword clashing against a metal shield in a medieval battle',
          duration: 3.0,
          audio_type: 'sound'
      });

      const taskId = response.task_id;
      console.log(`Task created: ${taskId}`);

      // Poll for completion
      while (true) {
          const status = await client.textToAudio.getTextToAudioStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              const result = await client.textToAudio.getTextToAudioResult({
                  run_id: status.run_id
              });
              await saveStreamToFile(result, 'sound_effect.wav');
              console.log('Saved to sound_effect.wav');
              break;
          } else if (status.status === 'FAILED') {
              console.log('Task failed!');
              break;
          }

          await new Promise(r => setTimeout(r, 2000));
      }
  }

  generateSound();
  ```
</CodeGroup>

***

## Parameters

| Parameter    | Description                                   | Values                 |
| ------------ | --------------------------------------------- | ---------------------- |
| `prompt`     | Natural language description of desired audio | Any text               |
| `duration`   | Length of audio in seconds                    | `1.0` - `30.0`         |
| `audio_type` | Type of audio to generate                     | `"sound"` or `"music"` |

***

## Use Cases

<div>
  <UseCaseCard title="Game Development" description="Generate unique sound effects for games" icon="🎮" />

  <UseCaseCard title="Video Production" description="Create custom audio for videos" icon="🎬" />

  <UseCaseCard title="Podcasts" description="Add background music or transitions" icon="🎙️" />

  <UseCaseCard title="Prototyping" description="Quick audio assets for demos" icon="⚡" />
</div>

***

## Next Steps

<CardGroup>
  <Card title="Text to Speech" icon="audio-lines" href="/tutorials/tts-with-sdk">
    Generate speech from text using the SDK.
  </Card>

  <Card title="TTS with Accents" icon="globe" href="/tutorials/tts-with-accents">
    Speak in 140+ language accents with the same voice.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Clone a voice from reference audio.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/create-text-to-sound">
    Full Text-to-Sound API specification.
  </Card>
</CardGroup>


# Transcription
Source: https://docs.camb.ai/tutorials/transcription-with-sdk

Transcribe an audio or video file into timestamped text using the Python or TypeScript SDK

## Overview

Convert spoken audio or video into accurate, timestamped text with speaker labels. The pipeline is asynchronous: submit a job with a local file or a public URL, poll until it completes, then retrieve the segmented transcript.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def transcribe_audio():
      # Step 1: Submit the transcription job
      response = client.transcription.create_transcription(
          language=Languages.EN_US,  # English (US)
          media_url="https://example.com/meeting.mp3",
          transcription_mode="fast",
      )

      task_id = response.task_id
      print(f"Transcription task created: {task_id}")

      # Step 2: Poll until complete
      while True:
          status = client.transcription.get_transcription_task_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Step 3: Retrieve the transcript
              result = client.transcription.get_transcription_result(run_id=status.run_id)
              for segment in result.transcript[:3]:
                  print(f"[{segment.start:.2f}-{segment.end:.2f}] {segment.speaker}: {segment.text}")
              break
          elif status.status == "ERROR":
              print(f"Transcription failed: {status.exception_reason}")
              break

          time.sleep(5)

  transcribe_audio()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function transcribeAudio() {
      // Step 1: Submit the transcription job
      const response = await client.transcription.createTranscription({
          language: CambApi.Languages.EN_US, // English (US)
          media_url: 'https://example.com/meeting.mp3',
          transcription_mode: 'fast'
      });

      const taskId = response.task_id;
      console.log(`Transcription task created: ${taskId}`);

      // Step 2: Poll until complete
      while (true) {
          const status = await client.transcription.getTranscriptionTaskStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Step 3: Retrieve the transcript
              const result = await client.transcription.getTranscriptionResult({
                  run_id: status.run_id
              });

              for (const segment of result.transcript.slice(0, 3)) {
                  console.log(
                      `[${segment.start.toFixed(2)}-${segment.end.toFixed(2)}] ${segment.speaker}: ${segment.text}`
                  );
              }
              break;
          } else if (status.status === 'ERROR') {
              console.error(`Transcription failed: ${status.exception_reason}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 5000));
      }
  }

  transcribeAudio();
  ```
</CodeGroup>

### Transcribing a local file

Pass `media_file` instead of `media_url` to upload a local file:

<CodeGroup>
  ```python Python theme={null}
  with open("meeting.mp3", "rb") as audio_file:
      response = client.transcription.create_transcription(
          language=Languages.EN_US,
          media_file=audio_file
      )
  ```

  ```javascript TypeScript theme={null}
  import { createReadStream } from 'fs';

  const response = await client.transcription.createTranscription({
      language: CambApi.Languages.EN_US,
      media_file: createReadStream('meeting.mp3')
  });
  ```
</CodeGroup>

***

## Subtitle Formatting

By default, the transcript is segmented by natural speech patterns rather than by subtitle-length rules. Pass `formatting_options` to segment it into subtitle-ready cues instead:

<CodeGroup>
  ```python Python theme={null}
  from camb.types.subtitle_formatting_options import SubtitleFormattingOptions

  formatting_options = SubtitleFormattingOptions(
      max_segment_duration_in_seconds=6,
      max_characters_in_segment=42,
  )

  response = client.transcription.create_transcription(
      language=Languages.EN_US,
      media_url="https://example.com/meeting.mp3",
      formatting_options=formatting_options,
  )
  ```

  ```javascript TypeScript theme={null}
  const response = await client.transcription.createTranscription({
      language: CambApi.Languages.EN_US,
      media_url: 'https://example.com/meeting.mp3',
      formatting_options: {
          max_segment_duration_in_seconds: 7, // Default: 7 seconds; caps each segment length.
          min_segment_duration_in_seconds: 1, // Default: 1 second; avoids very short segments when possible.
          max_characters_in_segment: 42, // Default: 42 characters; keeps subtitle-style lines readable.
      }
  });
  ```
</CodeGroup>

* **`max_segment_duration_in_seconds`** (default `7.0`): the longest a single segment may stay on screen.
* **`min_segment_duration_in_seconds`** (default `1.0`): the shortest a single segment may stay on screen.
* **`max_characters_in_segment`** (default `42`): the maximum number of characters allowed in one segment.

Once the task succeeds, request the transcript as `srt` or `vtt` instead of the structured JSON by passing `format_type` (and optionally `data_type`) to the result call. The response then carries a single `transcript` string instead of a segment array:

<CodeGroup>
  ```python Python theme={null}
  result = client.transcription.get_transcription_result(
      status.run_id,
      format_type="srt",
      data_type="raw_data",
  )
  print(result.transcript)
  ```

  ```javascript TypeScript theme={null}
  const result = await client.transcription.getTranscriptionResult({
      run_id: status.run_id,
      format_type: CambApi.TranscriptFileFormat.Srt,
      data_type: CambApi.TranscriptDataType.RawData
  });
  console.log(result.transcript);
  ```
</CodeGroup>

<Info>
  Need subtitles translated into languages other than the source? Use the [Subtitles](/tutorials/subtitles-with-sdk) tutorial. It runs the same segmentation across one or more target languages.
</Info>

***

## Parameters

### Required

| Parameter                     | Type             | Description                                                                                                                                                                                          |
| ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `language`                    | `Languages` enum | Source language for the spoken content (e.g. `Languages.EN_US`). The raw API also accepts locale-tag strings like `"en-us"`; numeric IDs still work but are deprecated. See [Languages](#languages). |
| `media_file` *or* `media_url` | file *or* string | Provide exactly one — a local audio/video file, or a publicly accessible URL.                                                                                                                        |

### Optional

| Parameter             | Type                                       | Description                                                                                                                             |
| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `project_name`        | string                                     | Label for the job in your dashboard                                                                                                     |
| `project_description` | string                                     | Additional notes for the job                                                                                                            |
| `folder_id`           | integer                                    | Place the run inside a specific folder                                                                                                  |
| `transcription_mode`  | `fast` or `slow`                           | Choose a faster transcript or a more thorough pass; defaults to `fast`                                                                  |
| `formatting_options`  | `SubtitleFormattingOptions` object or dict | Segments the transcript into subtitle-ready cues instead of natural speech boundaries. See [Subtitle Formatting](#subtitle-formatting). |

### Result shape

`get_transcription_result` returns a `TranscriptionResult` with a `transcript` array. Each segment contains:

| Field     | Type   | Description                      |
| --------- | ------ | -------------------------------- |
| `start`   | float  | Segment start time in seconds    |
| `end`     | float  | Segment end time in seconds      |
| `text`    | string | Transcribed text for the segment |
| `speaker` | string | Speaker label (e.g. `Speaker 1`) |

When you pass `format_type` and/or `data_type`, the call instead returns a `TranscriptExportResult` with a single `transcript` string, either the rendered `srt`/`vtt`/`txt` content or a presigned URL to it.

***

## Languages

The Python and TypeScript SDKs expect the `Languages` enum:

| Language         | Enum              | Locale (raw API) |
| ---------------- | ----------------- | ---------------- |
| English (US)     | `Languages.EN_US` | `en-us`          |
| Spanish (Spain)  | `Languages.ES_ES` | `es-es`          |
| French (France)  | `Languages.FR_FR` | `fr-fr`          |
| German (Germany) | `Languages.DE_DE` | `de-de`          |
| Mandarin Chinese | `Languages.ZH_CN` | `zh-cn`          |
| Japanese (Japan) | `Languages.JA_JP` | `ja-jp`          |
| Arabic           | `Languages.AR_SA` | `ar-sa`          |

If you're calling the API directly (not via the SDK), pass the locale tag. Numeric language IDs still work but are deprecated.

<Card icon="languages" href="/api-reference/endpoint/get-source-languages">
  For the full list of supported source languages, see the Source Languages reference.
</Card>

***

## Tips

* **Supported formats:** `.mp3`, `.wav`, `.aac`, `.flac`, `.mp4`, `.mov`, and `.mxf` (MXF is enterprise-only). For best quality use a lossless format like WAV or FLAC.
* **File size:** Uploaded files must be under 20 MB. For longer recordings, host the file and pass a `media_url` instead, or split the recording into chunks.
* **Polling timeout:** For long media, cap your polling loop (e.g. 60 attempts x 5s = 5 minutes) and handle the timeout gracefully.
* **Pick the right language:** Specifying the correct source language significantly improves accuracy. For multilingual content, choose the predominant language.

***

## Next Steps

<CardGroup>
  <Card title="Create Transcription API" icon="book" href="/api-reference/endpoint/create-transcription">
    Full API reference for the transcription endpoint.
  </Card>

  <Card title="Poll Transcription Result" icon="clock" href="/api-reference/endpoint/poll-transcription-result">
    Status polling endpoint reference.
  </Card>

  <Card title="Get Transcription Run Result" icon="captions" href="/api-reference/endpoint/get-transcription-run-result">
    Retrieve the transcript segments and timing data.
  </Card>

  <Card title="Subtitles" icon="captions" href="/tutorials/subtitles-with-sdk">
    Generate cue-ready subtitles translated into one or more target languages.
  </Card>

  <Card title="Dubbing" icon="video" href="/tutorials/dubbing-with-sdk">
    Translate a video into another language while preserving the original voice.
  </Card>
</CardGroup>


# Translated TTS
Source: https://docs.camb.ai/tutorials/translated-tts

Automatically translate text and generate speech in the target language

## Overview

Translate text and generate speech in one API call. Input text in any language, get audio output in your target language.

<Note>
  This is different from the standard TTS API which only changes accents. Translated TTS actually **translates** your text before speaking.
</Note>

### Hear the Translations

Same English input, automatically translated and spoken in each language:

<AudioGrid>
  <AudioGridItem title="Spanish" />

  <AudioGridItem title="French" />

  <AudioGridItem title="German" />

  <AudioGridItem title="Japanese" />

  <AudioGridItem title="Portuguese" />

  <AudioGridItem title="Hindi" />
</AudioGrid>

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  import requests
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def translate_and_speak():
      # Translate English to Spanish and generate speech
      # Language codes: 1 = English (US), 54 = Spanish (Spain)
      response = client.translated_tts.create_translated_tts(
          text="Hello, welcome to our service. We're glad to have you here.",
          source_language=Languages.EN_US,  # English (US)
          target_language=Languages.ES_ES,  # Spanish (Spain)
          voice_id=144300      # Voice ID (required)
      )

      task_id = response.task_id
      print(f"Task created: {task_id}")

      # Poll for completion
      while True:
          status = client.translated_tts.get_translated_tts_task_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Get the audio URL and download
              result = client.text_to_speech.get_tts_run_info(
                  run_id=status.run_id,
                  output_type="file_url"
              )
              audio_response = requests.get(result.output_url)
              with open("translated_output.wav", "wb") as f:
                  f.write(audio_response.content)
              print("Saved to translated_output.wav")
              break
          elif status.status == "FAILED":
              print("Translation failed!")
              break

          time.sleep(2)

  translate_and_speak()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';
  import fs from 'fs';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function translateAndSpeak() {
      // Translate English to Spanish and generate speech
      console.log('Translating and generating speech...');
      const response = await client.translatedTts.createTranslatedTts({
          text: "Hello, welcome to our service. We're glad to have you here.",
          source_language: CambApi.Languages.EN_US,  // English (US)
          target_language: CambApi.Languages.ES_ES,  // Spanish (Spain)
          voice_id: 144300                           // Voice ID (required)
      });

      const taskId = response.task_id;
      console.log(`Task created: ${taskId}`);

      // Poll for completion
      while (true) {
          const status = await client.translatedTts.getTranslatedTtsTaskStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Small delay to ensure result is available in backend
              await new Promise(r => setTimeout(r, 1000));

              // Get the audio URL and download
              const result = await client.textToSpeech.getTtsRunInfo({
                  run_id: status.run_id,
                  output_type: 'file_url'
              });
              const audioResponse = await fetch(result.output_url);
              const buffer = Buffer.from(await audioResponse.arrayBuffer());
              fs.writeFileSync('translated_output.wav', buffer);
              console.log('Saved to translated_output.wav');
              break;
          } else if (status.status === 'FAILED') {
              console.log('Translation failed!');
              break;
          }

          await new Promise(r => setTimeout(r, 2000));
      }
  }

  translateAndSpeak();
  ```
</CodeGroup>

***

## Parameters

| Parameter         | Description                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`            | Input text to translate                                                                                                                           |
| `source_language` | Source language (e.g., `Languages.EN_US`). The raw API also accepts locale-tag strings like `"en-us"`; numeric IDs still work but are deprecated. |
| `target_language` | Target language (e.g., `Languages.ES_ES`).                                                                                                        |
| `voice_id`        | Voice ID to use for speech generation (required)                                                                                                  |

### Common Languages

| Language            | Enum              | Locale (raw API) |
| ------------------- | ----------------- | ---------------- |
| English (US)        | `Languages.EN_US` | `en-us`          |
| Spanish (Spain)     | `Languages.ES_ES` | `es-es`          |
| French (France)     | `Languages.FR_FR` | `fr-fr`          |
| German (Germany)    | `Languages.DE_DE` | `de-de`          |
| Japanese (Japan)    | `Languages.JA_JP` | `ja-jp`          |
| Hindi (India)       | `Languages.HI_IN` | `hi-in`          |
| Portuguese (Brazil) | `Languages.PT_BR` | `pt-br`          |
| Chinese (Mandarin)  | `Languages.ZH_CN` | `zh-cn`          |

See [Language Support](/language-support) for the full list.

***

## Use Cases

<div>
  <UseCaseCard title="Global Announcements" description="Translate and speak messages in multiple languages" icon="📢" />

  <UseCaseCard title="Content Localization" description="Convert podcasts and videos to other languages" icon="🎬" />

  <UseCaseCard title="Customer Support" description="Respond in your customer's native language" icon="💬" />

  <UseCaseCard title="E-Learning" description="Translate course content automatically" icon="📚" />
</div>

***

## Next Steps

<CardGroup>
  <Card title="Emotional Voice Control" icon="sparkles" href="/tutorials/emotional-voice-control">
    Add emotional expression to translated speech.
  </Card>

  <Card title="TTS with Accents" icon="globe" href="/tutorials/tts-with-accents">
    Speak in 140+ accents without translating.
  </Card>

  <Card title="Text to Speech" icon="audio-lines" href="/tutorials/tts-with-sdk">
    Generate speech from text using the SDK.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Clone a voice from reference audio.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/create-translated-tts">
    Full Translated TTS API specification.
  </Card>
</CardGroup>


# Translation
Source: https://docs.camb.ai/tutorials/translation-with-sdk

Translate text into another language with formality, gender, age, and domain customization using the Python or TypeScript SDK

## Overview

Translate an array of text segments from one language into another with fine-grained control over tone (`formality`), grammatical `gender`, audience `age`, and domain-specific terminology (`chosen_dictionaries`). Translation is ideal for localizing user content, documents, support replies, marketing copy, or any batch of strings that needs to read naturally in another language.

The translation pipeline is asynchronous: you submit a job with one or more texts, poll until it completes, then retrieve the translations in the same order as the inputs.

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  from camb.client import CambAI
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def translate_texts():
      source_texts = [
          "Thank you for your inquiry about our services.",
          "We would be happy to schedule a meeting next week.",
          "Please let us know what day works best for you.",
      ]

      # Step 1: Submit the translation job
      response = client.translation.create_translation(
          texts=source_texts,
          source_language=Languages.EN_US,   # English (US)
          target_language=Languages.ES_ES,   # Spanish (Spain)
          formality=1,          # Formal
          gender=1,             # Masculine grammatical forms when relevant
          age=30,
      )

      task_id = response.task_id
      print(f"Translation task created: {task_id}")

      # Step 2: Poll until complete
      while True:
          status = client.translation.get_translation_task_status(task_id=task_id)
          print(f"Status: {status.status}")

          if status.status == "SUCCESS":
              # Step 3: Retrieve the translated texts
              result = client.translation.get_translation_result(run_id=status.run_id)
              for src, dst in zip(source_texts, result.texts):
                  print(f"EN: {src}\nES: {dst}\n---")
              break
          elif status.status in ("ERROR", "TIMEOUT", "PAYMENT_REQUIRED"):
              print(f"Translation failed: {status.status}")
              break

          time.sleep(2)

  translate_texts()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function translateTexts() {
      const sourceTexts = [
          'Thank you for your inquiry about our services.',
          'We would be happy to schedule a meeting next week.',
          'Please let us know what day works best for you.'
      ];

      // Step 1: Submit the translation job
      const response = await client.translation.createTranslation({
          texts: sourceTexts,
          source_language: CambApi.Languages.EN_US,  // English (US)
          target_language: CambApi.Languages.ES_ES,  // Spanish (Spain)
          formality: 1,         // Formal
          gender: 1,            // Masculine grammatical forms when relevant
          age: 30
      });

      const taskId = response.task_id;
      console.log(`Translation task created: ${taskId}`);

      // Step 2: Poll until complete
      while (true) {
          const status = await client.translation.getTranslationTaskStatus({
              task_id: taskId
          });

          console.log(`Status: ${status.status}`);

          if (status.status === 'SUCCESS') {
              // Step 3: Retrieve the translated texts
              const result = await client.translation.getTranslationResult({
                  run_id: status.run_id
              });

              sourceTexts.forEach((src, i) => {
                  console.log(`EN: ${src}\nES: ${result.texts[i]}\n---`);
              });
              break;
          } else if (['ERROR', 'TIMEOUT', 'PAYMENT_REQUIRED'].includes(status.status)) {
              console.error(`Translation failed: ${status.status}`);
              break;
          }

          await new Promise(resolve => setTimeout(resolve, 2000));
      }
  }

  translateTexts();
  ```
</CodeGroup>

***

## Customization options

### Formality

Adjust the formality level to fit the context. This affects pronoun choice (e.g. `tú` vs `usted` in Spanish, `du` vs `Sie` in German) and overall register.

| Value | Meaning  | Best for                                                      |
| ----- | -------- | ------------------------------------------------------------- |
| `1`   | Formal   | Business communications, official documents, customer support |
| `2`   | Informal | Casual chat, social posts, friendly marketing                 |

### Gender

In many target languages, adjectives, articles, and past participles agree with gender. Use the `gender` parameter to tell the engine which grammatical forms to prefer.

| Value | Meaning               |
| ----- | --------------------- |
| `0`   | Unspecified / neutral |
| `1`   | Masculine forms       |
| `2`   | Feminine forms        |
| `9`   | Other                 |

### Age

Pass an integer (e.g. `12`, `30`, `65`) to bias vocabulary and idioms toward an audience age range. Useful when translating content meant for kids or for very formal/elder audiences.

### Chosen dictionaries

Pass an array of dictionary IDs via `chosen_dictionaries` to apply specialized vocabulary (medical, legal, technical, etc.). Manage your dictionaries with the [Dictionaries API](/api-reference/endpoint/list-dictionaries).

***

## Parameters

### Required

| Parameter         | Type             | Description                                                                                                                                      |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `texts`           | string\[]        | Array of text segments to translate. Each item is translated independently and returned in the same order.                                       |
| `source_language` | `Languages` enum | Source language (e.g. `Languages.EN_US`). The raw API also accepts locale-tag strings like `"en-us"`; numeric IDs still work but are deprecated. |
| `target_language` | `Languages` enum | Target language (e.g. `Languages.ES_ES`).                                                                                                        |

### Optional

| Parameter             | Type       | Description                                                      |
| --------------------- | ---------- | ---------------------------------------------------------------- |
| `formality`           | integer    | `1` for formal, `2` for informal                                 |
| `gender`              | integer    | Grammatical gender hint: `0`, `1`, `2`, or `9` (see table above) |
| `age`                 | integer    | Target audience age, used to adapt vocabulary                    |
| `chosen_dictionaries` | integer\[] | Dictionary IDs to apply specialized vocabulary                   |
| `project_name`        | string     | Label for the job in your dashboard                              |
| `project_description` | string     | Additional notes for the job                                     |
| `folder_id`           | integer    | Place the run inside a specific folder                           |

### Result shape

`get_translation_result` returns a `TranslationResult` with a single field:

| Field   | Type      | Description                                                                                              |
| ------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `texts` | string\[] | Translated outputs, in the same order as the input `texts`. Pair index-by-index with the original array. |

***

## Languages

Translation requires both a `source_language` and a `target_language`. The Python and TypeScript SDKs expect the `Languages` enum:

| Language         | Enum              | Locale (raw API) |
| ---------------- | ----------------- | ---------------- |
| English (US)     | `Languages.EN_US` | `en-us`          |
| Spanish (Spain)  | `Languages.ES_ES` | `es-es`          |
| French (France)  | `Languages.FR_FR` | `fr-fr`          |
| German (Germany) | `Languages.DE_DE` | `de-de`          |
| Mandarin Chinese | `Languages.ZH_CN` | `zh-cn`          |
| Japanese (Japan) | `Languages.JA_JP` | `ja-jp`          |
| Arabic           | `Languages.AR_SA` | `ar-sa`          |

If you're calling the API directly (not via the SDK), pass the locale tag. Numeric language IDs still work but are deprecated.

<CardGroup>
  <Card icon="languages" href="/api-reference/endpoint/get-source-languages">
    Full list of supported source languages.
  </Card>

  <Card icon="globe" href="/api-reference/endpoint/get-target-languages">
    Full list of supported target languages.
  </Card>
</CardGroup>

***

## Tips

* **Batch in one call:** Pass multiple strings in a single `texts` array instead of submitting one task per string — it is faster and uses fewer credits.
* **Preserve order:** `result.texts[i]` always corresponds to `texts[i]` from the input. Pair them with `zip` (Python) or index-by-index access (TypeScript).
* **Polling cadence:** Translation is usually quick; a 1-2 second polling interval works well. Cap the total wait time (for example, 5 minutes) so your code never hangs forever.
* **Pick the right register:** Setting `formality` and `gender` on customer-facing translations dramatically improves how natural the output reads in languages like Spanish, French, German, and Italian.
* **Domain accuracy:** For medical, legal, or technical content, define a dictionary first and pass its ID in `chosen_dictionaries` so jargon is translated consistently across runs.

***

## Next Steps

<CardGroup>
  <Card title="Create Translation API" icon="book" href="/api-reference/endpoint/create-translation">
    Full API reference for the translation endpoint.
  </Card>

  <Card title="Poll Translation Status" icon="clock" href="/api-reference/endpoint/poll-translation-result">
    Status polling endpoint reference.
  </Card>

  <Card title="Get Translation Result" icon="languages" href="/api-reference/endpoint/get-translation-run-result">
    Retrieve the translated texts for a completed run.
  </Card>

  <Card title="Fetch Multiple Runs" icon="layers" href="/api-reference/endpoint/fetch-translation-runs-results">
    Batch-fetch results for several translation run IDs in one call.
  </Card>
</CardGroup>


# TTS with Accents
Source: https://docs.camb.ai/tutorials/tts-with-accents

Generate natural speech across the MARS language accents

## Overview

Generate speech with different language accents. The `language` parameter controls the accent/pronunciation style of the output — see [Language Support](/language-support) for the full per-model locale list.

The TTS API speaks the text you provide - it does **not** translate. To speak in a different language, provide input text in that language. For automatic translation + speech, use the [Translated TTS API](/api-reference/endpoint/create-translated-tts).

### Hear the Difference

Same text, different accents - all with the same voice:

<AudioGrid>
  <AudioGridItem title="English (US)" />

  <AudioGridItem title="English (UK)" />

  <AudioGridItem title="French" />

  <AudioGridItem title="Spanish" />
</AudioGrid>

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  import asyncio
  from camb.client import AsyncCambAI, save_async_stream_to_file
  from camb.types import StreamTtsOutputConfiguration

  client = AsyncCambAI(api_key=os.getenv("CAMB_API_KEY"))

  # Languages to generate
  LANGUAGES = [
      ("en-us", "English"),
      ("es-es", "Spanish"),
      ("fr-fr", "French"),
      ("pt-br", "Portuguese"),
  ]

  async def generate_language(text, lang_code, lang_name):
      """Generate TTS for a single language"""
      print(f"Generating {lang_name}...")
      response = client.text_to_speech.tts(
          text=text,
          language=lang_code,
          speech_model="mars-8.1-flash-beta",
          voice_id=144300,  # Replace with your voice ID
          output_configuration=StreamTtsOutputConfiguration(format="wav")
      )
      filename = f"output_{lang_code}.wav"
      await save_async_stream_to_file(response, filename)
      print(f"  Saved: {filename}")
      return filename

  async def main():
      text = "Welcome to our service. We're glad to have you here."

      print(f"Generating TTS in {len(LANGUAGES)} languages...\n")

      # Generate all languages concurrently
      tasks = [
          generate_language(text, code, name)
          for code, name in LANGUAGES
      ]
      files = await asyncio.gather(*tasks)

      print(f"\nDone! Generated {len(files)} audio files.")

  asyncio.run(main())
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, saveStreamToFile } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  // Languages to generate
  const LANGUAGES = [
      { code: 'en-us', name: 'English' },
      { code: 'es-es', name: 'Spanish' },
      { code: 'fr-fr', name: 'French' },
      { code: 'pt-br', name: 'Portuguese' },
  ];

  async function generateLanguage(text, langCode, langName) {
      console.log(`Generating ${langName}...`);
      const response = await client.textToSpeech.tts({
          text: text,
          language: langCode,
          speech_model: 'mars-8.1-flash-beta',
          voice_id: 144300,  // Replace with your voice ID
          output_configuration: {
              format: 'wav'
          },
      });
      const filename = `output_${langCode}.wav`;
      await saveStreamToFile(response, filename);
      console.log(`  Saved: ${filename}`);
      return filename;
  }

  async function main() {
      const text = "Welcome to our service. We're glad to have you here.";

      console.log(`Generating TTS in ${LANGUAGES.length} languages...\n`);

      // Generate all languages concurrently
      const promises = LANGUAGES.map(lang =>
          generateLanguage(text, lang.code, lang.name)
      );
      const files = await Promise.all(promises);

      console.log(`\nDone! Generated ${files.length} audio files.`);
  }

  main();
  ```
</CodeGroup>

***

## Supported Accents

Over 140 language accents are supported across CAMB.AI TTS. Common codes:

| Accent              | Code    |
| ------------------- | ------- |
| English (US)        | `en-us` |
| English (UK)        | `en-gb` |
| Spanish (Spain)     | `es-es` |
| Spanish (Mexico)    | `es-mx` |
| French              | `fr-fr` |
| German              | `de-de` |
| Italian             | `it-it` |
| Portuguese (Brazil) | `pt-br` |
| Japanese            | `ja-jp` |
| Korean              | `ko-kr` |
| Chinese (Mandarin)  | `zh-cn` |
| Hindi               | `hi-in` |
| Arabic              | `ar-sa` |
| Russian             | `ru-ru` |

See [API Reference](/api-reference/endpoint/get-target-languages) for the broader TTS language list.

If you are using `POST /tts-stream`, check the streaming API reference for endpoint-specific support and model-specific constraints.

***

## Use Cases

<div>
  <UseCaseCard title="Accent Variation" description="Same content, localized pronunciation for different markets" icon="🌍" />

  <UseCaseCard title="Character Voices" description="Give characters distinct accents in games or audiobooks" icon="🎭" />

  <UseCaseCard title="Language Learning" description="Hear native pronunciation for educational content" icon="📚" />

  <UseCaseCard title="Localized Content" description="Produce region-specific audio for global audiences" icon="📡" />
</div>

***

## Next Steps

<CardGroup>
  <Card title="Emotional Voice Control" icon="sparkles" href="/tutorials/emotional-voice-control">
    Add emotional expression and character to your speech with mars-instruct.
  </Card>

  <Card title="Translated TTS" icon="languages" href="/tutorials/translated-tts">
    Translate text and generate speech in the target language.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Clone a voice from reference audio.
  </Card>

  <Card title="Text to Sound Effects" icon="volume-2" href="/tutorials/text-to-sound">
    Generate sound effects and music from text.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/create-tts-stream">
    Full TTS streaming API specification.
  </Card>
</CardGroup>


# TTS with API
Source: https://docs.camb.ai/tutorials/tts-with-api

Use the Camb.ai TTS API directly for maximum control and flexibility

## Overview

While SDKs and frameworks provide convenience, sometimes you need direct control over API calls. This tutorial shows how to call the Camb.ai TTS API directly using HTTP requests.

### When to Use Direct API

* Building integrations in languages without an SDK
* Need fine-grained control over request/response handling
* Debugging or testing API behavior
* Building custom streaming implementations

### Listen to an Example

<AudioPlayer title="Direct API Output" />

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>
</Steps>

***

## Basic TTS Request

`POST /tts-stream` returns a **binary audio byte stream** (for example `audio/wav` or `audio/mpeg`), not Server-Sent Events or JSON chunks. The server sends the `Content-Type` that matches your `output_configuration.format`. You can buffer the full body for short clips, or read in chunks for lower latency—see [Stream Text-to-Speech Audio](/api-reference/endpoint/create-tts-stream).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://client.camb.ai/apis/tts-stream" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Hello from the command line!",
      "voice_id": 147320,
      "language": "en-us",
      "speech_model": "mars-8.1-flash-beta",
      "output_configuration": {
        "format": "wav"
      }
    }' \
    --output output.wav
  ```

  ```python Python (requests) theme={null}
  import os
  import requests

  def text_to_speech(text: str, voice_id: int = 147320) -> bytes:
      """Synchronous TTS call: stream the response and concatenate chunks (matches the streaming endpoint)."""
      api_key = os.getenv("CAMB_API_KEY")
      url = "https://client.camb.ai/apis/tts-stream"

      headers = {
          "x-api-key": api_key,
          "Content-Type": "application/json",
      }

      payload = {
          "text": text,
          "voice_id": voice_id,
          "language": "en-us",
          "speech_model": "mars-8.1-flash-beta",
          "output_configuration": {"format": "wav"},
      }

      with requests.post(url, headers=headers, json=payload, stream=True) as response:
          response.raise_for_status()
          return b"".join(
              chunk for chunk in response.iter_content(chunk_size=1024) if chunk
          )


  if __name__ == "__main__":
      audio = text_to_speech("Hello world!")
      with open("output.wav", "wb") as f:
          f.write(audio)
  ```

  ```python Python (aiohttp) theme={null}
  import asyncio
  import os
  import aiohttp

  async def text_to_speech(text: str, voice_id: int = 147320) -> bytes:
      """Convert text to speech using direct API call; buffers full body after a successful response."""
      api_key = os.getenv("CAMB_API_KEY")
      url = "https://client.camb.ai/apis/tts-stream"

      headers = {
          "x-api-key": api_key,
          "Content-Type": "application/json",
      }

      payload = {
          "text": text,
          "voice_id": voice_id,
          "language": "en-us",
          "speech_model": "mars-8.1-flash-beta",
          "output_configuration": {
              "format": "wav"
          },
      }

      timeout = aiohttp.ClientTimeout(total=120)

      async with aiohttp.ClientSession(timeout=timeout) as session:
          async with session.post(url, headers=headers, json=payload) as resp:
              resp.raise_for_status()
              return await resp.read()


  async def main():
      audio_data = await text_to_speech("Hello from the direct API!")

      with open("output.wav", "wb") as f:
          f.write(audio_data)

      print(f"Saved {len(audio_data)} bytes to output.wav")


  if __name__ == "__main__":
      asyncio.run(main())
  ```
</CodeGroup>

***

## Streaming Response

For real-time playback, iterate over the **raw response body** as chunks arrive. Always validate the status **before** reading the stream—non-success responses may return JSON (for example validation errors), not audio.

Responses can include the `X-Credits-Required` header for usage tracking (see the [API reference](/api-reference/endpoint/create-tts-stream)).

```python theme={null}
import asyncio
import os
import aiohttp


async def stream_tts(text: str, voice_id: int = 147320):
    """Yield audio chunks as they arrive; raises on non-success HTTP status."""
    api_key = os.getenv("CAMB_API_KEY")
    url = "https://client.camb.ai/apis/tts-stream"

    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
    }

    payload = {
        "text": text,
        "voice_id": voice_id,
        "language": "en-us",
        "speech_model": "mars-8.1-flash-beta",
        "output_configuration": {"format": "wav"},
    }

    timeout = aiohttp.ClientTimeout(total=120)

    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.post(url, headers=headers, json=payload) as resp:
            print(f"Status: {resp.status}")
            print(f"Content-Type: {resp.headers.get('Content-Type')}")
            print(f"X-Credits-Required: {resp.headers.get('X-Credits-Required')}")
            resp.raise_for_status()

            async for chunk in resp.content.iter_chunked(4096):
                yield chunk


async def main():
    with open("streamed_output.wav", "wb") as f:
        async for chunk in stream_tts("This is streamed audio generation."):
            f.write(chunk)


if __name__ == "__main__":
    asyncio.run(main())
```

***

## Request Parameters

These fields match [Stream Text-to-Speech Audio](/api-reference/endpoint/create-tts-stream) and the OpenAPI schema for `POST /tts-stream`.

### Required Parameters

| Parameter  | Type    | Description                                                                                                               |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `text`     | string  | Text to synthesize (**3–3000** characters)                                                                                |
| `language` | string  | BCP-47 locale (e.g. `en-us`). Case-sensitive lowercase. Unsupported locales for the chosen `speech_model` return **422**. |
| `voice_id` | integer | Voice profile ID from [`/list-voices`](/api-reference/endpoint/list-voices)                                               |

### Optional Parameters

| Parameter                              | Type    | Default                  | Description                                                                                                                                                                                                                                                                               |
| -------------------------------------- | ------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `speech_model`                         | string  | `mars-8.1-flash-beta`    | `mars-8.1-flash-beta`, `mars-8.1-pro-beta`, `mars-flash`, `mars-pro`, `mars-instruct`. MARS 8.1 beta models support inline pronunciation and non-verbal tags in `text`; `mars-instruct` uses a different expressive tag set ([API reference](/api-reference/endpoint/create-tts-stream)). |
| `user_instructions`                    | string  | `null`                   | Optional style, tone, pronunciation, or delivery guidance. Only supported with `speech_model: "mars-instruct"`.                                                                                                                                                                           |
| `output_configuration`                 | object  | format defaults to `wav` | `format`, optional `sample_rate`. Supported formats depend on `speech_model` (see the **Output format support by model** table in the API reference).                                                                                                                                     |
| `voice_settings`                       | object  | —                        | `speaking_rate`, reference quality, accent controls ([API reference](/api-reference/endpoint/create-tts-stream)).                                                                                                                                                                         |
| `inference_options`                    | object  | —                        | e.g. `inference_steps` where applicable ([API reference](/api-reference/endpoint/create-tts-stream)).                                                                                                                                                                                     |
| `enhance_named_entities_pronunciation` | boolean | `false`                  | Improves named-entity pronunciation when supported. **Not supported** for `mars-8.1-flash-beta` or `mars-8.1-pro-beta` (same as the API reference note).                                                                                                                                  |

More details available in the [API Reference](/api-reference/endpoint/create-tts-stream).

`mars-instruct` does not support `mp3` or `pcm_s16be` (see **Output format support by model** in the API reference).

***

## Expressive and pronunciation controls

* **`mars-8.1-flash-beta` / `mars-8.1-pro-beta`**: English CMU phoneme overrides (e.g. `[B EY1 S]`) and non-verbal tags such as `[laughter]`—see **MARS 8.1 Beta Text Controls** in the [API reference](/api-reference/endpoint/create-tts-stream).
* **`mars-instruct`**: Emotion and pacing tags and SSML-style pauses in `text`, plus optional `user_instructions` for broader delivery guidance—examples below.

When you use `speech_model: "mars-instruct"`, you can encode expression directly in the `text` field and use `user_instructions` for the overall style.

English examples:

* `[speaking slowly] This is very important. Please pay close attention.`
* `[excited] We shipped the feature, and the response has been fantastic!`
* `Let's pause for a moment <break time="400ms"/> and continue clearly.`

<Note>
  For a comprehensive guide on emotional expression, pauses, and prosody control, see the [Emotional Voice Control tutorial](/tutorials/emotional-voice-control).
</Note>

***

## Listing Voices

Get available voices:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import os
  import aiohttp


  async def list_voices():
      """List all available voices."""
      api_key = os.getenv("CAMB_API_KEY")
      url = "https://client.camb.ai/apis/list-voices"

      headers = {"x-api-key": api_key}

      async with aiohttp.ClientSession() as session:
          async with session.get(url, headers=headers) as resp:
              if resp.status == 200:
                  voices = await resp.json()
                  return voices
              else:
                  raise Exception(f"Error: {resp.status}")


  async def main():
      voices = await list_voices()

      print(f"Found {len(voices)} voices:\n")
      for voice in voices[:10]:  # Print first 10
          print(f"ID: {voice['id']}, Name: {voice['voice_name']}, Gender: {voice['gender']}")


  if __name__ == "__main__":
      asyncio.run(main())
  ```

  ```bash cURL theme={null}
  curl -X GET "https://client.camb.ai/apis/list-voices" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

***

## Playing Audio

<CodeGroup>
  ```python Using sounddevice theme={null}
  import asyncio
  import io
  import os
  import wave
  import aiohttp
  import numpy as np
  import sounddevice as sd


  async def play_tts(text: str):
      """Generate and play TTS audio."""
      api_key = os.getenv("CAMB_API_KEY")
      url = "https://client.camb.ai/apis/tts-stream"

      headers = {
          "x-api-key": api_key,
          "Content-Type": "application/json",
      }

      payload = {
          "text": text,
          "voice_id": 147320,
          "language": "en-us",
          "speech_model": "mars-8.1-flash-beta",
          "output_configuration": {"format": "wav"},
      }

      timeout = aiohttp.ClientTimeout(total=120)

      async with aiohttp.ClientSession(timeout=timeout) as session:
          async with session.post(url, headers=headers, json=payload) as resp:
              resp.raise_for_status()
              audio_bytes = await resp.read()

      # Parse WAV and extract PCM data
      with wave.open(io.BytesIO(audio_bytes), 'rb') as wav_file:
          sample_rate = wav_file.getframerate()
          audio_data = np.frombuffer(wav_file.readframes(-1), dtype=np.int16)

      sd.play(audio_data, samplerate=sample_rate)
      sd.wait()


  if __name__ == "__main__":
      asyncio.run(play_tts("Hello! This audio is playing directly."))
  ```

  ```python Converting raw PCM to WAV theme={null}
  import wave

  def save_as_wav(pcm_data: bytes, filename: str, sample_rate: int = 22050):
      """Save raw PCM16 mono bytes as a WAV file (use only when `output_configuration.format` is a raw `pcm_*` format)."""
      with wave.open(filename, "wb") as wav_file:
          wav_file.setnchannels(1)  # Mono
          wav_file.setsampwidth(2)  # 16-bit
          wav_file.setframerate(sample_rate)
          wav_file.writeframes(pcm_data)

  # Example: wrap PCM from a `pcm_*` stream after you have the full byte buffer
  # (If you use format "wav", the API already returns a WAV container—open it with wave.open(io.BytesIO(...)) instead.)
  if __name__ == "__main__":
      pcm_bytes = b"..."  # your raw PCM payload
      save_as_wav(pcm_bytes, "output.wav", sample_rate=22050)
  ```
</CodeGroup>

***

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/sdk-guides/python-sdk">
    Use the SDK for simpler integration
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/create-tts-stream">
    Complete API documentation
  </Card>

  <Card title="Voice Agents" icon="https://mintcdn.com/cambai/2LvnefIkletroPxv/images/pipecat-orange.svg?fit=max&auto=format&n=2LvnefIkletroPxv&q=85&s=40cf8e001b8cadc8a4c3c557dea603d5" href="/integrations/pipecat">
    Build real-time voice applications
  </Card>

  <Card title="Voice Library" icon="speech" href="/api-reference/endpoint/list-voices">
    Browse available voices
  </Card>
</CardGroup>


# TTS with SDK
Source: https://docs.camb.ai/tutorials/tts-with-sdk

Generate speech from text using the Python or TypeScript SDK

## Overview

Generate natural-sounding speech from text using the CAMB.AI SDK. This tutorial covers installation, generating your first audio, choosing a model, and listing voices.

### Listen to an Example

<AudioPlayer title="SDK Output" />

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  from camb.client import CambAI, save_stream_to_file
  from camb.types import StreamTtsOutputConfiguration

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  # Generate speech and save to file
  response = client.text_to_speech.tts(
      text="You really got me, I didn't see that coming at all.",
      voice_id=147320,
      language="en-us",
      speech_model="mars-8.1-flash-beta",
      output_configuration=StreamTtsOutputConfiguration(format="wav")
  )

  save_stream_to_file(response, "output.wav")
  print("Audio saved to output.wav")
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi, saveStreamToFile } from '@camb-ai/sdk';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function main() {
      // Generate speech and save to file
      const response = await client.textToSpeech.tts({
          text: '[laughter] You really got me. I didn\'t see that coming at all.',
          voice_id: 147320,
          language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
          speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.Mars81FlashBeta,
          output_configuration: { format: 'wav' }
      });

      await saveStreamToFile(response, 'output.wav');
      console.log('Audio saved to output.wav');
  }

  main();
  ```
</CodeGroup>

***

## MARS Instruct Delivery Control

Use `mars-instruct` when you want fine-grained control over tone and delivery. You can combine embedded expressive tags in `text` with `user_instructions` for broader style guidance.

<CodeGroup>
  ```python Python theme={null}
  response = client.text_to_speech.tts(
      text="[excited] We just shipped the feature, and the response has been fantastic!",
      voice_id=147320,
      language="en-us",
      speech_model="mars-instruct",
      user_instructions="Speak in an excited, upbeat tone",
      output_configuration=StreamTtsOutputConfiguration(format="wav")
  )

  save_stream_to_file(response, "excited.wav")
  ```

  ```javascript TypeScript theme={null}
  const response = await client.textToSpeech.tts({
      text: '[excited] We just shipped the feature, and the response has been fantastic!',
      voice_id: 147320,
      language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
      speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.MarsInstruct,
      user_instructions: 'Speak in an excited, upbeat tone',
      output_configuration: { format: 'wav' }
  });

  await saveStreamToFile(response, 'excited.wav');
  ```
</CodeGroup>

***

## Listing Voices

List available voices to find the right one for your use case:

<CodeGroup>
  ```python Python theme={null}
  voices = client.voice_cloning.list_voices()

  for voice in voices[:10]:
      print(f"ID: {voice['id']}, Name: {voice['voice_name']}, Gender: {voice['gender']}")
  ```

  ```javascript TypeScript theme={null}
  const voices = await client.voiceCloning.listVoices();

  for (const voice of voices.slice(0, 10)) {
      console.log(`ID: ${voice.id}, Name: ${voice.voice_name}, Gender: ${voice.gender}`);
  }
  ```
</CodeGroup>

***

## Parameters

### Required

| Parameter  | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| `text`     | string  | Text to convert to speech (min 3 characters) |
| `voice_id` | integer | Voice ID to use (e.g., `147320`)             |

### Optional

| Parameter              | Type   | Default        | Description                                                                              |
| ---------------------- | ------ | -------------- | ---------------------------------------------------------------------------------------- |
| `language`             | string | `"en-us"`      | BCP-47 language code                                                                     |
| `speech_model`         | string | `"mars-flash"` | `mars-8.1-flash-beta`, `mars-8.1-pro-beta`, `mars-flash`, `mars-pro`, or `mars-instruct` |
| `output_configuration` | object | `{}`           | Output format: `wav`, `mp3`, or `pcm_s16le`                                              |
| `user_instructions`    | string | `null`         | Tone/style guidance (`mars-instruct` only)                                               |

***

`mars-instruct` supports embedded emotion tags, SSML-style breaks, and `user_instructions` for fine-grained control. See [Emotional Voice Control](/tutorials/emotional-voice-control) for examples.

***

## Next Steps

<CardGroup>
  <Card title="Emotional Voice Control" icon="sparkles" href="/tutorials/emotional-voice-control">
    Add emotional expression and dramatic pacing with mars-instruct.
  </Card>

  <Card title="TTS with Accents" icon="globe" href="/tutorials/tts-with-accents">
    Generate speech in 140+ language accents with the same voice.
  </Card>

  <Card title="Voice Cloning" icon="mic" href="/tutorials/voice-cloning">
    Clone a voice from reference audio and generate speech with it.
  </Card>

  <Card title="MARS 8 Models" icon="bolt" href="/choosing-a-model">
    Compare model variants in detail.
  </Card>
</CardGroup>


# Voice Cloning
Source: https://docs.camb.ai/tutorials/voice-cloning

Clone a voice from reference audio and generate speech with it

## Overview

Create a custom voice clone from a reference audio file and use it to generate speech. The cloned voice captures the unique characteristics of the original speaker.

### Requirements

* Reference audio file (10-30 seconds of clear speech)
* Supported formats: WAV, MP3, FLAC, OGG
* Clean audio with minimal background noise works best

### Prerequisites

<Steps>
  <Step title="Create an account">
    Sign up at [CAMB.AI Studio](https://studio.camb.ai) if you haven't already.
  </Step>

  <Step title="Get your API key">
    Go to **Settings → API Keys** in Studio and copy your key. See [Authentication](/getting-started/authentication) for details.
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install camb-sdk
      ```

      ```bash TypeScript theme={null}
      npm install @camb-ai/sdk
      ```
    </CodeGroup>

    Skip this step if you're using the [direct API](/tutorials/direct-api).
  </Step>

  <Step title="Set your API key to use in your code">
    ```bash theme={null}
    export CAMB_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

***

## Code

<CodeGroup>
  ```python Python theme={null}
  import os
  from camb.client import CambAI, save_stream_to_file
  from camb.types import StreamTtsOutputConfiguration
  from camb.types.language_enums import Languages

  client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

  def clone_voice():
      # Create custom voice from reference audio
      print("Creating custom voice from reference audio...")
      custom_voice = client.voice_cloning.create_custom_voice(
          file=open("reference.wav", "rb"),
          voice_name="my-cloned-voice",
          gender=1,  # 1 = male, 2 = female
          description="Custom cloned voice",
          language=Languages.EN_US
      )

      print(f"Voice created! ID: {custom_voice.voice_id}")

      # Generate speech with the cloned voice
      print("Generating speech with cloned voice...")
      response = client.text_to_speech.tts(
          text="Hello! This is my cloned voice speaking.",
          voice_id=custom_voice.voice_id,
          language="en-us",
          speech_model="mars-8.1-flash-beta",
          output_configuration=StreamTtsOutputConfiguration(format="wav")
      )

      save_stream_to_file(response, "cloned_output.wav")
      print("Audio saved to cloned_output.wav")

  clone_voice()
  ```

  ```javascript TypeScript theme={null}
  import { CambClient, CambApi, saveStreamToFile } from '@camb-ai/sdk';
  import * as fs from 'fs';

  const client = new CambClient({
      apiKey: process.env.CAMB_API_KEY
  });

  async function cloneVoice() {
      const referenceAudioPath = 'reference.wav';

      if (!fs.existsSync(referenceAudioPath)) {
          console.error('Reference audio file not found');
          console.log('Requirements:');
          console.log('  - Audio: 10-30 seconds of clear speech');
          console.log('  - Formats: WAV, MP3, FLAC, OGG');
          return;
      }

      // Create custom voice from reference audio
      console.log('Creating custom voice from reference audio...');
      const customVoice = await client.voiceCloning.createCustomVoice({
          file: fs.createReadStream(referenceAudioPath),
          voice_name: `cloned-voice-${Date.now()}`,
          gender: 1, // 1 = male, 2 = female
          description: 'Custom cloned voice',
          language: CambApi.Languages.EN_US
      });

      console.log(`Voice created! ID: ${customVoice.voice_id}`);

      // Generate speech with the cloned voice
      console.log('Generating speech with cloned voice...');
      const response = await client.textToSpeech.tts({
          text: 'Hello! This is my cloned voice speaking.',
          voice_id: customVoice.voice_id,
          language: CambApi.CreateStreamTtsRequestPayload.Language.EnUs,
          speech_model: CambApi.CreateStreamTtsRequestPayload.SpeechModel.Mars81FlashBeta,
          output_configuration: { format: 'wav' }
      });

      await saveStreamToFile(response, 'cloned_output.wav');
      console.log('Audio saved to cloned_output.wav');
  }

  cloneVoice();
  ```
</CodeGroup>

***

## Parameters

| Parameter  | Description    | Values                                                                               |
| ---------- | -------------- | ------------------------------------------------------------------------------------ |
| `gender`   | Voice gender   | `1` = male, `2` = female                                                             |
| `language` | Voice language | Use `Languages` enum (e.g., `Languages.EN_US`, `Languages.ES_ES`, `Languages.FR_FR`) |

***

## Tips

* Use high-quality reference audio for best results
* 15-20 seconds of speech is ideal
* Avoid background music or noise in reference audio
* The cloned voice is saved to your account for future use

***

## Next Steps

<CardGroup>
  <Card title="Emotional Voice Control" icon="sparkles" href="/tutorials/emotional-voice-control">
    Add emotional expression to your cloned voices with mars-instruct.
  </Card>

  <Card title="Text to Speech" icon="audio-lines" href="/tutorials/tts-with-sdk">
    Generate speech with any voice using the SDK.
  </Card>

  <Card title="TTS with Accents" icon="globe" href="/tutorials/tts-with-accents">
    Speak in 140+ language accents with the same voice.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/endpoint/create-custom-voice">
    Full voice cloning API specification.
  </Card>

  <Card title="Text to Sound Effects" icon="volume-2" href="/tutorials/text-to-sound">
    Generate sound effects and music from text.
  </Card>
</CardGroup>