{"id":"97e93636-9a30-4b4a-9562-38fefa9c16ee","entityType":"agent","slug":"clawhub-wallacerao-cutrix-video-translate","name":"Cutrix Video Translate","canonicalUrl":"https://www.xpersona.co/agent/clawhub-wallacerao-cutrix-video-translate","canonicalPath":"/agent/clawhub-wallacerao-cutrix-video-translate","generatedAt":"2026-10-11T20:59:32.356Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":null},"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,...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17fcw6rfzxghwy6x8ndj0fqs986kxyn:cutrix-video-translate","sourceUrl":"https://clawhub.ai/wallacerao/cutrix-video-translate","homepage":"https://clawhub.ai/wallacerao/skills/cutrix-video-translate","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/wallacerao/cutrix-video-translate","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/wallacerao/skills/cutrix-video-translate","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Cutrix Video Translate technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":null},"stars":null,"forks":null,"downloads":1024,"packageName":null,"latestVersion":"v1.1.4","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:51:33.786Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T16:51:33.883Z","lastCrawledAt":"2026-10-11T16:51:33.786Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T16:51:33.786Z","lastVerifiedAt":null,"highlights":[{"version":"v1.1.4","createdAt":"2026-06-08T01:45:23.564Z","changelog":"优化搜索关键词和描述，提升搜索匹配度","fileCount":6,"zipByteSize":12223},{"version":"1.1.3","createdAt":"2026-05-12T09:23:27.854Z","changelog":"update description","fileCount":6,"zipByteSize":12190},{"version":"1.1.2","createdAt":"2026-05-12T09:17:36.572Z","changelog":"update description","fileCount":5,"zipByteSize":11097},{"version":"1.1.1","createdAt":"2026-05-12T09:15:07.951Z","changelog":"update description","fileCount":5,"zipByteSize":11094},{"version":"1.1.0","createdAt":"2026-05-12T07:15:38.852Z","changelog":"first publish","fileCount":5,"zipByteSize":11100}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17fcw6rfzxghwy6x8ndj0fqs986kxyn:cutrix-video-translate","setupComplexity":"medium","setupSteps":["Install using `clawhub skill install s17fcw6rfzxghwy6x8ndj0fqs986kxyn:cutrix-video-translate` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/wallacerao/cutrix-video-translate before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T20:59:32.353Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-wallacerao-cutrix-video-translate/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":null},"readme":"Skill: Cutrix Video Translate\n\nOwner: wallacerao\n\nSummary: Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM. Enough free quota every month for beginners,...\n\nTags: ai-translation:v1.1.4, dubbing:v1.1.4, latest:v1.1.4, subtitle:v1.1.4, video-translate:v1.1.4, voice-clone:v1.1.4\n\nVersion history:\n\nvv1.1.4 | 2026-06-08T01:45:23.564Z | user\n\n优化搜索关键词和描述，提升搜索匹配度\n\nv1.1.3 | 2026-05-12T09:23:27.854Z | user\n\nupdate description\n\nv1.1.2 | 2026-05-12T09:17:36.572Z | user\n\nupdate description\n\nv1.1.1 | 2026-05-12T09:15:07.951Z | user\n\nupdate description\n\nv1.1.0 | 2026-05-12T07:15:38.852Z | user\n\nfirst publish\n\nArchive index:\n\nArchive vv1.1.4: 6 files, 12223 bytes\n\nFiles: README.md (4322b), requirements.txt (121b), scripts/check_install.py (611b), skill-card.md (2163b), SKILL.md (17971b), _meta.json (142b)\n\nFile vv1.1.4:SKILL.md\n\n---\nname: cutrix-video-translate\nversion: 1.1.3\ndescription: >-\n Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM.\n Enough free quota every month for beginners, and save 90% of costs if the quota is exhausted for processional usage.\n video dubbing、AI subtitle、voice cloning、视频翻译、配音 字幕 声音克隆\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - video translation\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - video translate\n - dubbing\n - subtitle\n - AI translation\n - 视频翻译\n - 视频配音\n - 声音克隆\n - 字幕翻译\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可节约90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接口：`translate()`（本地文件）\n\n**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()`.\n\n**中文：**主入口：`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()` 轮询。\n\n```python\nfrom cutrix import Client\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration\n```\n\n### Compatibility alias / 兼容别名\n\n**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.\n\n**中文：**`client.video.translate_file(...)` 与 `translate(...)` 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。\n\n```python\nfrom cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)\n```\n\n## API: poll `get_task()` / 接口：轮询 `get_task()`\n\n**English:** After `translate()` / `translate_file()`, poll `client.video.get_task(task_id=...)` until a terminal status. Success terminal: `succeed`. Failure terminal: `failed`.\n\n**中文：**在 `translate()` / `translate_file()` 之后，轮询 `client.video.get_task(task_id=...)` 直至终态。成功终态：`succeed`；失败终态：`failed`。\n\n### Task `status` values / 任务 `status` 取值\n\n| `status` | Meaning (EN) | 含义（中文） |\n|---|---|---|\n| `pending` | Task is queued, waiting to be picked up | 排队等待调度 |\n| `started` | Processing is in progress | 处理中 |\n| `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` |\n| `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` |\n\n```python\nimport time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)\n```\n\n### `get_task()` response fields / `get_task()` 返回字段\n\n| Field | Type | Description (EN) | 说明（中文） |\n|---|---|---|---|\n| `id` / `task_id` | `int` | Task identifier | 任务 ID |\n| `status` | `str \\| None` | Current status | 当前状态 |\n| `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） |\n| `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 |\n| `source_lang` | `str \\| None` | Detected or specified source language | 源语言（检测或指定） |\n| `target_lang` | `str \\| None` | Target language | 目标语言 |\n| `input_video_duration` | `float \\| None` | Source video length in seconds | 源视频时长（秒） |\n| `name` | `str \\| None` | Task label | 任务名称 |\n| `failed_code` | `int \\| str \\| None` | Error code when `status` is `failed` | 失败时的错误码 |\n| `failed_message` | `str \\| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 |\n| `created_at` | `datetime \\| None` | Task creation time (UTC) | 创建时间（UTC） |\n| `estimate_finish_time` | `datetime \\| None` | Estimated completion (UTC) | 预计完成时间（UTC） |\n| `finished_at` | `datetime \\| None` | Actual completion (UTC) | 实际完成时间（UTC） |\n\n**English:** `get_task()` applies a **soft rate limit of about 1 call/second per `Client` instance** to avoid accidental hot-loop polling.\n\n**中文：**`get_task()` 对**每个 `Client` 实例**有约 **1 次/秒**的软限流，避免无意中的高频轮询。\n\n### Known `failed_code` values / 已知 `failed_code`\n\n| Code | Message (EN) |\n|---|---|\n| `2001` | Automatic language detection failed. Please select the source language manually and try again. |\n| `2002` | No audio was detected. Please make sure the video contains an audio track. |\n| `2003` | No video was detected. Please make sure the file contains video content. |\n| `2004` | Unknown error. Please try again later or contact support. |\n| `2005` | The source and target languages are the same, so translation is not needed. |\n\n**中文：**`2001` 自动语种识别失败，请改手动 `source_lang`；`2002` 无音频轨；`2003` 无视频轨；`2004` 未知错误；`2005` 源语种与目标语种相同。\n\n```python\nfrom cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])\n```\n\n## Language codes (aligned with repo `README.md`) / 语言代码（与仓库 `README.md` 一致）\n\n**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.\n\n**中文：**运行时优先以 `SOURCE_LANGUAGES`、`TARGET_LANGUAGES` 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。\n\n```python\nfrom cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))\n```\n\n### Supported source languages (`source_lang`) / 支持的源语言（`source_lang`）\n\n| Code | Language |\n|---|---|\n| `auto` | Auto-detect |\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `yue` | Cantonese |\n| `ar` | Arabic |\n| `cs` | Czech |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fa` | Persian |\n| `fi` | Finnish |\n| `fil` | Filipino |\n| `fr` | French |\n| `hi` | Hindi |\n| `hu` | Hungarian |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `mk` | Macedonian |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`）\n\n| Code | Language |\n|---|---|\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `ar` | Arabic |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `he` | Hebrew |\n| `hi` | Hindi |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `no` | Norwegian |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `sw` | Swahili |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n**中文：**`auto` 仅出现在源语言；目标语言表无 `auto`。向 API 传参时使用上表中的 **code** 字符串。\n\n## Error model / 错误模型\n\n**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.\n\n**中文：**异常基类为 `SDKError`；HTTP 相关为 `APIError`。401 映射 `AuthenticationError`，429 映射 `RateLimitError`。示例代码应使用 `try/except`，勿静默吞错。\n\n| Exception | When (EN) | 何时（中文） |\n|---|---|---|\n| `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 |\n| `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 |\n| `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 |\n| `SDKError` | Local errors (e.g. file not found, missing dependency) | 本地错误（如文件不存在、缺依赖） |\n\n`APIError` attributes: `message` (str), `status_code` (int | None), `raw_response` (any).\n\n```python\nfrom cutrix import Client, AuthenticationError, RateLimitError\nfrom cutrix.exceptions import APIError, SDKError\n\nwith Client(api_key=\"...\") as client:\n try:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n except AuthenticationError:\n print(\"Invalid API key\")\n except RateLimitError:\n print(\"Rate limit hit — slow down\")\n except APIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n except SDKError as e:\n print(f\"SDK error: {e}\")\n```\n\n## Advanced `Client` options (optional) / 高级 `Client` 选项（可选）\n\n**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.\n\n**中文：**默认 `base_url=\"https://www.cutrix.cc/v1\"`，`timeout=30.0`。可传额外 `headers`，或通过 `http_client` 注入自定义 `httpx.Client` 以配置代理、连接池、重试等。\n\n```python\nfrom cutrix import Client\n\nclient = Client(\n api_key=\"...\",\n base_url=\"https://www.cutrix.cc/v1\",\n timeout=60.0,\n headers={\"X-Custom-Header\": \"value\"},\n)\n```\n\n## Network & dependencies / 网络与依赖\n\n**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.\n\n**中文：**默认安装包含 `httpx`、`pydantic` 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。\n\n## Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）\n\n**English:** If the product uses a **one folder, one skill** layout similar to **Cursor Agent Skills**:\n\n1. Place the entire `cutrix-python-sdk` folder where the product expects skills (often `.cursor/skills/cutrix-python-sdk/`—check that product’s docs).\n2. Keep `SKILL.md` at the folder root.\n3. Have the user run `pip install cutrix-video-translate-sdk` or `pip install -r requirements.txt` in the runtime environment.\n\nTo 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.\n\n**中文：**若目标产品采用与 **Cursor Agent Skills** 类似的「单目录一技能」结构：\n\n1. 将整个 `cutrix-python-sdk` 文件夹放到该产品要求的技能根路径（常见为项目内 `.cursor/skills/cutrix-python-sdk/`，以各产品文档为准）。\n2. 保证目录根部存在本文件 `SKILL.md`。\n3. 由用户在运行环境中执行 `pip install cutrix-video-translate-sdk` 或 `pip install -r requirements.txt`。\n\n发布到 **Claw Hub** 时，见仓库内 `clawhub/cutrix-python-sdk/README.md` 的 `clawhub validate` / `clawhub publish` 步骤；发布前确认 frontmatter 的 `author` 与你在 clawhub.ai 上的发布者 ID 一致。\n\n## Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）\n\n**English:** Confirms the distribution is installed and `import cutrix` works; **does not** call the Cutrix API. Equivalent script: `python scripts/check_install.py`.\n\n**中文：**仅确认已安装发行包且可 `import cutrix`，**不**调用 Cutrix API。等价脚本：`python scripts/check_install.py`。\n\n```python\nfrom __future__ import annotations\n\nimport importlib.metadata\n\n\ndef execute() -> dict[str, object]:\n import cutrix # noqa: F401\n\n try:\n dist_ver = importlib.metadata.version(\"cutrix-video-translate-sdk\")\n except importlib.metadata.PackageNotFoundError:\n dist_ver = \"unknown\"\n return {\"import_ok\": True, \"distribution_version\": dist_ver}\n```\n\n## Canonical docs / 权威文档\n\n**English:**\n\n- Repository root `README.md`: authoritative install, parameters, polling, language lists, and edge notes\n- `docs/ARCHITECTURE.md`: data flow `Client` → `VideoResource` → `_http`\n\nKeep 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.\n\n**中文：**\n\n- 本仓库根目录 `README.md`：安装、参数、轮询、语言表与边界说明的权威来源\n- `docs/ARCHITECTURE.md`：`Client` → `VideoResource` → `_http` 数据流\n\n回答用户时应与上述文档保持一致；本文件中的技能 `version` 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 `requirements.txt` 与技能 `version`（semver）。\n\nFile vv1.1.4:README.md\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/` at the repo root. This skill only documents how to **install and call** that package from agent-generated code.\n\nFile vv1.1.4:_meta.json\n\n{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"v1.1.4\",\n \"publishedAt\": 1780883123564\n}\n\nFile vv1.1.4:skill-card.md\n\n## Description:\n\nGuides agents to use the Cutrix Python SDK for video translation, dubbing, subtitles, task polling, and API error handling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[wallacerao](https://clawhub.ai/user/wallacerao)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to generate guidance, Python code, installation commands, and configuration for submitting Cutrix video translation tasks, polling task status, and handling subtitle-related parameters.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Selected videos, audio, subtitles, and task metadata may be sent to Cutrix for cloud processing.\n\nMitigation: Use the skill only when that data transfer is acceptable for the user's content and environment.\n\nRisk: API keys and ClawHub tokens can be exposed if copied into code, logs, or shared transcripts.\n\nMitigation: Store secrets outside generated code, prefer environment variables such as CUTRIX_API_KEY, and remove credentials from logs and transcripts.\n\nRisk: The SDK dependency may change over time, which can affect reproducibility or supply-chain controls.\n\nMitigation: In controlled environments, pin and hash-lock the SDK dependency before deployment.\n\n## Reference(s):\n\n- [Cutrix](https://www.cutrix.cc)\n- [Cutrix Video Translate on ClawHub](https://clawhub.ai/wallacerao/skills/cutrix-video-translate)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown with Python and bash code blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include SDK installation steps, environment-variable guidance, task polling patterns, language-code tables, and error-handling examples.]\n\n## Skill Version(s):\n\nv1.1.4 (source: ClawHub release evidence; artifact frontmatter says 1.1.3)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile vv1.1.4:requirements.txt\n\n# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0\n\nArchive v1.1.3: 6 files, 12190 bytes\n\nFiles: README.md (4322b), requirements.txt (121b), scripts/check_install.py (611b), skill-card.md (2263b), SKILL.md (17736b), _meta.json (141b)\n\nFile v1.1.3:SKILL.md\n\n---\nname: cutrix-video-translate\nversion: 1.1.3\ndescription: >-\n Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM.\n Enough free quota every month for beginners, and save 90% of costs if the quota is exhausted for processional usage.\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - china\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可解决90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接口：`translate()`（本地文件）\n\n**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()`.\n\n**中文：**主入口：`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()` 轮询。\n\n```python\nfrom cutrix import Client\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration\n```\n\n### Compatibility alias / 兼容别名\n\n**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.\n\n**中文：**`client.video.translate_file(...)` 与 `translate(...)` 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。\n\n```python\nfrom cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)\n```\n\n## API: poll `get_task()` / 接口：轮询 `get_task()`\n\n**English:** After `translate()` / `translate_file()`, poll `client.video.get_task(task_id=...)` until a terminal status. Success terminal: `succeed`. Failure terminal: `failed`.\n\n**中文：**在 `translate()` / `translate_file()` 之后，轮询 `client.video.get_task(task_id=...)` 直至终态。成功终态：`succeed`；失败终态：`failed`。\n\n### Task `status` values / 任务 `status` 取值\n\n| `status` | Meaning (EN) | 含义（中文） |\n|---|---|---|\n| `pending` | Task is queued, waiting to be picked up | 排队等待调度 |\n| `started` | Processing is in progress | 处理中 |\n| `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` |\n| `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` |\n\n```python\nimport time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)\n```\n\n### `get_task()` response fields / `get_task()` 返回字段\n\n| Field | Type | Description (EN) | 说明（中文） |\n|---|---|---|---|\n| `id` / `task_id` | `int` | Task identifier | 任务 ID |\n| `status` | `str \\| None` | Current status | 当前状态 |\n| `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） |\n| `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 |\n| `source_lang` | `str \\| None` | Detected or specified source language | 源语言（检测或指定） |\n| `target_lang` | `str \\| None` | Target language | 目标语言 |\n| `input_video_duration` | `float \\| None` | Source video length in seconds | 源视频时长（秒） |\n| `name` | `str \\| None` | Task label | 任务名称 |\n| `failed_code` | `int \\| str \\| None` | Error code when `status` is `failed` | 失败时的错误码 |\n| `failed_message` | `str \\| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 |\n| `created_at` | `datetime \\| None` | Task creation time (UTC) | 创建时间（UTC） |\n| `estimate_finish_time` | `datetime \\| None` | Estimated completion (UTC) | 预计完成时间（UTC） |\n| `finished_at` | `datetime \\| None` | Actual completion (UTC) | 实际完成时间（UTC） |\n\n**English:** `get_task()` applies a **soft rate limit of about 1 call/second per `Client` instance** to avoid accidental hot-loop polling.\n\n**中文：**`get_task()` 对**每个 `Client` 实例**有约 **1 次/秒**的软限流，避免无意中的高频轮询。\n\n### Known `failed_code` values / 已知 `failed_code`\n\n| Code | Message (EN) |\n|---|---|\n| `2001` | Automatic language detection failed. Please select the source language manually and try again. |\n| `2002` | No audio was detected. Please make sure the video contains an audio track. |\n| `2003` | No video was detected. Please make sure the file contains video content. |\n| `2004` | Unknown error. Please try again later or contact support. |\n| `2005` | The source and target languages are the same, so translation is not needed. |\n\n**中文：**`2001` 自动语种识别失败，请改手动 `source_lang`；`2002` 无音频轨；`2003` 无视频轨；`2004` 未知错误；`2005` 源语种与目标语种相同。\n\n```python\nfrom cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])\n```\n\n## Language codes (aligned with repo `README.md`) / 语言代码（与仓库 `README.md` 一致）\n\n**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.\n\n**中文：**运行时优先以 `SOURCE_LANGUAGES`、`TARGET_LANGUAGES` 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。\n\n```python\nfrom cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))\n```\n\n### Supported source languages (`source_lang`) / 支持的源语言（`source_lang`）\n\n| Code | Language |\n|---|---|\n| `auto` | Auto-detect |\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `yue` | Cantonese |\n| `ar` | Arabic |\n| `cs` | Czech |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fa` | Persian |\n| `fi` | Finnish |\n| `fil` | Filipino |\n| `fr` | French |\n| `hi` | Hindi |\n| `hu` | Hungarian |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `mk` | Macedonian |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`）\n\n| Code | Language |\n|---|---|\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `ar` | Arabic |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `he` | Hebrew |\n| `hi` | Hindi |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `no` | Norwegian |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `sw` | Swahili |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n**中文：**`auto` 仅出现在源语言；目标语言表无 `auto`。向 API 传参时使用上表中的 **code** 字符串。\n\n## Error model / 错误模型\n\n**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.\n\n**中文：**异常基类为 `SDKError`；HTTP 相关为 `APIError`。401 映射 `AuthenticationError`，429 映射 `RateLimitError`。示例代码应使用 `try/except`，勿静默吞错。\n\n| Exception | When (EN) | 何时（中文） |\n|---|---|---|\n| `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 |\n| `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 |\n| `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 |\n| `SDKError` | Local errors (e.g. file not found, missing dependency) | 本地错误（如文件不存在、缺依赖） |\n\n`APIError` attributes: `message` (str), `status_code` (int | None), `raw_response` (any).\n\n```python\nfrom cutrix import Client, AuthenticationError, RateLimitError\nfrom cutrix.exceptions import APIError, SDKError\n\nwith Client(api_key=\"...\") as client:\n try:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n except AuthenticationError:\n print(\"Invalid API key\")\n except RateLimitError:\n print(\"Rate limit hit — slow down\")\n except APIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n except SDKError as e:\n print(f\"SDK error: {e}\")\n```\n\n## Advanced `Client` options (optional) / 高级 `Client` 选项（可选）\n\n**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.\n\n**中文：**默认 `base_url=\"https://www.cutrix.cc/v1\"`，`timeout=30.0`。可传额外 `headers`，或通过 `http_client` 注入自定义 `httpx.Client` 以配置代理、连接池、重试等。\n\n```python\nfrom cutrix import Client\n\nclient = Client(\n api_key=\"...\",\n base_url=\"https://www.cutrix.cc/v1\",\n timeout=60.0,\n headers={\"X-Custom-Header\": \"value\"},\n)\n```\n\n## Network & dependencies / 网络与依赖\n\n**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.\n\n**中文：**默认安装包含 `httpx`、`pydantic` 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。\n\n## Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）\n\n**English:** If the product uses a **one folder, one skill** layout similar to **Cursor Agent Skills**:\n\n1. Place the entire `cutrix-python-sdk` folder where the product expects skills (often `.cursor/skills/cutrix-python-sdk/`—check that product’s docs).\n2. Keep `SKILL.md` at the folder root.\n3. Have the user run `pip install cutrix-video-translate-sdk` or `pip install -r requirements.txt` in the runtime environment.\n\nTo 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.\n\n**中文：**若目标产品采用与 **Cursor Agent Skills** 类似的「单目录一技能」结构：\n\n1. 将整个 `cutrix-python-sdk` 文件夹放到该产品要求的技能根路径（常见为项目内 `.cursor/skills/cutrix-python-sdk/`，以各产品文档为准）。\n2. 保证目录根部存在本文件 `SKILL.md`。\n3. 由用户在运行环境中执行 `pip install cutrix-video-translate-sdk` 或 `pip install -r requirements.txt`。\n\n发布到 **Claw Hub** 时，见仓库内 `clawhub/cutrix-python-sdk/README.md` 的 `clawhub validate` / `clawhub publish` 步骤；发布前确认 frontmatter 的 `author` 与你在 clawhub.ai 上的发布者 ID 一致。\n\n## Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）\n\n**English:** Confirms the distribution is installed and `import cutrix` works; **does not** call the Cutrix API. Equivalent script: `python scripts/check_install.py`.\n\n**中文：**仅确认已安装发行包且可 `import cutrix`，**不**调用 Cutrix API。等价脚本：`python scripts/check_install.py`。\n\n```python\nfrom __future__ import annotations\n\nimport importlib.metadata\n\n\ndef execute() -> dict[str, object]:\n import cutrix # noqa: F401\n\n try:\n dist_ver = importlib.metadata.version(\"cutrix-video-translate-sdk\")\n except importlib.metadata.PackageNotFoundError:\n dist_ver = \"unknown\"\n return {\"import_ok\": True, \"distribution_version\": dist_ver}\n```\n\n## Canonical docs / 权威文档\n\n**English:**\n\n- Repository root `README.md`: authoritative install, parameters, polling, language lists, and edge notes\n- `docs/ARCHITECTURE.md`: data flow `Client` → `VideoResource` → `_http`\n\nKeep 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.\n\n**中文：**\n\n- 本仓库根目录 `README.md`：安装、参数、轮询、语言表与边界说明的权威来源\n- `docs/ARCHITECTURE.md`：`Client` → `VideoResource` → `_http` 数据流\n\n回答用户时应与上述文档保持一致；本文件中的技能 `version` 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 `requirements.txt` 与技能 `version`（semver）。\n\nFile v1.1.3:README.md\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/` at the repo root. This skill only documents how to **install and call** that package from agent-generated code.\n\nFile v1.1.3:_meta.json\n\n{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"1.1.3\",\n \"publishedAt\": 1778577807854\n}\n\nFile v1.1.3:skill-card.md\n\n## Description:
\nTranslate video into another language while preserving voice timbre and emotion with Cutrix video translation, dubbing, and subtitle guidance.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[wallacerao](https://clawhub.ai/user/wallacerao)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agent users use this skill to generate Python guidance and examples for installing the Cutrix SDK, submitting video translation tasks, polling task status, and handling subtitle or language parameters.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill requires a Cutrix API key.
\nMitigation: Use a scoped key, provide it through CUTRIX_API_KEY, and avoid hard-coding credentials in repositories or prompts.
\nRisk: Selected video or audio content is uploaded to Cutrix for cloud processing.
\nMitigation: Avoid confidential or regulated media unless approved, and review Cutrix retention and privacy terms before use.
\nRisk: The README uses cutrix-python-sdk naming while the manifested skill name is Cutrix Video Translate.
\nMitigation: Treat this as a documentation naming inconsistency and rely on the server-resolved skill slug and release metadata for identification.
\n\n\n## Reference(s):
\n- [Cutrix](https://www.cutrix.cc)
\n- [Cutrix API Base URL](https://www.cutrix.cc/v1)
\n- [ClawHub Release Page](https://clawhub.ai/wallacerao/cutrix-video-translate)
\n\n\n## Skill Output:
\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration instructions]
\n**Output Format:** [Markdown with Python and shell code examples]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May include Cutrix SDK calls that require CUTRIX_API_KEY and network access to Cutrix.]
\n\n## Skill Version(s):
\n1.1.3 (source: server release metadata and frontmatter)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.1.3:requirements.txt\n\n# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0\n\nArchive v1.1.2: 5 files, 11097 bytes\n\nFiles: README.md (4322b), requirements.txt (121b), scripts/check_install.py (611b), SKILL.md (18053b), _meta.json (141b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: cutrix-video-translate\nversion: 1.1.2\ndescription: >-\n EN: Guides coding agents to integrate Cutrix via PyPI package\n cutrix-video-translate-sdk (import cutrix): local upload, translate()/translate_file(),\n get_task() polling, status and response fields, failed_code table, full source/target\n language code tables (aligned with repo README), CUTRIX_API_KEY.\n 中文：指导代理通过 cutrix-video-translate-sdk 对接 Cutrix：本地上传、translate/\n translate_file、get_task 轮询、状态与返回字段、失败码表、与 README 一致的源/目标\n 语言码表、CUTRIX_API_KEY。\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - china\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可解决90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接口：`translate()`（本地文件）\n\n**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()`.\n\n**中文：**主入口：`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()` 轮询。\n\n```python\nfrom cutrix import Client\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration\n```\n\n### Compatibility alias / 兼容别名\n\n**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.\n\n**中文：**`client.video.translate_file(...)` 与 `translate(...)` 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。\n\n```python\nfrom cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)\n```\n\n## API: poll `get_task()` / 接口：轮询 `get_task()`\n\n**English:** After `translate()` / `translate_file()`, poll `client.video.get_task(task_id=...)` until a terminal status. Success terminal: `succeed`. Failure terminal: `failed`.\n\n**中文：**在 `translate()` / `translate_file()` 之后，轮询 `client.video.get_task(task_id=...)` 直至终态。成功终态：`succeed`；失败终态：`failed`。\n\n### Task `status` values / 任务 `status` 取值\n\n| `status` | Meaning (EN) | 含义（中文） |\n|---|---|---|\n| `pending` | Task is queued, waiting to be picked up | 排队等待调度 |\n| `started` | Processing is in progress | 处理中 |\n| `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` |\n| `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` |\n\n```python\nimport time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)\n```\n\n### `get_task()` response fields / `get_task()` 返回字段\n\n| Field | Type | Description (EN) | 说明（中文） |\n|---|---|---|---|\n| `id` / `task_id` | `int` | Task identifier | 任务 ID |\n| `status` | `str \\| None` | Current status | 当前状态 |\n| `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） |\n| `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 |\n| `source_lang` | `str \\| None` | Detected or specified source language | 源语言（检测或指定） |\n| `target_lang` | `str \\| None` | Target language | 目标语言 |\n| `input_video_duration` | `float \\| None` | Source video length in seconds | 源视频时长（秒） |\n| `name` | `str \\| None` | Task label | 任务名称 |\n| `failed_code` | `int \\| str \\| None` | Error code when `status` is `failed` | 失败时的错误码 |\n| `failed_message` | `str \\| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 |\n| `created_at` | `datetime \\| None` | Task creation time (UTC) | 创建时间（UTC） |\n| `estimate_finish_time` | `datetime \\| None` | Estimated completion (UTC) | 预计完成时间（UTC） |\n| `finished_at` | `datetime \\| None` | Actual completion (UTC) | 实际完成时间（UTC） |\n\n**English:** `get_task()` applies a **soft rate limit of about 1 call/second per `Client` instance** to avoid accidental hot-loop polling.\n\n**中文：**`get_task()` 对**每个 `Client` 实例**有约 **1 次/秒**的软限流，避免无意中的高频轮询。\n\n### Known `failed_code` values / 已知 `failed_code`\n\n| Code | Message (EN) |\n|---|---|\n| `2001` | Automatic language detection failed. Please select the source language manually and try again. |\n| `2002` | No audio was detected. Please make sure the video contains an audio track. |\n| `2003` | No video was detected. Please make sure the file contains video content. |\n| `2004` | Unknown error. Please try again later or contact support. |\n| `2005` | The source and target languages are the same, so translation is not needed. |\n\n**中文：**`2001` 自动语种识别失败，请改手动 `source_lang`；`2002` 无音频轨；`2003` 无视频轨；`2004` 未知错误；`2005` 源语种与目标语种相同。\n\n```python\nfrom cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])\n```\n\n## Language codes (aligned with repo `README.md`) / 语言代码（与仓库 `README.md` 一致）\n\n**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.\n\n**中文：**运行时优先以 `SOURCE_LANGUAGES`、`TARGET_LANGUAGES` 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。\n\n```python\nfrom cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))\n```\n\n### Supported source languages (`source_lang`) / 支持的源语言（`source_lang`）\n\n| Code | Language |\n|---|---|\n| `auto` | Auto-detect |\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `yue` | Cantonese |\n| `ar` | Arabic |\n| `cs` | Czech |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fa` | Persian |\n| `fi` | Finnish |\n| `fil` | Filipino |\n| `fr` | French |\n| `hi` | Hindi |\n| `hu` | Hungarian |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `mk` | Macedonian |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`）\n\n| Code | Language |\n|---|---|\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `ar` | Arabic |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `he` | Hebrew |\n| `hi` | Hindi |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `no` | Norwegian |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `sw` | Swahili |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n**中文：**`auto` 仅出现在源语言；目标语言表无 `auto`。向 API 传参时使用上表中的 **code** 字符串。\n\n## Error model / 错误模型\n\n**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.\n\n**中文：**异常基类为 `SDKError`；HTTP 相关为 `APIError`。401 映射 `AuthenticationError`，429 映射 `RateLimitError`。示例代码应使用 `try/except`，勿静默吞错。\n\n| Exception | When (EN) | 何时（中文） |\n|---|---|---|\n| `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 |\n| `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 |\n| `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 |\n| `SDKError` | Local errors (e.g. file not found, missing dependency) | 本地错误（如文件不存在、缺依赖） |\n\n`APIError` attributes: `message` (str), `status_code` (int | None), `raw_response` (any).\n\n```python\nfrom cutrix import Client, AuthenticationError, RateLimitError\nfrom cutrix.exceptions import APIError, SDKError\n\nwith Client(api_key=\"...\") as client:\n try:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n except AuthenticationError:\n print(\"Invalid API key\")\n except RateLimitError:\n print(\"Rate limit hit — slow down\")\n except APIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n except SDKError as e:\n print(f\"SDK error: {e}\")\n```\n\n## Advanced `Client` options (optional) / 高级 `Client` 选项（可选）\n\n**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.\n\n**中文：**默认 `base_url=\"https://www.cutrix.cc/v1\"`，`timeout=30.0`。可传额外 `headers`，或通过 `http_client` 注入自定义 `httpx.Client` 以配置代理、连接池、重试等。\n\n```python\nfrom cutrix import Client\n\nclient = Client(\n api_key=\"...\",\n base_url=\"https://www.cutrix.cc/v1\",\n timeout=60.0,\n headers={\"X-Custom-Header\": \"value\"},\n)\n```\n\n## Network & dependencies / 网络与依赖\n\n**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.\n\n**中文：**默认安装包含 `httpx`、`pydantic` 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。\n\n## Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）\n\n**English:** If the product uses a **one folder, one skill** layout similar to **Cursor Agent Skills**:\n\n1. Place the entire `cutrix-python-sdk` folder where the product expects skills (often `.cursor/skills/cutrix-python-sdk/`—check that product’s docs).\n2. Keep `SKILL.md` at the folder root.\n3. Have the user run `pip install cutrix-video-translate-sdk` or `pip install -r requirements.txt` in the runtime environment.\n\nTo 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.\n\n**中文：**若目标产品采用与 **Cursor Agent Skills** 类似的「单目录一技能」结构：\n\n1. 将整个 `cutrix-python-sdk` 文件夹放到该产品要求的技能根路径（常见为项目内 `.cursor/skills/cutrix-python-sdk/`，以各产品文档为准）。\n2. 保证目录根部存在本文件 `SKILL.md`。\n3. 由用户在运行环境中执行 `pip install cutrix-video-translate-sdk` 或 `pip install -r requirements.txt`。\n\n发布到 **Claw Hub** 时，见仓库内 `clawhub/cutrix-python-sdk/README.md` 的 `clawhub validate` / `clawhub publish` 步骤；发布前确认 frontmatter 的 `author` 与你在 clawhub.ai 上的发布者 ID 一致。\n\n## Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）\n\n**English:** Confirms the distribution is installed and `import cutrix` works; **does not** call the Cutrix API. Equivalent script: `python scripts/check_install.py`.\n\n**中文：**仅确认已安装发行包且可 `import cutrix`，**不**调用 Cutrix API。等价脚本：`python scripts/check_install.py`。\n\n```python\nfrom __future__ import annotations\n\nimport importlib.metadata\n\n\ndef execute() -> dict[str, object]:\n import cutrix # noqa: F401\n\n try:\n dist_ver = importlib.metadata.version(\"cutrix-video-translate-sdk\")\n except importlib.metadata.PackageNotFoundError:\n dist_ver = \"unknown\"\n return {\"import_ok\": True, \"distribution_version\": dist_ver}\n```\n\n## Canonical docs / 权威文档\n\n**English:**\n\n- Repository root `README.md`: authoritative install, parameters, polling, language lists, and edge notes\n- `docs/ARCHITECTURE.md`: data flow `Client` → `VideoResource` → `_http`\n\nKeep 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.\n\n**中文：**\n\n- 本仓库根目录 `README.md`：安装、参数、轮询、语言表与边界说明的权威来源\n- `docs/ARCHITECTURE.md`：`Client` → `VideoResource` → `_http` 数据流\n\n回答用户时应与上述文档保持一致；本文件中的技能 `version` 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 `requirements.txt` 与技能 `version`（semver）。\n\nFile v1.1.2:README.md\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/` at the repo root. This skill only documents how to **install and call** that package from agent-generated code.\n\nFile v1.1.2:_meta.json\n\n{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"1.1.2\",\n \"publishedAt\": 1778577456572\n}\n\nFile v1.1.2:requirements.txt\n\n# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0\n\nArchive v1.1.1: 5 files, 11094 bytes\n\nFiles: README.md (4322b), requirements.txt (121b), scripts/check_install.py (611b), SKILL.md (18053b), _meta.json (141b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: cutrix-video-translate\nversion: 1.1.1\ndescription: >-\n EN: Guides coding agents to integrate Cutrix via PyPI package\n cutrix-video-translate-sdk (import cutrix): local upload, translate()/translate_file(),\n get_task() polling, status and response fields, failed_code table, full source/target\n language code tables (aligned with repo README), CUTRIX_API_KEY.\n 中文：指导代理通过 cutrix-video-translate-sdk 对接 Cutrix：本地上传、translate/\n translate_file、get_task 轮询、状态与返回字段、失败码表、与 README 一致的源/目标\n 语言码表、CUTRIX_API_KEY。\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - china\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可解决90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接口：`translate()`（本地文件）\n\n**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()`.\n\n**中文：**主入口：`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()` 轮询。\n\n```python\nfrom cutrix import Client\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration\n```\n\n### Compatibility alias / 兼容别名\n\n**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.\n\n**中文：**`client.video.translate_file(...)` 与 `translate(...)` 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。\n\n```python\nfrom cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)\n```\n\n## API: poll `get_task()` / 接口：轮询 `get_task()`\n\n**English:** After `translate()` / `translate_file()`, poll `client.video.get_task(task_id=...)` until a terminal status. Success terminal: `succeed`. Failure terminal: `failed`.\n\n**中文：**在 `translate()` / `translate_file()` 之后，轮询 `client.video.get_task(task_id=...)` 直至终态。成功终态：`succeed`；失败终态：`failed`。\n\n### Task `status` values / 任务 `status` 取值\n\n| `status` | Meaning (EN) | 含义（中文） |\n|---|---|---|\n| `pending` | Task is queued, waiting to be picked up | 排队等待调度 |\n| `started` | Processing is in progress | 处理中 |\n| `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` |\n| `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` |\n\n```python\nimport time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)\n```\n\n### `get_task()` response fields / `get_task()` 返回字段\n\n| Field | Type | Description (EN) | 说明（中文） |\n|---|---|---|---|\n| `id` / `task_id` | `int` | Task identifier | 任务 ID |\n| `status` | `str \\| None` | Current status | 当前状态 |\n| `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） |\n| `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 |\n| `source_lang` | `str \\| None` | Detected or specified source language | 源语言（检测或指定） |\n| `target_lang` | `str \\| None` | Target language | 目标语言 |\n| `input_video_duration` | `float \\| None` | Source video length in seconds | 源视频时长（秒） |\n| `name` | `str \\| None` | Task label | 任务名称 |\n| `failed_code` | `int \\| str \\| None` | Error code when `status` is `failed` | 失败时的错误码 |\n| `failed_message` | `str \\| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 |\n| `created_at` | `datetime \\| None` | Task creation time (UTC) | 创建时间（UTC） |\n| `estimate_finish_time` | `datetime \\| None` | Estimated completion (UTC) | 预计完成时间（UTC） |\n| `finished_at` | `datetime \\| None` | Actual completion (UTC) | 实际完成时间（UTC） |\n\n**English:** `get_task()` applies a **soft rate limit of about 1 call/second per `Client` instance** to avoid accidental hot-loop polling.\n\n**中文：**`get_task()` 对**每个 `Client` 实例**有约 **1 次/秒**的软限流，避免无意中的高频轮询。\n\n### Known `failed_code` values / 已知 `failed_code`\n\n| Code | Message (EN) |\n|---|---|\n| `2001` | Automatic language detection failed. Please select the source language manually and try again. |\n| `2002` | No audio was detected. Please make sure the video contains an audio track. |\n| `2003` | No video was detected. Please make sure the file contains video content. |\n| `2004` | Unknown error. Please try again later or contact support. |\n| `2005` | The source and target languages are the same, so translation is not needed. |\n\n**中文：**`2001` 自动语种识别失败，请改手动 `source_lang`；`2002` 无音频轨；`2003` 无视频轨；`2004` 未知错误；`2005` 源语种与目标语种相同。\n\n```python\nfrom cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])\n```\n\n## Language codes (aligned with repo `README.md`) / 语言代码（与仓库 `README.md` 一致）\n\n**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.\n\n**中文：**运行时优先以 `SOURCE_LANGUAGES`、`TARGET_LANGUAGES` 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。\n\n```python\nfrom cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))\n```\n\n### Supported source languages (`source_lang`) / 支持的源语言（`source_lang`）\n\n| Code | Language |\n|---|---|\n| `auto` | Auto-detect |\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `yue` | Cantonese |\n| `ar` | Arabic |\n| `cs` | Czech |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fa` | Persian |\n| `fi` | Finnish |\n| `fil` | Filipino |\n| `fr` | French |\n| `hi` | Hindi |\n| `hu` | Hungarian |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `mk` | Macedonian |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`）\n\n| Code | Language |\n|---|---|\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `ar` | Arabic |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `he` | Hebrew |\n| `hi` | Hindi |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `no` | Norwegian |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `sw` | Swahili |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n**中文：**`auto` 仅出现在源语言；目标语言表无 `auto`。向 API 传参时使用上表中的 **code** 字符串。\n\n## Error model / 错误模型\n\n**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.\n\n**中文：**异常基类为 `SDKError`；HTTP 相关为 `APIError`。401 映射 `AuthenticationError`，429 映射 `RateLimitError`。示例代码应使用 `try/except`，勿静默吞错。\n\n| Exception | When (EN) | 何时（中文） |\n|---|---|---|\n| `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 |\n| `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 |\n| `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 |\n| `SDKError` | Local errors (e.g. file not found, missing dependency) | 本地错误（如文件不存在、缺依赖） |\n\n`APIError` attributes: `message` (str), `status_code` (int | None), `raw_response` (any).\n\n```python\nfrom cutrix import Client, AuthenticationError, RateLimitError\nfrom cutrix.exceptions import APIError, SDKError\n\nwith Client(api_key=\"...\") as client:\n try:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n except AuthenticationError:\n print(\"Invalid API key\")\n except RateLimitError:\n print(\"Rate limit hit — slow down\")\n except APIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n except SDKError as e:\n print(f\"SDK error: {e}\")\n```\n\n## Advanced `Client` options (optional) / 高级 `Client` 选项（可选）\n\n**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.\n\n**中文：**默认 `base_url=\"https://www.cutrix.cc/v1\"`，`timeout=30.0`。可传额外 `headers`，或通过 `http_client` 注入自定义 `httpx.Client` 以配置代理、连接池、重试等。\n\n```python\nfrom cutrix import Client\n\nclient = Client(\n api_key=\"...\",\n base_url=\"https://www.cutrix.cc/v1\",\n timeout=60.0,\n headers={\"X-Custom-Header\": \"value\"},\n)\n```\n\n## Network & dependencies / 网络与依赖\n\n**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.\n\n**中文：**默认安装包含 `httpx`、`pydantic` 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。\n\n## Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）\n\n**English:** If the product uses a **one folder, one skill** layout similar to **Cursor Agent Skills**:\n\n1. Place the entire `cutrix-python-sdk` folder where the product expects skills (often `.cursor/skills/cutrix-python-sdk/`—check that product’s docs).\n2. Keep `SKILL.md` at the folder root.\n3. Have the user run `pip install cutrix-video-translate-sdk` or `pip install -r requirements.txt` in the runtime environment.\n\nTo 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.\n\n**中文：**若目标产品采用与 **Cursor Agent Skills** 类似的「单目录一技能」结构：\n\n1. 将整个 `cutrix-python-sdk` 文件夹放到该产品要求的技能根路径（常见为项目内 `.cursor/skills/cutrix-python-sdk/`，以各产品文档为准）。\n2. 保证目录根部存在本文件 `SKILL.md`。\n3. 由用户在运行环境中执行 `pip install cutrix-video-translate-sdk` 或 `pip install -r requirements.txt`。\n\n发布到 **Claw Hub** 时，见仓库内 `clawhub/cutrix-python-sdk/README.md` 的 `clawhub validate` / `clawhub publish` 步骤；发布前确认 frontmatter 的 `author` 与你在 clawhub.ai 上的发布者 ID 一致。\n\n## Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）\n\n**English:** Confirms the distribution is installed and `import cutrix` works; **does not** call the Cutrix API. Equivalent script: `python scripts/check_install.py`.\n\n**中文：**仅确认已安装发行包且可 `import cutrix`，**不**调用 Cutrix API。等价脚本：`python scripts/check_install.py`。\n\n```python\nfrom __future__ import annotations\n\nimport importlib.metadata\n\n\ndef execute() -> dict[str, object]:\n import cutrix # noqa: F401\n\n try:\n dist_ver = importlib.metadata.version(\"cutrix-video-translate-sdk\")\n except importlib.metadata.PackageNotFoundError:\n dist_ver = \"unknown\"\n return {\"import_ok\": True, \"distribution_version\": dist_ver}\n```\n\n## Canonical docs / 权威文档\n\n**English:**\n\n- Repository root `README.md`: authoritative install, parameters, polling, language lists, and edge notes\n- `docs/ARCHITECTURE.md`: data flow `Client` → `VideoResource` → `_http`\n\nKeep 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.\n\n**中文：**\n\n- 本仓库根目录 `README.md`：安装、参数、轮询、语言表与边界说明的权威来源\n- `docs/ARCHITECTURE.md`：`Client` → `VideoResource` → `_http` 数据流\n\n回答用户时应与上述文档保持一致；本文件中的技能 `version` 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 `requirements.txt` 与技能 `version`（semver）。\n\nFile v1.1.1:README.md\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/` at the repo root. This skill only documents how to **install and call** that package from agent-generated code.\n\nFile v1.1.1:_meta.json\n\n{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"1.1.1\",\n \"publishedAt\": 1778577307951\n}\n\nFile v1.1.1:requirements.txt\n\n# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0\n\nArchive v1.1.0: 5 files, 11100 bytes\n\nFiles: README.md (4322b), requirements.txt (121b), scripts/check_install.py (611b), SKILL.md (18068b), _meta.json (141b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: cutrix-video-translate\nversion: 1.1.0\ndescription: >-\n EN: Guides coding agents to integrate Cutrix via PyPI package\n cutrix-video-translate-sdk (import cutrix): local upload, translate()/translate_file(),\n get_task() polling, status and response fields, failed_code table, full source/target\n language code tables (aligned with repo README), CUTRIX_API_KEY.\n 中文：指导代理通过 cutrix-video-translate-sdk 对接 Cutrix：本地上传、translate/\n translate_file、get_task 轮询、状态与返回字段、失败码表、与 README 一致的源/目标\n 语言码表、CUTRIX_API_KEY。\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - china\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可解决90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接口：`translate()`（本地文件）\n\n**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()`.\n\n**中文：**主入口：`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()` 轮询。\n\n```python\nfrom cutrix import Client\n\nwith Client(api_key=\"sk-...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration\n```\n\n### Compatibility alias / 兼容别名\n\n**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.\n\n**中文：**`client.video.translate_file(...)` 与 `translate(...)` 参数相同，为薄别名。SDK 内部完成完整上传链路：初始化 → 云存储上传 → 完成回调 → 创建任务。\n\n```python\nfrom cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"sk-...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)\n```\n\n## API: poll `get_task()` / 接口：轮询 `get_task()`\n\n**English:** After `translate()` / `translate_file()`, poll `client.video.get_task(task_id=...)` until a terminal status. Success terminal: `succeed`. Failure terminal: `failed`.\n\n**中文：**在 `translate()` / `translate_file()` 之后，轮询 `client.video.get_task(task_id=...)` 直至终态。成功终态：`succeed`；失败终态：`failed`。\n\n### Task `status` values / 任务 `status` 取值\n\n| `status` | Meaning (EN) | 含义（中文） |\n|---|---|---|\n| `pending` | Task is queued, waiting to be picked up | 排队等待调度 |\n| `started` | Processing is in progress | 处理中 |\n| `succeed` | Finished successfully — `output_video_path` is available | 成功完成，可读取 `output_video_path` |\n| `failed` | Task failed — inspect `failed_code` / `failed_message` | 失败，查看 `failed_code` / `failed_message` |\n\n```python\nimport time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"sk-...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)\n```\n\n### `get_task()` response fields / `get_task()` 返回字段\n\n| Field | Type | Description (EN) | 说明（中文） |\n|---|---|---|---|\n| `id` / `task_id` | `int` | Task identifier | 任务 ID |\n| `status` | `str \\| None` | Current status | 当前状态 |\n| `output_video_path` | `str` | Download URL of translated video (when successful) | 译后视频下载地址（成功时有值） |\n| `input_video_path` | `str` | URL of the original uploaded video | 原始上传视频地址 |\n| `source_lang` | `str \\| None` | Detected or specified source language | 源语言（检测或指定） |\n| `target_lang` | `str \\| None` | Target language | 目标语言 |\n| `input_video_duration` | `float \\| None` | Source video length in seconds | 源视频时长（秒） |\n| `name` | `str \\| None` | Task label | 任务名称 |\n| `failed_code` | `int \\| str \\| None` | Error code when `status` is `failed` | 失败时的错误码 |\n| `failed_message` | `str \\| None` | Human-readable message for known `failed_code` | 已知失败码的可读说明 |\n| `created_at` | `datetime \\| None` | Task creation time (UTC) | 创建时间（UTC） |\n| `estimate_finish_time` | `datetime \\| None` | Estimated completion (UTC) | 预计完成时间（UTC） |\n| `finished_at` | `datetime \\| None` | Actual completion (UTC) | 实际完成时间（UTC） |\n\n**English:** `get_task()` applies a **soft rate limit of about 1 call/second per `Client` instance** to avoid accidental hot-loop polling.\n\n**中文：**`get_task()` 对**每个 `Client` 实例**有约 **1 次/秒**的软限流，避免无意中的高频轮询。\n\n### Known `failed_code` values / 已知 `failed_code`\n\n| Code | Message (EN) |\n|---|---|\n| `2001` | Automatic language detection failed. Please select the source language manually and try again. |\n| `2002` | No audio was detected. Please make sure the video contains an audio track. |\n| `2003` | No video was detected. Please make sure the file contains video content. |\n| `2004` | Unknown error. Please try again later or contact support. |\n| `2005` | The source and target languages are the same, so translation is not needed. |\n\n**中文：**`2001` 自动语种识别失败，请改手动 `source_lang`；`2002` 无音频轨；`2003` 无视频轨；`2004` 未知错误；`2005` 源语种与目标语种相同。\n\n```python\nfrom cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])\n```\n\n## Language codes (aligned with repo `README.md`) / 语言代码（与仓库 `README.md` 一致）\n\n**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.\n\n**中文：**运行时优先以 `SOURCE_LANGUAGES`、`TARGET_LANGUAGES` 为准。下表与公开 README 对齐；若与代码常量不一致，以仓库内常量及 README 为准。\n\n```python\nfrom cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))\n```\n\n### Supported source languages (`source_lang`) / 支持的源语言（`source_lang`）\n\n| Code | Language |\n|---|---|\n| `auto` | Auto-detect |\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `yue` | Cantonese |\n| `ar` | Arabic |\n| `cs` | Czech |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fa` | Persian |\n| `fi` | Finnish |\n| `fil` | Filipino |\n| `fr` | French |\n| `hi` | Hindi |\n| `hu` | Hungarian |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `mk` | Macedonian |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ro` | Romanian |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n### Supported target languages (`target_lang`) / 支持的目标语言（`target_lang`）\n\n| Code | Language |\n|---|---|\n| `zh` | Chinese (Mandarin) |\n| `en` | English |\n| `ar` | Arabic |\n| `da` | Danish |\n| `de` | German |\n| `el` | Greek |\n| `es` | Spanish |\n| `fi` | Finnish |\n| `fr` | French |\n| `he` | Hebrew |\n| `hi` | Hindi |\n| `id` | Indonesian |\n| `it` | Italian |\n| `ja` | Japanese |\n| `ko` | Korean |\n| `ms` | Malay |\n| `nl` | Dutch |\n| `no` | Norwegian |\n| `pl` | Polish |\n| `pt` | Portuguese |\n| `ru` | Russian |\n| `sv` | Swedish |\n| `sw` | Swahili |\n| `th` | Thai |\n| `tr` | Turkish |\n| `vi` | Vietnamese |\n\n**中文：**`auto` 仅出现在源语言；目标语言表无 `auto`。向 API 传参时使用上表中的 **code** 字符串。\n\n## Error model / 错误模型\n\n**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.\n\n**中文：**异常基类为 `SDKError`；HTTP 相关为 `APIError`。401 映射 `AuthenticationError`，429 映射 `RateLimitError`。示例代码应使用 `try/except`，勿静默吞错。\n\n| Exception | When (EN) | 何时（中文） |\n|---|---|---|\n| `AuthenticationError` | HTTP 401 — invalid or missing API key | 密钥无效或未提供 |\n| `RateLimitError` | HTTP 429 — too many requests | 请求过于频繁 |\n| `APIError` | Other HTTP errors or non-zero API `code` | 其他 HTTP 错误或业务 `code` 非 0 |\n| `SDKError` | Local errors (e.g. file not found, missing dependency) | 本地错误（如文件不存在、缺依赖） |\n\n`APIError` attributes: `message` (str), `status_code` (int | None), `raw_response` (any).\n\n```python\nfrom cutrix import Client, AuthenticationError, RateLimitError\nfrom cutrix.exceptions import APIError, SDKError\n\nwith Client(api_key=\"sk-...\") as client:\n try:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n except AuthenticationError:\n print(\"Invalid API key\")\n except RateLimitError:\n print(\"Rate limit hit — slow down\")\n except APIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n except SDKError as e:\n print(f\"SDK error: {e}\")\n```\n\n## Advanced `Client` options (optional) / 高级 `Client` 选项（可选）\n\n**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.\n\n**中文：**默认 `base_url=\"https://www.cutrix.cc/v1\"`，`timeout=30.0`。可传额外 `headers`，或通过 `http_client` 注入自定义 `httpx.Client` 以配置代理、连接池、重试等。\n\n```python\nfrom cutrix import Client\n\nclient = Client(\n api_key=\"sk-...\",\n base_url=\"https://www.cutrix.cc/v1\",\n timeout=60.0,\n headers={\"X-Custom-Header\": \"value\"},\n)\n```\n\n## Network & dependencies / 网络与依赖\n\n**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.\n\n**中文：**默认安装包含 `httpx`、`pydantic` 与 COS 上传相关依赖；创建任务走官方上传链路。不要假设 README 或官方文档未列出的隐藏端点或字段。\n\n## Domestic assistants (WorkBuddy / 小龙虾) / 国内助手（WorkBuddy / 小龙虾）\n\n**English:** If the product uses a **one folder, one skill** layout similar to **Cursor Agent Skills**:\n\n1. Place the entire `cutrix-python-sdk` folder where the product expects skills (often `.cursor/skills/cutrix-python-sdk/`—check that product’s docs).\n2. Keep `SKILL.md` at the folder root.\n3. Have the user run `pip install cutrix-video-translate-sdk` or `pip install -r requirements.txt` in the runtime environment.\n\nTo 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.\n\n**中文：**若目标产品采用与 **Cursor Agent Skills** 类似的「单目录一技能」结构：\n\n1. 将整个 `cutrix-python-sdk` 文件夹放到该产品要求的技能根路径（常见为项目内 `.cursor/skills/cutrix-python-sdk/`，以各产品文档为准）。\n2. 保证目录根部存在本文件 `SKILL.md`。\n3. 由用户在运行环境中执行 `pip install cutrix-video-translate-sdk` 或 `pip install -r requirements.txt`。\n\n发布到 **Claw Hub** 时，见仓库内 `clawhub/cutrix-python-sdk/README.md` 的 `clawhub validate` / `clawhub publish` 步骤；发布前确认 frontmatter 的 `author` 与你在 clawhub.ai 上的发布者 ID 一致。\n\n## Verification snippet (no network, no API key) / 验证用执行片段（无网络、无密钥）\n\n**English:** Confirms the distribution is installed and `import cutrix` works; **does not** call the Cutrix API. Equivalent script: `python scripts/check_install.py`.\n\n**中文：**仅确认已安装发行包且可 `import cutrix`，**不**调用 Cutrix API。等价脚本：`python scripts/check_install.py`。\n\n```python\nfrom __future__ import annotations\n\nimport importlib.metadata\n\n\ndef execute() -> dict[str, object]:\n import cutrix # noqa: F401\n\n try:\n dist_ver = importlib.metadata.version(\"cutrix-video-translate-sdk\")\n except importlib.metadata.PackageNotFoundError:\n dist_ver = \"unknown\"\n return {\"import_ok\": True, \"distribution_version\": dist_ver}\n```\n\n## Canonical docs / 权威文档\n\n**English:**\n\n- Repository root `README.md`: authoritative install, parameters, polling, language lists, and edge notes\n- `docs/ARCHITECTURE.md`: data flow `Client` → `VideoResource` → `_http`\n\nKeep 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.\n\n**中文：**\n\n- 本仓库根目录 `README.md`：安装、参数、轮询、语言表与边界说明的权威来源\n- `docs/ARCHITECTURE.md`：`Client` → `VideoResource` → `_http` 数据流\n\n回答用户时应与上述文档保持一致；本文件中的技能 `version` 与 PyPI SDK 版本独立维护，发布新 SDK 后可分别更新 `requirements.txt` 与技能 `version`（semver）。\n\nFile v1.1.0:README.md\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/` at the repo root. This skill only documents how to **install and call** that package from agent-generated code.\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1778570138852\n}\n\nFile v1.1.0:requirements.txt\n\n# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0","readmeExcerpt":"Skill: Cutrix Video Translate Owner: wallacerao Summary: Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM. Enough free quota every month for beginners,... Tags: ai-translation:v1.1.4, dubbing:v1.1.4, latest:v1.1.4, subtitle:v1.1.4, video-translate:v1.1.4, voice-clone:v1.1.4 Version history: vv1.1.4 | 2026-06-08T01:45:23.564Z | user 优化搜索关键词和描述，提升搜索匹配度 v1.1.","codeSnippets":[],"executableExamples":[{"language":"python","snippet":"import os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])"},{"language":"python","snippet":"from cutrix import Client\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\", # required — local file path\n target_lang=\"zh\", # required — target language code\n source_lang=\"auto\", # optional — default \"auto\"\n task_name=\"my task\", # optional\n add_subtitle=True, # optional — burn subtitles into output, default True\n erase_original_subtitle=False, # optional\n remove_cutrix_logo=True, # optional — maps to API field is_logo\n # progress_callback=on_progress, # optional — receives upload progress 0-100\n )\n\n print(result.task_id) # int\n print(result.required_minutes) # int — estimated quota cost\n print(result.video_duration_seconds) # float — source video duration"},{"language":"python","snippet":"from cutrix import Client\n\ndef on_progress(percent: int) -> None:\n print(f\"\\rupload: {percent}%\", end=\"\", flush=True)\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate_file(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n source_lang=\"auto\",\n task_name=\"local upload demo\",\n progress_callback=on_progress,\n )\n print(result.task_id)"},{"language":"python","snippet":"import time\nfrom cutrix import Client\n\nSUCCESS = {\"succeed\"}\nFAILURE = {\"failed\"}\n\nwith Client(api_key=\"...\") as client:\n result = client.video.translate(\n file_path=\"./demo.mp4\",\n target_lang=\"zh\",\n )\n\n while True:\n task = client.video.get_task(task_id=result.task_id)\n print(f\"status: {task.status}\")\n\n if task.status in SUCCESS:\n print(\"output:\", task.output_video_path)\n break\n if task.status in FAILURE:\n print(\"failed, code:\", task.failed_code)\n print(\"failed, message:\", task.failed_message)\n break\n\n time.sleep(5)"},{"language":"python","snippet":"from cutrix import FAILED_CODE_MESSAGES\n\nprint(FAILED_CODE_MESSAGES[\"2002\"])"},{"language":"python","snippet":"from cutrix import SOURCE_LANGUAGES, TARGET_LANGUAGES\n\nprint(sorted(SOURCE_LANGUAGES))\nprint(sorted(TARGET_LANGUAGES))"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: cutrix-video-translate\nversion: 1.1.3\ndescription: >-\n Translate your video into another language, keep the original timbre and emotion with advanced voice clone LLM.\n Enough free quota every month for beginners, and save 90% of costs if the quota is exhausted for processional usage.\n video dubbing、AI subtitle、voice cloning、视频翻译、配音 字幕 声音克隆\nauthor: WallaceRao\ntags:\n - cutrix\n - video translate\n - video translation\n - translation\n - subtitles\n - python\n - sdk\n - httpx\n - video translate\n - dubbing\n - subtitle\n - AI translation\n - 视频翻译\n - 视频配音\n - 声音克隆\n - 字幕翻译\n---\n\n# Cutrix Python SDK — OpenClaw / ClawHub skill | Cutrix Python SDK — OpenClaw / ClawHub 技能\n\n**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.\n\n**中文：**本技能指导代理在 **Python** 中正确使用官方 SDK（PyPI：`cutrix-video-translate-sdk`，导入包名：`cutrix`），对接 [Cutrix](https://www.cutrix.cc) 的视频翻译 / 配音 / 字幕能力。**不要**在技能目录内重复实现 HTTP；一律通过已发布的 SDK 调用。\n\n## When to apply / 何时启用\n\n**English:** Load and follow this skill when:\n\n- 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`\n- You need Python code to submit translation tasks, poll task status, or handle subtitle-related parameters\n- 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\n\n**中文：**在以下情况应加载并遵守本技能：\n\n- 用户提到 `视频翻译`， `语音克隆视频翻译`，`免费视频翻译`， `heygen`, Cutrix、`cutrix.cc`、`cutrix-video-translate-sdk` 或 `from cutrix import Client`\n- 需要用 Python 提交视频翻译任务、查询任务状态或处理字幕相关参数\n- 用户在国内助手（如 WorkBuddy 等「小龙虾」生态）中编写相同逻辑：若产品支持基于 `SKILL.md` 的技能包，本目录可直接作为技能根目录使用\n\n\n**English:** Features：\n- Cutrix keeps the original timbre and emotion with advanced voice clone LLM,\n- Spread your video into multi languages with just one submit. \n- 10 minutes of free quota per month\n- Saving 90% of costs if the quota is exhausted\n\n**中文:** 特性\n- 使用最先进语音大模型，完美保留原声音色和情绪\n- 提交后不管，无需手动干预\n- 每月10分钟免费翻译\n- 免费额度用尽后也可节约90%费用\n\n## Environment & secrets / 环境与密钥\n\n**English:**\n\n- **Python:** 3.9+\n- **Install:** `pip install cutrix-video-translate-sdk` (or `pip install -r requirements.txt`)\n- **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`)\n\n**中文：**\n\n- **Python：**3.9+\n- **安装：**`pip install cutrix-video-translate-sdk`（或 `pip install -r requirements.txt`）\n- **密钥：**在 Cutrix 控制台获取 API Key；**禁止**硬编码进仓库或技能正文。优先使用环境变量 `CUTRIX_API_KEY`（见 `.env.example`）\n\n```python\nimport os\nfrom cutrix import Client\n\nclient = Client(api_key=os.environ[\"CUTRIX_API_KEY\"])\n```\n\n## API: `translate()` (local file) / 接"},{"path":"README.md","content":"# Cutrix Python SDK — OpenClaw / ClawHub skill\n\nThis folder is a **ClawHub-compatible skill** that teaches OpenClaw-class agents how to use the official Cutrix Python SDK (`cutrix-video-translate-sdk` on PyPI). It is not a second implementation of the API.\n\nOfficial references:\n\n- [ClawHub Quickstart — publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)\n- [ClawHub CLI (`clawhub`)](https://docs.openclaw.ai/clawhub/cli)\n- [Skill format](https://docs.openclaw.ai/clawhub/skill-format)\n\n---\n\n## Publish to Claw Hub（发布到 OpenClaw Hub / ClawHub）\n\nClawHub 是 OpenClaw 的 **技能与插件注册表**。安装进 OpenClaw 用 `openclaw skills …`；**注册、登录、上传自己的技能**用 **`clawhub` CLI**（见上 Quickstart）。\n\n### 1. 前置条件\n\n1. 在 [clawhub.ai](https://clawhub.ai/) 注册并完成 **GitHub 绑定**（平台对账号/GitHub 有年龄与信任要求，以官网为准）。\n2. 本目录根下有 **`SKILL.md`**（必填），且 frontmatter 里 **`author`** 为你的 ClawHub **发布者标识**（与账号一致）。\n3. 发布到 ClawHub 的技能按官方说明以 **MIT-0** 许可发布（可自由使用与再分发；详见 CLI 文档中 `skill publish` 说明）。\n\n### 2. 安装 `clawhub` CLI\n\n```bash\nnpm i -g clawhub\n# 或\npnpm add -g clawhub\n```\n\n验证：\n\n```bash\nclawhub --help\n```\n\n### 3. 登录\n\n本机浏览器 OAuth（默认）：\n\n```bash\nclawhub login\nclawhub whoami\n```\n\n无头 / CI：在 ClawHub 网页创建 API token 后：\n\n```bash\nclawhub login --token clh_...\n```\n\n国内网络若需代理，CLI 会读取 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#http-proxy)）。\n\n### 4. 发布本技能（推荐命令）\n\n在**本技能目录**下执行（路径按你克隆仓库的位置调整）：\n\n```bash\ncd clawhub/cutrix-python-sdk\n\nclawhub skill publish . \\\n --slug cutrix-python-sdk \\\n --name \"Cutrix Python SDK\" \\\n --version 1.1.0 \\\n --changelog \"Sync README-aligned language tables and translate/get_task docs\"\n```\n\n说明：\n\n- **`--version`**：须为 **semver**，且通常与 `SKILL.md` frontmatter 里的 `version` **一致**；每次发新版递增 semver，并同步修改 `SKILL.md` 中的 `version`。\n- **`--slug`**：Hub 上的技能标识；首发布后若要改名可用官方 `skill rename` 等流程（见 CLI 文档）。\n- **`--changelog`**：建议每次发布都写一句变更说明。\n- **`--owner`**：若你以组织发布且账号有权限，可按 CLI 文档追加 `--owner `。\n\n官方 Quickstart 中的等价示例见：[Publish a skill](https://docs.openclaw.ai/clawhub/quickstart#publish-a-skill)。\n\n**旧式别名：**部分环境仍支持顶层 `clawhub publish`；以 `clawhub skill publish` 与 `clawhub --help` 为准。\n\n发布前可查看子命令全部参数：\n\n```bash\nclawhub skill publish --help\n```\n\n若你维护多个技能目录，也可用 **`clawhub sync`** 扫描并批量同步（见 [CLI 文档](https://docs.openclaw.ai/clawhub/cli#sync)）。\n\n### 5. 发布后\n\n- 在网页或通过 `clawhub inspect ` 查看元数据、版本与扫描状态。\n- 用户在 OpenClaw 侧安装示例（Quickstart）：`openclaw skills install `。\n\n---\n\n## WorkBuddy / 小龙虾生态（国内助手）\n\n许多国产 AI 助手（口语里常叫「小龙虾」）支持与 **Cursor Agent Skills** 类似的「技能目录」：根文件为 `SKILL.md`，旁挂 `README.md`、脚本与 `requirements.txt`。\n\n- 若产品支持从本仓库或压缩包「导入技能」，请直接选择 **`clawhub/cutrix-python-sdk`** 目录。\n- 若产品要求技能放在固定路径（例如项目下的 `.cursor/skills//`），可将整个 **`cutrix-python-sdk`** 文件夹复制过去，保持 `SKILL.md` 在目录根部。\n- 具体菜单名称以各产品文档为准；本技能不依赖境外服务即可被代理读取，**实际调用 Cutrix API 仍需网络可达 `https://www.cutrix.cc` 与用户自备的 API Key**。\n\n---\n\n## Local smoke check\n\n```bash\npip install -r requirements.txt\npython scripts/check_install.py\n```\n\n## Repository layout\n\nThe Python SDK lives under `src/cutrix/"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn79n5cshpnk2hphqr97gjsz0986kg0e\",\n \"slug\": \"cutrix-video-translate\",\n \"version\": \"v1.1.4\",\n \"publishedAt\": 1780883123564\n}"},{"path":"skill-card.md","content":"## Description:\n\nGuides agents to use the Cutrix Python SDK for video translation, dubbing, subtitles, task polling, and API error handling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[wallacerao](https://clawhub.ai/user/wallacerao)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to generate guidance, Python code, installation commands, and configuration for submitting Cutrix video translation tasks, polling task status, and handling subtitle-related parameters.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Selected videos, audio, subtitles, and task metadata may be sent to Cutrix for cloud processing.\n\nMitigation: Use the skill only when that data transfer is acceptable for the user's content and environment.\n\nRisk: API keys and ClawHub tokens can be exposed if copied into code, logs, or shared transcripts.\n\nMitigation: Store secrets outside generated code, prefer environment variables such as CUTRIX_API_KEY, and remove credentials from logs and transcripts.\n\nRisk: The SDK dependency may change over time, which can affect reproducibility or supply-chain controls.\n\nMitigation: In controlled environments, pin and hash-lock the SDK dependency before deployment.\n\n## Reference(s):\n\n- [Cutrix](https://www.cutrix.cc)\n- [Cutrix Video Translate on ClawHub](https://clawhub.ai/wallacerao/skills/cutrix-video-translate)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown with Python and bash code blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include SDK installation steps, environment-variable guidance, task polling patterns, language-code tables, and error-handling examples.]\n\n## Skill Version(s):\n\nv1.1.4 (source: ClawHub release evidence; artifact frontmatter says 1.1.3)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."},{"path":"requirements.txt","content":"# Pin for reproducible agent environments; bump minor/patch when releasing SDK.\ncutrix-video-translate-sdk>=0.0.2,<1.0.0"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1233,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:51:33.883Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:59:32.356Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}