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-sdkAPI 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. Submit either a local file_path or a public url (YouTube/TikTok/Bilibili), and customize the task with optional parameters.
!
file_path and url are mutually exclusive (provide exactly one). For file_path tasks, source video duration must not exceed 45 minutes. For URL-based tasks, source video duration must not exceed 15 minutes (900 seconds).Advanced usage
python
from cutrix import Client
with Client(api_key="sk-...") as client:
result = client.video.translate(
# file_path="./demo.mp4", # choose one: file_path or url
url="https://www.youtube.com/watch?v=example",
target_lang="zh",
source_lang="en",
task_name="Campaign Video V1",
add_subtitle=True,
erase_original_subtitle=False,
remove_cutrix_logo=True,
remove_background_audio=False
)
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 | Conditional | Path to your local video file. Mutually exclusive with url. Source duration must be <= 45 minutes. |
| url | str | Conditional | Public video URL (YouTube/TikTok/Bilibili). Mutually exclusive with file_path. URL source must be <= 15 minutes. |
| 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). |
| erase_original_subtitle | bool | No | Erase hard-coded source subtitles in the original video (Default: False). |
| remove_cutrix_logo | bool | No | Remove platform branding (Default: True). |
| remove_background_audio | bool | No | Remove original background audio from the source video (Default: False). |
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 |
| ro | Romanian |
| 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 secondsget_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 |
| downloading | Source media is being downloaded and prepared |
| succeed | Translation finished successfully. output_video_path is available |
| failed | Task failed. Check failed_code for the reason |
get_task() response fields
| Field | Type | Description |
|---|---|---|
| ok | bool | Whether the request is successful |
| id / task_id | int | Task identifier |
| status | str | None | Current status |
| type | str | None | Task type, such as one_click |
| url | str | None | Original source URL when created from url |
| output_video_path | str | Download URL of the translated video when successful |
| input_video_path | str | URL of the original uploaded video |
| input_video_jpg | str | None | Preview image URL for the source video |
| srt_file | str | None | Download URL of translated subtitle file (.srt) |
| source_lang | str | None | Detected or explicitly specified source language |
| target_lang | str | None | Target language |
| input_video_duration | float | None | Source video length in seconds |
| name | str | None | Task label |
| remove_background_audio | bool | None | Whether background audio removal is enabled for this task |
| failed_code | int | str | None | Error code when status is failed |
| failed_message | str | None | SDK-provided human-readable message for known failure codes |
| created_at | datetime | None | Task creation time in UTC |
| estimate_finish_time | datetime | None | Estimated completion time in UTC |
| finished_at | datetime | None | Actual completion time in UTC |
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}")