Cutrix Python SDK

The official Python SDK for the Cutrix AI video platform. Translate, dub, and subtitle videos with a few lines of Python code.

Start translating in minutes

Use the Client class to interact with the Cutrix API. This minimal example shows how to submit a local video for translation.

Minimal example

python

from cutrix import Client

with Client(api_key="sk-...") as client:
    result = client.video.translate(
        file_path="./demo.mp4",
        target_lang="zh",
    )
    print(f"Task ID: {result.task_id}")

System requirements

Ensure your development environment meets the following prerequisites.

Python 3.9+
A Cutrix API key (obtainable from the user dashboard). Go to get →
Only videos up to 45 minutes are currently supported.
pip (Python package installer)

Install the SDK

Install the official package from PyPI using pip.

Terminal

bash

pip install cutrix-video-translate-sdk

API Key authentication

Authenticate your requests by passing your API key when initializing the client. Get API Key →

Initialization

python

import os
from cutrix import Client

# Option 1: Direct initialization
client = Client(api_key="sk-...")

# Option 2: Using environment variables (Recommended)
client = Client(api_key=os.environ.get("CUTRIX_API_KEY"))

Submit a translation job

The translate() method handles file uploading and task initialization. You can customize the process with various parameters.

Only videos up to 45 minutes are currently supported. Longer files should be split before submission.

Advanced usage

python

from cutrix import Client

with Client(api_key="sk-...") as client:
    result = client.video.translate(
        file_path="./demo.mp4",
        target_lang="zh",
        source_lang="en",
        task_name="Campaign Video V1",
        add_subtitle=True,
        remove_cutrix_logo=True
    )

    print(f"Task created: {result.task_id}")
    print(f"Estimated duration: {result.video_duration_seconds}s")

translate() parameters

Parameter	Type	Required	Description
file_path	str	Yes	Path to your local video file.
target_lang	str	Yes	Target language code (BCP-47).
source_lang	str	No	Defaults to "auto" detection.
task_name	str	No	Label for internal tracking.
add_subtitle	bool	No	Whether to add subtitles (Default: True).
remove_cutrix_logo	bool	No	Remove platform branding (Default: True).

Supported languages

Check the lists below for all supported source and target language codes.

Source languages

Code	Language
auto	Auto-detect
zh	Chinese (Mandarin)
en	English
yue	Cantonese
ar	Arabic
cs	Czech
da	Danish
de	German
el	Greek
es	Spanish
fa	Persian
fi	Finnish
fil	Filipino
fr	French
hi	Hindi
hu	Hungarian
id	Indonesian
it	Italian
ja	Japanese
ko	Korean
mk	Macedonian
ms	Malay
nl	Dutch
pl	Polish
pt	Portuguese
ro	Romanian
ru	Russian
sv	Swedish
th	Thai
tr	Turkish
vi	Vietnamese

Target languages

Code	Language
zh	Chinese (Mandarin)
en	English
ar	Arabic
da	Danish
de	German
el	Greek
es	Spanish
fi	Finnish
fr	French
he	Hebrew
hi	Hindi
id	Indonesian
it	Italian
ja	Japanese
ko	Korean
ms	Malay
nl	Dutch
no	Norwegian
pl	Polish
pt	Portuguese
ru	Russian
sv	Swedish
sw	Swahili
th	Thai
tr	Turkish
vi	Vietnamese

Monitor task status

Since video processing is asynchronous, you must poll the get_task() method to determine when the processing is complete.

Polling implementation

python

import time
from cutrix import Client

with Client(api_key="sk-...") as client:
    result = client.video.translate(file_path="./demo.mp4", target_lang="zh")
    
    while True:
        task = client.video.get_task(task_id=result.task_id)
        print(f"Current Status: {task.status}")

        if task.status == "succeed":
            print(f"Download URL: {task.output_video_path}")
            break
        elif task.status == "failed":
            print(f"Error: {task.failed_message}")
            break
            
        time.sleep(30) # Poll every 30 seconds

get_task() parameters

Parameter	Type	Required	Description
task_id	int \| str	Yes	Unique identifier returned by translate().

Task status codes

status	Description
pending	Task is queued, waiting to be picked up
started	Processing is in progress
succeed	Translation finished successfully. output_video_path is available
failed	Task failed. Check failed_code for the reason

Failure error codes

Code	Reason
2001	Automatic language detection failed. Please select the source language manually and try again.
2002	No audio was detected. Please make sure the video contains an audio track.
2003	No video was detected. Please make sure the file contains video content.
2004	Unknown error. Please try again later or contact support.
2005	The source and target languages are the same, so translation is not needed.

Exception handling

Handle API and SDK exceptions to ensure your integration is robust.

Error handling

python

from cutrix import Client, AuthenticationError, RateLimitError
from cutrix.exceptions import APIError, SDKError

try:
    with Client(api_key="sk-...") as client:
        # API calls...
        pass
except AuthenticationError:
    print("Invalid API Key.")
except RateLimitError:
    print("Request limit exceeded.")
except APIError as e:
    print(f"API Exception: {e.message} (Status: {e.status_code})")
except SDKError as e:
    print(f"Local SDK Error: {e}")