> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Text-to-Speech Result

> Retrieves the result of a specific Text-to-Speech run using the provided `run_id`.

<Card icon="lightbulb" cta="Go to streaming Text-to-Speech" 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.


## OpenAPI

````yaml get /tts-result/{run_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /tts-result/{run_id}:
    get:
      tags:
        - Apis
      summary: Get Tts Run Info
      operationId: get_tts_run_info_tts_result__run_id__get
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/RunIDParam'
            description: >-
              The unique identifier for the run, which was generated during the
              Text-to-Speech creation process and returned upon task completion.
        - name: output_type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/OutputType'
            default: raw_bytes
            title: Format Type
          description: >-
            The type of the Text-to-Speech output to return. Either streamable
            audio bytes or a URL to the generated file.
      responses:
        '200':
          description: Successful Response
          content:
            audio/flac:
              schema:
                $ref: '#/components/schemas/AudioBytesResponse'
                description: >-
                  The generated audio file bytes in FLAC format, representing
                  the speech created from the Text-to-Speech task.
            application/json:
              schema:
                $ref: '#/components/schemas/AudioOutputFileURLResponse'
                description: >-
                  A JSON that contains a presigned URL for the generated speech
                  FLAC audio file.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    RunIDParam:
      type: integer
      title: Run ID
      description: >-
        The unique identifier for the run, which was generated during the
        creation process and returned upon task completion.
    OutputType:
      type: string
      enum:
        - raw_bytes
        - file_url
      default: raw_bytes
      title: Output Type
    AudioBytesResponse:
      type: string
      contentEncoding: base64
      title: Audio Bytes Response
    AudioOutputFileURLResponse:
      type: object
      properties:
        output_url:
          title: Output URL
          type: string
          description: A presigned URL that points to the output audio file.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The `x-api-key` is a custom header required for authenticating requests
        to our API. Include this header in your request with the appropriate API
        key value to securely access our endpoints. You can find your API key(s)
        in the 'API' section of our studio website.

````