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）

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() 轮询。

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 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。

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 取值

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() 返回字段

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

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

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 为准。

from cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES

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

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

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

中文：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，勿静默吞错。

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

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 以配置代理、连接池、重试等。

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。

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）。