Cutrix Python SDK

Cutrix AI 视频平台官方 Python SDK。用几行 Python 代码即可完成视频翻译、配音与字幕处理。

快速创建翻译任务

使用 Client 类即可与 Cutrix API 进行交互。以下示例展示了如何提交本地视频进行翻译。

最小示例

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}")

运行环境要求

在开始集成前，请确保您的开发环境符合以下要求。

Python 3.9+
有效的 Cutrix API Key（可在用户控制台中获取）。前往获取 →
当前仅支持 45 分钟以内的视频。
pip (Python package installer)

安装 SDK

通过 pip 从 PyPI 安装官方提供的 SDK 包。

终端命令

bash

pip install cutrix-video-translate-sdk

API Key 鉴权

在初始化 Client 时传入 API Key。为了安全性，建议从环境变量中读取密钥。立即获取 →

初始化示例

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"))

提交翻译任务

translate() 方法集成了文件上传与任务初始化。您可以通过以下参数自定义处理流程。

当前仅支持 45 分钟以内的视频。超过时长的文件建议先拆分后再提交。

进阶用法

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() 参数说明

参数	类型	必填	说明
file_path	str	是	本地视频文件路径。
target_lang	str	是	目标语言代码 (BCP-47)。
source_lang	str	否	源语言代码，默认为 "auto" 自动识别。
task_name	str	否	方便内部追踪的任务名称。
add_subtitle	bool	否	是否添加字幕（默认为 True）。
remove_cutrix_logo	bool	否	是否去除平台水印（默认为 True）。

支持的语言列表

以下是当前支持的源语言和目标语言代码列表。

支持的源语言 (source_lang)

代码	语言
auto	自动检测
zh	中文（普通话）
en	英语
yue	粤语
ar	阿拉伯语
cs	捷克语
da	丹麦语
de	德语
el	希腊语
es	西班牙语
fa	波斯语
fi	芬兰语
fil	菲律宾语
fr	法语
hi	印地语
hu	匈牙利语
id	印度尼西亚语
it	意大利语
ja	日语
ko	韩语
mk	马其顿语
ms	马来语
nl	荷兰语
pl	波兰语
pt	葡萄牙语
ro	罗马尼亚语
ru	俄语
sv	瑞典语
th	泰语
tr	土耳其语
vi	越南语

支持的目标语言 (target_lang)

代码	语言
zh	中文（普通话）
en	英语
ar	阿拉伯语
da	丹麦语
de	德语
el	希腊语
es	西班牙语
fi	芬兰语
fr	法语
he	希伯来语
hi	印地语
id	印度尼西亚语
it	意大利语
ja	日语
ko	韩语
ms	马来语
nl	荷兰语
no	挪威语
pl	波兰语
pt	葡萄牙语
ru	俄语
sv	瑞典语
sw	斯瓦希里语
th	泰语
tr	土耳其语
vi	越南语

任务状态监控

由于视频处理是异步的，您需要调用 get_task() 方法来获取最新状态，直到任务完成。

轮询实现示例

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() 参数说明

参数	类型	必填	说明
task_id	int \| str	是	由 translate() 返回的任务唯一标识。

任务状态说明

status	说明
pending	任务已进入队列，等待开始处理
started	任务正在处理中
succeed	翻译已成功完成，可读取 output_video_path
failed	任务处理失败，请查看 failed_code

常见错误码 (failed_code)

错误码	原因
2001	自动检测源语言失败，请手动指定 source_lang 后重试。
2002	未检测到音频，请确认视频中包含音轨。
2003	未检测到视频内容，请确认文件中包含视频流。
2004	未知错误，请稍后重试或联系支持。
2005	源语言与目标语言相同，无需翻译。

错误与异常处理

通过捕获 API 和 SDK 异常，确保您的集成方案能够稳健地处理各类边缘情况。

异常捕获示例

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}")