How Tasks & Runs Work

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

1. Submit a Request

   Send your data (text, audio, video) to a creation endpoint. The API immediately returns a task_id.

2. Poll for Status

   Use the task_id to check progress. The task moves through states: PENDING → SUCCESS (or ERROR).

3. Get the Result

   Once the status is SUCCESS, you receive a run_id. Use this to download your result.

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:

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

Use appropriate intervals

Start with 2-5 second intervals. Shorter tasks (TTS) complete faster than longer ones (dubbing).

Implement exponential backoff

For longer tasks, increase the polling interval over time to reduce API calls.

Set a maximum timeout

Don’t poll forever. Set a maximum wait time and handle timeouts gracefully.

Handle all status types

Always handle ERROR, TIMEOUT, and PAYMENT_REQUIRED statuses in your code.

Bulk Operations

For processing multiple items, use the bulk fetch endpoints:

# 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

SDK Guide

SDKs handle polling automatically

API Reference

Explore all endpoints