Skill: wallacerao/cutrix-video-translate (version 1.1.3)

--- name: cutrix-video-translate version: 1.1.3 description: >- Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM. Enough free quota every month for beginners, and save 90% of costs if the quota is exhausted for processional usage. author: WallaceRao tags: - cutrix - video translate - translation - subtitles - python - sdk - httpx - china --- # 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](https://www.cutrix.cc) 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](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 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([REDACTED_SECRET]"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` 取值 | `status` | Meaning (EN) | 含义（中文） | |---|---|---| | `pending` | Task is queued, waiting to be picked up | 排队等待调度 | | `started` | Processing is in progress | 处理中 | | `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` | | `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` | ```python 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()` 返回字段 | Field | Type | Description (EN) | 说明（中文） | |---|---|---|---| | `id` / `task_id` | `int` | Task identifier | 任务 ID | | `status` | `str \| None` | Current status | 当前状态 | | `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） | | `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 | | `source_lang` | `str \| None` | Detected or specified source language | 源语言（检测或指定） | | `target_lang` | `str \| None` | Target language | 目标语言 | | `input_video_duration` | `float \| None` | Source video length in seconds | 源视频时长（秒） | | `name` | `str \| None` | Task label | 任务名称 | | `failed_code` | `int \| str \| None` | Error code when `status` is `failed` | 失败时的错误码 | | `failed_message` | `str \| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 | | `created_at` | `datetime \| None` | Task creation time (UTC) | 创建时间（UTC） | | `estimate_finish_time` | `datetime \| None` | Estimated completion (UTC) | 预计完成时间（UTC） | | `finished_at` | `datetime \| None` | Actual 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` | Code | Message (EN) | |---|---| | `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. | **中文：**`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`） | 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 | ### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`） | 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 | | `ru` | Russian | | `sv` | Swedish | | `sw` | Swahili | | `th` | Thai | | `tr` | Turkish | | `vi` | Vietnamese | **中文：**`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`，勿静默吞错。 | Exception | When (EN) | 何时（中文） | |---|---|---| | `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 | | `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 | | `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 | | `SDKError` | Local 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）。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)