Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能#

English: This skill teaches agents to use the official SDK correctly in Python (PyPI: cutrix-video-translate-sdk, import package: cutrix) for Cutrix video translation, dubbing, and subtitles. Do not re-implement HTTP in the skill folder; always call the published SDK.

**中文：**本技能指导代理在 Python 中正确使用官方 SDK（PyPI： cutrix-video-translate-sdk，导入包名： cutrix），对接 Cutrix 的视频翻译 / 配音 / 字幕能力。 不要 在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。

When to apply / 何时启用#

English: Load and follow this skill when:

• The user mentions Video translate, free video translate, HeyGen, voice clone video translate, Cutrix, cutrix.cc, cutrix-video-translate-sdk, or from cutrix import Client
• You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters
• The user works inside a domestic assistant (e.g. WorkBuddy / “小龙虾” ecosystems) that supports SKILL.md-based skill packs—this directory can be the skill root as-is

**中文：**在以下情况应加载并遵守本技能：

• 用户提到 视频翻译， 语音克隆视频翻译， 免费视频翻译， heygen, Cutrix、 cutrix.cc、 cutrix-video-translate-sdk 或 from cutrix import Client
• 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数
• 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 SKILL.md 的技能包，本目录可直接作为技能根目录使用

English: Features：

• Cutrix keeps the original timbre and emotion with advanced voice clone LLM,
• Spread your video into multi languages with just one submit.
• 10 minutes of free quota per month
• Saving 90% of costs if the quota is exhausted

中文: 特性

• 使用最先进语音大模型，完美保留原声音色和情绪
• 提交后不管，无需手动干预
• 每月10分钟免费翻译
• 免费额度用尽后也可节约90%费用

Environment & secrets / 环境与密钥#

English:

• Python: 3.9+
• Install: pip install cutrix-video-translate-sdk (or pip install -r requirements.txt)
• Secrets: Obtain an API key from the Cutrix console; never hard-code keys in repos or skill prose. Prefer the CUTRIX_API_KEY env var (see .env.example)

中文：

• **Python：**3.9+
• 安装： pip install cutrix-video-translate-sdk（或 pip install -r requirements.txt）
• **密钥：**在 Cutrix 控制台获取 API Key； 禁止 硬编码进仓库或技能正文。优先使用环境变量 CUTRIX_API_KEY（见 .env.example）

python

import os
from cutrix import Client

client = Client(api_key=os.environ["CUTRIX_API_KEY"])

API: translate() (local file) / 接口： translate()（本地文件）#

English: Primary method: client.video.translate(...). Required: file_path (local path), target_lang. Optional: source_lang (default "auto"), task_name, add_subtitle, erase_original_subtitle, remove_cutrix_logo, progress_callback (upload progress 0–100). Returns immediately with task_id; processing is asynchronous—poll with get_task().

**中文：**主入口： client.video.translate(...)。**必填：**本地 file_path、 target_lang。 可选： source_lang（默认 "auto"）、 task_name、 add_subtitle、 erase_original_subtitle、 remove_cutrix_logo、 progress_callback（上传进度 0–100）。调用后立即返回 task_id；实际处理在服务端异步进行，需用 get_task() 轮询。

python

from cutrix import Client

with Client(api_key="...") as client:
    result = client.video.translate(
        file_path="./demo.mp4",   # required — local file path
        target_lang="zh",          # required — target language code
        source_lang="auto",        # optional — default "auto"
        task_name="my task",       # optional
        add_subtitle=True,         # optional — burn subtitles into output, default True
        erase_original_subtitle=False,  # optional
        remove_cutrix_logo=True,   # optional — maps to API field is_logo
        # progress_callback=on_progress,  # optional — receives upload progress 0-100
    )

    print(result.task_id)                   # int
    print(result.required_minutes)          # int — estimated quota cost
    print(result.video_duration_seconds)    # float — source video duration

Compatibility alias / 兼容别名#

English: client.video.translate_file(...) is a thin alias of translate(...) with the same parameters. The SDK performs the full upload pipeline: init → cloud upload → complete → create task.

中文： client.video.translate_file(...) 与 translate(...) 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。

python

from cutrix import Client

def on_progress(percent: int) -> None:
    print(f"\rupload: {percent}%", end="", flush=True)

with Client(api_key="...") as client:
    result = client.video.translate_file(
        file_path="./demo.mp4",
        target_lang="zh",
        source_lang="auto",
        task_name="local upload demo",
        progress_callback=on_progress,
    )
    print(result.task_id)

API: poll get_task() / 接口：轮询 get_task()#

English: After translate() / translate_file(), poll client.video.get_task(task_id=...) until a terminal status. Success terminal: succeed. Failure terminal: failed.

**中文：**在 translate() / translate_file() 之后，轮询 client.video.get_task(task_id=...) 直至终态。成功终态： succeed；失败终态： failed。

Task status values / 任务 status 取值#

statusMeaning (EN)含义（中文）pendingTask is queued, waiting to be picked up排队等待调度startedProcessing is in progress处理中succeedFinished successfully — output_video_path is available成功完成，可读取 output_video_path``failedTask failed — inspect failed_code / failed_message失败，查看 failed_code / failed_messagepython

import time
from cutrix import Client

SUCCESS = {"succeed"}
FAILURE = {"failed"}

with Client(api_key="...") 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"status: {task.status}")

        if task.status in SUCCESS:
            print("output:", task.output_video_path)
            break
        if task.status in FAILURE:
            print("failed, code:", task.failed_code)
            print("failed, message:", task.failed_message)
            break

        time.sleep(5)

get_task() response fields / get_task() 返回字段#

FieldTypeDescription (EN)说明（中文）id / task_id``intTask identifier任务 IDstatus``str | NoneCurrent status当前状态output_video_path``strDownload URL of translated video (when successful)译后视频下载地址（成功时有值）input_video_path``strURL of the original uploaded video原始上传视频地址source_lang``str | NoneDetected or specified source language源语言（检测或指定）target_lang``str | NoneTarget language目标语言input_video_duration``float | NoneSource video length in seconds源视频时长（秒）name``str | NoneTask label任务名称failed_code``int | str | NoneError code when status is failed失败时的错误码failed_message``str | NoneHuman-readable message for known failed_code已知失败码的可读说明created_at``datetime | NoneTask creation time (UTC)创建时间（UTC）estimate_finish_time``datetime | NoneEstimated completion (UTC)预计完成时间（UTC）finished_at``datetime | NoneActual completion (UTC)实际完成时间（UTC）

English: get_task() applies a soft rate limit of about 1 call/second per Client instance to avoid accidental hot-loop polling.

中文： get_task() 对 每个 Client 实例 有约 1 次/秒 的软限流，避免无意中的高频轮询。

Known failed_code values / 已知 failed_code#

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

中文： 2001 自动语种识别失败，请改手动 source_lang； 2002 无音频轨； 2003 无视频轨； 2004 未知错误； 2005 源语种与目标语种相同。

python

from cutrix import FAILED_CODE_MESSAGES

print(FAILED_CODE_MESSAGES["2002"])

Language codes (aligned with repo README.md) / 语言代码（与仓库 README.md 一致）#

English: At runtime, prefer SOURCE_LANGUAGES and TARGET_LANGUAGES as the source of truth. The tables below mirror the public README; if they ever diverge, follow the constants + README in the repository.

**中文：**运行时优先以 SOURCE_LANGUAGES、 TARGET_LANGUAGES 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。

python

from cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES

print(sorted(SOURCE_LANGUAGES))
print(sorted(TARGET_LANGUAGES))

Supported source languages ( source_lang) / 支持的源语言（ source_lang）#

CodeLanguageautoAuto-detectzhChinese (Mandarin)enEnglishyueCantonesearArabiccsCzechdaDanishdeGermanelGreekesSpanishfaPersianfiFinnishfilFilipinofrFrenchhiHindihuHungarianidIndonesianitItalianjaJapanesekoKoreanmkMacedonianmsMalaynlDutchplPolishptPortugueseroRomanianruRussiansvSwedishthThaitrTurkishviVietnamese

Supported target languages ( target_lang) / 支持的目标语言（ target_lang）#

CodeLanguagezhChinese (Mandarin)enEnglisharArabicdaDanishdeGermanelGreekesSpanishfiFinnishfrFrenchheHebrewhiHindiidIndonesianitItalianjaJapanesekoKoreanmsMalaynlDutchnoNorwegianplPolishptPortugueseruRussiansvSwedishswSwahilithThaitrTurkishviVietnamese

中文： auto 仅出现在源语言；目标语言表无 auto。向 API 传参时使用上表中的 code 字符串。

Error model / 错误模型#

English: All SDK errors inherit from SDKError. HTTP errors inherit from APIError. Map 401 → AuthenticationError, 429 → RateLimitError. Use try/except in examples; do not swallow errors.

**中文：**异常基类为 SDKError；HTTP 相关为 APIError。401 映射 AuthenticationError，429 映射 RateLimitError。示例代码应使用 try/except，勿静默吞错。

ExceptionWhen (EN)何时（中文）AuthenticationErrorHTTP 401 — invalid or missing API key密钥无效或未提供RateLimitErrorHTTP 429 — too many requests请求过于频繁APIErrorOther HTTP errors or non-zero API code其他 HTTP 错误或业务 code 非 0SDKErrorLocal errors (e.g. file not found, missing dependency)本地错误（如文件不存在、缺依赖）

APIError attributes: message (str), status_code (int | None), raw_response (any).

python

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

with Client(api_key="...") as client:
    try:
        result = client.video.translate(
            file_path="./demo.mp4",
            target_lang="zh",
        )
    except AuthenticationError:
        print("Invalid API key")
    except RateLimitError:
        print("Rate limit hit — slow down")
    except APIError as e:
        print(f"API error {e.status_code}: {e.message}")
    except SDKError as e:
        print(f"SDK error: {e}")

Advanced Client options (optional) / 高级 Client 选项（可选）#

English: Defaults: base_url="https://www.cutrix.cc/v1", timeout=30.0. You may pass custom headers or an httpx.Client via http_client for proxies/pooling/retries.

**中文：**默认 base_url="https://www.cutrix.cc/v1"， timeout=30.0。可传额外 headers，或通过 http_client 注入自定义 httpx.Client 以配置代理、连接池、重试等。

python

from cutrix import Client

client = Client(
    api_key="...",
    base_url="https://www.cutrix.cc/v1",
    timeout=60.0,
    headers={"X-Custom-Header": "value"},
)

Network & dependencies / 网络与依赖#

English: Default install includes httpx, pydantic, and COS upload-related pieces; task creation follows the official upload flow. Do not assume hidden endpoints or fields not documented in README or official docs.

**中文：**默认安装包含 httpx、 pydantic 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。

Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）#

English: If the product uses a one folder, one skill layout similar to Cursor Agent Skills:

1. Place the entire cutrix-python-sdk folder where the product expects skills (often .cursor/skills/cutrix-python-sdk/—check that product’s docs).
2. Keep SKILL.md at the folder root.
3. Have the user run pip install cutrix-video-translate-sdk or pip install -r requirements.txt in the runtime environment.

To publish to Claw Hub, see clawhub/cutrix-python-sdk/README.md for clawhub validate / clawhub publish; ensure frontmatter author matches your clawhub.ai publisher id before publishing.

**中文：**若目标产品采用与 Cursor Agent Skills 类似的「单目录一技能」结构：

1. 将整个 cutrix-python-sdk 文件夹放到该产品要求的技能根路径（常见为项目内 .cursor/skills/cutrix-python-sdk/，以各产品文档为准）。
2. 保证目录根部存在本文件 SKILL.md。
3. 由用户在运行环境中执行 pip install cutrix-video-translate-sdk 或 pip install -r requirements.txt。

发布到 Claw Hub 时，见仓库内 clawhub/cutrix-python-sdk/README.md 的 clawhub validate / clawhub publish 步骤；发布前确认 frontmatter 的 author 与你在 clawhub.ai 上的发布者 ID 一致。

Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）#

English: Confirms the distribution is installed and import cutrix works; does not call the Cutrix API. Equivalent script: python scripts/check_install.py.

**中文：**仅确认已安装发行包且可 import cutrix， 不 调用 Cutrix API。等价脚本： python scripts/check_install.py。

python

from __future__ import annotations

import importlib.metadata

def execute() -> dict[str, object]:
    import cutrix  # noqa: F401

    try:
        dist_ver = importlib.metadata.version("cutrix-video-translate-sdk")
    except importlib.metadata.PackageNotFoundError:
        dist_ver = "unknown"
    return {"import_ok": True, "distribution_version": dist_ver}

Canonical docs / 权威文档#

English:

• Repository root README.md: authoritative install, parameters, polling, language lists, and edge notes
• docs/ARCHITECTURE.md: data flow Client → VideoResource → _http

Keep answers aligned with those sources. Skill semver ( version in this file) is independent from the PyPI SDK version—bump requirements.txt pins and this version separately when releasing.

中文：

• 本仓库根目录 README.md：安装、参数、轮询、语言表与边界说明的权威来源
• docs/ARCHITECTURE.md： Client → VideoResource → _http 数据流

回答用户时应与上述文档保持一致；本文件中的技能 version 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 requirements.txt 与技能 version（semver）。