Get Text-to-Speech Task Status

GET

tts

{task_id}

Get Tts Result

curl --request GET \
  --url https://client.camb.ai/apis/tts/{task_id} \
  --header 'x-api-key: <api-key>'

import requests

url = "https://client.camb.ai/apis/tts/{task_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/tts/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

{
  "run_id": 123
}

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

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.

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 and retry the request.

Example Code

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} endpoint to download your finished audio file and put it to work in your application.

Authorizations

x-api-key

string

header

required

The x-api-key is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website.

Path Parameters

task_id

string

required

A unique identifier for the task. This is used to query the status of the text to speech task that is running. It is returned when a create request is made for a text to speech.

Response

Successful Response

status

enum<string>

Available options:

SUCCESS,

PENDING,

TIMEOUT,

ERROR,

PAYMENT_REQUIRED

run_id

integer | null

Last modified on May 12, 2026

Get Text-to-Speech ResultRetrieves the result of a specific Text-to-Speech run using the provided `run_id`.

Get Tts Result

curl --request GET \
  --url https://client.camb.ai/apis/tts/{task_id} \
  --header 'x-api-key: <api-key>'

import requests

url = "https://client.camb.ai/apis/tts/{task_id}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/tts/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

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

curl_close($curl);

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

{
  "run_id": 123
}

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

Getting Started

Models

Tutorials

SDK Guides

Hosting Platforms

Integrations

API Reference

Other Products

Release Logs

Get Text-to-Speech Task Status

How to Use This Endpoint

Understanding the Response

Status Types Explained

Example Code

Next Steps

Authorizations

Path Parameters

Response

​How to Use This Endpoint

​Understanding the Response

​Status Types Explained

​Example Code

​Next Steps

Authorizations

Path Parameters

Response

How to Use This Endpoint

Understanding the Response

Status Types Explained

Example Code

Next Steps