Get Translated Story Status

Monitor the progress of your story translation tasks with our dedicated status tracking endpoint. This essential companion to our translation service lets you check on your story’s transformation journey in real-time, providing detailed information about which stage of the process your content has reached. By polling this endpoint, you can keep track of your translation progress and detect any issues that might arise during processing.

This endpoint works in conjunction with the /translated-story/{run_id} endpoint, which initiates the translation process and provides the task_id needed for status checks.

​

Understanding the Translation Pipeline

When you request a story translation, your content moves through several processing stages before completion. The status endpoint provides visibility into this journey, allowing you to:

1. Confirm your translation request was successfully received and is being processed
2. Monitor the progress as your story moves through different translation stages
3. Identify when the translation is complete and ready for use
4. Quickly detect and respond to any issues that might occur during processing

Having this level of insight helps you integrate story translations into your applications more effectively, allowing you to provide accurate progress updates to your users and plan subsequent workflows accordingly.

​

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_translation_status(task_id):
    """
    Polls the status endpoint to track a story translation task's progress.
    Continues checking until the task reaches a terminal state.

    Parameters:
    - task_id: The unique identifier returned when the translation request was submitted

    Returns:
    - The final status data when a terminal state is reached, or None if an error occurs
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    # Define the possible final states of a translation task
    terminal_states = ["SUCCESS", "ERROR", "TIMEOUT", "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/translated-story/{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 progress information
            print(f"Status: {current_status}")

            # Handle different status states
            if current_status == "SUCCESS":
                print("Translation completed successfully!")
                print(f"Translated story URL: {status_data.get('story_url')}")
                return status_data

            elif current_status == "ERROR":
                print(f"Translation failed: {status_data.get('error_message')}")
                return status_data

            elif current_status == "TIMEOUT":
                print("Translation process timed out")
                return status_data

            elif current_status == "PAYMENT_REQUIRED":
                print("Additional payment is required to complete this translation")
                return status_data

            elif current_status == "PENDING":
                # Task is still in progress, wait before checking again
                print("Translation in progress...")
                if status_data.get('progress'):
                    print(f"Progress: {status_data.get('progress')}%")
                if status_data.get('current_stage'):
                    print(f"Current stage: {status_data.get('current_stage')}")

                # Wait before next check to avoid excessive requests
                time.sleep(30)  # Poll every 30 seconds

            else:
                # Unexpected status, wait and try again
                print(f"Received status: {current_status}")
                time.sleep(30)

        except requests.exceptions.RequestException as e:
            print(f"Error checking translation status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")
            return None

    return status_data

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

​

Best Practices for Status Monitoring

To efficiently track your translation 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 Possible States: Ensure your code properly handles each possible status response, including unexpected values. This makes your integration robust against future API enhancements.

3. Set Reasonable Timeouts: For longer stories, translation may take significant time. Implement appropriate overall timeout periods based on the typical length of your content.

4. Persist Task IDs: Store task IDs securely in your database so you can resume status checking even if your application restarts or a user returns later.

5. Provide Meaningful Feedback: Translate technical status information into user-friendly messages that set appropriate expectations about completion time and next steps.

​

Troubleshooting Common Issues

If you encounter difficulties while checking translation status, consider these common solutions:

1. Invalid Task ID: Verify the task ID was correctly stored and passed to the status endpoint. Task IDs are case-sensitive and must be used exactly as provided.

2. Authentication Problems: Ensure your API key is valid and correctly included in the request headers.

3. Network Connectivity: Implement proper error handling for network issues that might interrupt status checking, including automatic retry logic.

4. Unexpected Terminal States: If a translation ends with an error status, examine the error message for specific issues that might be addressed in subsequent translation attempts.

By properly integrating status checking into your application, you can create a seamless translation experience that keeps your users informed throughout the entire process, building confidence in your service and ensuring the timely delivery of translated content.