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

Monitor the progress of your format conversion tasks with our dedicated status tracking endpoint. This essential companion to our format conversion service lets you check on your media transformation in real-time, providing status information about your content conversion process. By polling this endpoint, you can keep track of your format conversion progress and detect any issues that might arise during processing.

This endpoint works in conjunction with the format conversion functionality of our dubbing service, which provides the task_id needed for status checks when requesting alternative output formats.

​
Understanding Status Values

The endpoint returns one of these status values:

  • SUCCESS: The format conversion task has completed successfully
  • PENDING: The format conversion task is still in progress
  • TIMEOUT: The format conversion task has timed out
  • ERROR: The format conversion task encountered an error
  • PAYMENT_REQUIRED: Additional payment is needed to complete the task

​
Implementing Status Checking

Here’s how to implement status checking in your application using Python:

import requests
import json
import time

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json"
}

def check_format_conversion_status(task_id):
    """
    Polls the status endpoint to track a format conversion task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None
        
    # Define terminal states based on the API specification
    terminal_states = ["SUCCESS", "TIMEOUT", "ERROR", "PAYMENT_REQUIRED"]
    current_status = None
    
    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/dub-alt-format/{task_id}",
                headers=headers
            )
            
            # Verify the request was successful
            response.raise_for_status()
            
            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")
            
            # Display current status information
            print(f"Status: {current_status}")
            
            # Handle success state
            if current_status == "SUCCESS":
                print("Format conversion task completed successfully!")
                print(f"Result URL: {status_data.get('result_url')}")
                return status_data
                
            # Handle error states
            if current_status == "ERROR":
                print(f"Format conversion task failed: {status_data.get('error_message')}")
                return status_data
                
            # Handle timeout state
            if current_status == "TIMEOUT":
                print("Format conversion task timed out")
                return status_data
                
            # Handle payment required state
            if current_status == "PAYMENT_REQUIRED":
                print("Additional payment is required to complete this task")
                return status_data
                
            # If still pending, wait before next check
            if current_status == "PENDING":
                print("Task is still in progress")
                # Wait before next check to avoid excessive requests
                time.sleep(10)  # Poll every 10 seconds
            
        except requests.exceptions.RequestException as e:
            print(f"Error checking format conversion status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")
            return None
            
    return None

# Example usage with a task_id from a previous format conversion request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_format_conversion_status(task_id)

​
Best Practices for Status Monitoring

To efficiently track your format conversion tasks, consider these professional recommendations:

  1. Implement Exponential Backoff: Start with frequent checks that gradually increase in interval to avoid overloading the API. For example, begin with a 5-second interval, then double it each time until you reach a maximum of 2 minutes between checks.

  2. Handle All Status Codes: Ensure your implementation has specific handling for each possible status value (SUCCESS, PENDING, TIMEOUT, ERROR, and PAYMENT_REQUIRED).

  3. Graceful Error Recovery: If the format conversion fails, implement logic to retry the operation or provide clear feedback to users about the next steps they should take.

  4. User Interface Integration: Present status updates in a user-friendly way, such as progress indicators or status messages that translate the technical status codes into more accessible language.

  5. Event Logging: Maintain a detailed log of all status changes to help with troubleshooting if issues arise during the conversion process.

By properly integrating status checking into your application, you can create a seamless media conversion experience that keeps your users informed throughout the entire process and handles both successful and unsuccessful outcomes appropriately.

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

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 enum<string>.

Available options:
SUCCESS,
PENDING,
TIMEOUT,
ERROR,
PAYMENT_REQUIRED