Get Story Task Status

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 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:

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:

Implement Exponential Backoff: Start with frequent checks that gradually increase in interval to avoid overloading the API.
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.

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 story task that is running. It is returned when a create request is made for a story.

Response

Successful Response

status

enum<string>

Available options:

SUCCESS,

PENDING,

TIMEOUT,

ERROR,

PAYMENT_REQUIRED

run_id

integer | null

Documentation Index

​Checking Your Story Status

​Best Practices for Status Monitoring

Authorizations

Path Parameters

Response

Checking Your Story Status

Best Practices for Status Monitoring