GET
/
tts
/
{id}
curl --request GET \
  --url https://client.camb.ai/apis/tts/{id} \
  --header 'x-api-key: <api-key>'
{
  "status": "SUCCESS",
  "run_id": 123
}

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:

StatusDescriptionNext Step
SUCCESSYour audio generation has completed successfullyUse the run_id to download your finished audio
PENDINGYour task is currently being processed by our system.Continue polling until completion.
TIMEOUTThe processing time exceeded the allowed limit.Consider breaking text into smaller segments.
ERRORSomething went wrong during processing.Check error details and try submitting again.
PAYMENT_REQUIREDYour 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 = "abc123xyz"  # 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

​
id
string
required

This parameter represents a unique identifier for a task. It is used in various API endpoints to query the status or result of a specific task. The task_id is typically returned when a task is created.

Response

200
application/json

Successful Response

The response is of type object.