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() 方法集成了文件上传与任务初始化。提交任务时需二选一提供 file_path（本地文件）或 url（YouTube/TikTok/X/Bilibili/Google Drive/抖音公共链接），并可通过可选参数自定义处理流程。

file_path 与 url 互斥（必须且只能提供一个）。使用 file_path 创建任务时，源视频时长不能超过 45 分钟；使用 url 创建任务时，源视频时长不能超过 15 分钟（900 秒）。

进阶用法

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

参数	类型	必填	说明
file_path	str	条件必填	本地视频文件路径。与 url 互斥。源视频时长需 <= 45 分钟。
url	str	条件必填	公开视频链接（YouTube/TikTok/X/Bilibili/Google Drive/抖音）。与 file_path 互斥。URL 源视频时长需 <= 15 分钟。
target_lang	str	是	目标语言代码 (BCP-47)。
source_lang	str	否	源语言代码，默认为 "auto" 自动识别。
task_name	str	否	方便内部追踪的任务名称。
add_subtitle	bool	否	是否添加字幕（默认为 True）。
erase_original_subtitle	bool	否	是否擦除原视频中已硬编码的源字幕（默认为 False）。
remove_cutrix_logo	bool	否	是否去除平台水印（默认为 True）。
remove_background_audio	bool	否	是否移除原视频中的背景音轨（默认为 False）。

支持的语言列表

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

支持的源语言 (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	葡萄牙语
ro	罗马尼亚语
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	任务正在处理中
downloading	正在下载并准备源视频素材
succeed	翻译已成功完成，可读取 output_video_path
failed	任务处理失败，请查看 failed_code

get_task() 输出字段

字段	类型	说明
ok	bool	请求是否成功
id / task_id	int	任务唯一标识
status	str \| None	当前任务状态
type	str \| None	任务类型，例如 one_click
url	str \| None	使用 url 创建任务时的原始来源链接
output_video_path	str	成功后返回译制视频下载地址
input_video_path	str	原始上传视频地址
input_video_jpg	str \| None	源视频预览图地址
srt_file	str \| None	译制字幕文件（.srt）下载地址
source_lang	str \| None	检测到或手动指定的源语言
target_lang	str \| None	目标语言
input_video_duration	float \| None	原始视频时长（秒）
name	str \| None	任务名称
remove_background_audio	bool \| None	该任务是否启用了背景音去除
failed_code	int \| str \| None	status 为 failed 时的错误码
failed_message	str \| None	SDK 对已知失败码提供的人类可读错误信息
created_at	datetime \| None	任务创建时间（UTC）
estimate_finish_time	datetime \| None	预计完成时间（UTC）
finished_at	datetime \| None	实际完成时间（UTC）

常见错误码 (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}")