heygen-translate

What this skill does

# HeyGen Video Translation

Translate and dub an existing video into 175+ languages. The system clones the
presenter's voice into the target language, re-syncs their lips to the new
audio, and returns a fully dubbed video. You provide a source video and a target
language — the engine handles transcription, translation, voice cloning,
lip-sync, and (optionally) burned-in captions.

This is **not** new-video generation. The presenter, performance, framing, and
brand assets in the original video are preserved. Translation rides on top of
what's already there.

## User-Facing Behavior

1. **Be concise.** Don't dump translation IDs, raw API payloads, or status JSON in chat. Report the result (video link, language) not the plumbing.
2. **No internal jargon.** Don't say "polling", "video_translation_id", "asset_id", "v3 endpoint". Say "translating", "almost done", "your file".
3. **Polling is silent.** Background long-running translations and only speak on (a) result delivered, (b) >5 min stall (one update), (c) hard failure.
4. **One result, one message.** When the video is done, send the link plus a one-line summary (target language, duration, mode). Not every API field.
5. **Don't narrate transport choice.** MCP vs CLI vs OpenClaw plugin is internal. Pick silently at session start; never mention which is in use.
6. **Communicate in the user's language.** Detect from their first message. Replies, confirmations, and questions in their language. Technical CLI/API directives stay in English.

## API Mode Detection

**Pick one transport at session start. Never mix, never switch mid-session, never narrate the choice.**

Detect in this order:

1. **OpenClaw plugin mode** — If running inside OpenClaw and the `video_generate` tool exposes a HeyGen translation model, prefer that. *Currently the plugin generates videos but does not expose translation directly — fall through to the next tier until HeyGen ships translation through `video_generate`.*
2. **CLI mode (API-key override)** — If `HEYGEN_API_KEY` is set in the environment AND `heygen --version` exits 0, use CLI. API-key presence is an explicit signal that the user wants direct API access.
3. **MCP mode** — No `HEYGEN_API_KEY` AND HeyGen MCP tools are visible (`mcp__heygen__*`). OAuth auth, runs against the user's plan credits.
4. **CLI mode (fallback)** — MCP tools not available AND `heygen --version` exits 0. Auth via `heygen auth login`.
5. **Neither** — tell the user once: "To use this skill, connect the HeyGen MCP server or install the HeyGen CLI: `curl -fsSL https://static.heygen.ai/cli/install.sh | bash` then `heygen auth login`."

### Auth verification (run before any API call)

After mode detection, verify auth actually works before entering Phase 1. This avoids wasting the user's time gathering inputs only to hit an auth error on submit.

- **MCP mode:** auth is handled by OAuth — no check needed.
- **CLI mode:** run `heygen auth status` (silent). If it exits 0, proceed. If it exits non-zero (no key, expired, invalid):
  1. Ask the user: *"I need your HeyGen API key to proceed. You can grab one from https://app.heygen.com/settings?nav=API — paste it here."*
  2. Once they provide it, persist it: `echo "<key>" | heygen auth login` (writes to `~/.heygen/credentials`, survives across sessions).
  3. Verify: `heygen auth status`. If still failing, surface the error and stop.

This is a **one-time setup**. Once `heygen auth login` persists the key, future sessions pick it up automatically. Don't ask again if `heygen auth status` passes.

**Hard rules:**

- **Never call `curl api.heygen.com/...`** Every operation in this skill has a CLI command and (where supported) an MCP tool. Use those.
- **MCP mode: only `mcp__heygen__*` tools.** If translation isn't exposed via MCP yet, fall through to CLI for translation operations specifically. Do not synthesize raw HTTP calls.
- **CLI mode: only `heygen ...` commands.** Run `heygen video-translate --help` and `heygen video-translate <subcommand> --help` to discover arguments. Use `--request-schema` to see the full JSON shape of any create command.
- **Operations below show MCP and CLI side-by-side** — read only the column for your detected mode.

### MCP tool names (MCP mode only)

`create_video_translation` (single language). Multi-language and proofreads are
not yet exposed via MCP — fall through to CLI for those. Run `mcp__heygen__*`
tool listing at session start to confirm what's available; tool surface evolves.

### CLI command groups (CLI mode only)

```
heygen video-translate
├── languages list              # supported target languages
├── create                      # submit a translation job (single or batch)
├── get <id>                    # check status / fetch result
├── list                        # list past translations
├── update                      # update job metadata
├── delete                      # delete a job
└── proofreads
    ├── create                  # extract editable subtitles before final render
    ├── get <id>                # check proofread session status
    ├── srt get <id>            # download the extracted SRT
    ├── srt update <id>         # upload edited SRT
    └── generate <id>           # render the final video from approved SRT
heygen asset create --file <path>   # for local source video uploads (max 32 MB)
```

Every command supports `--help`. Use `--request-schema` on any `create` to see the full JSON body. CLI output: JSON on stdout, `{error:{code,message,hint}}` envelope on stderr, exit codes `0` ok · `1` API · `2` usage · `3` auth · `4` timeout. Add `--wait` on `create` to block until the job completes (default timeout 20m).

📖 **Detailed CLI/MCP error → action mapping → [references/troubleshooting.md](references/troubleshooting.md)**

---

## Default Workflow

The skill runs four phases. Phase 1 (Discovery) is the only place you ask questions. Phase 2 (Pre-flight) is silent. Phase 3 (Submit + Poll) is silent. Phase 4 (Deliver) is one short message.

```
Phase 1 — Discovery       — gather minimum needed inputs from the user
Phase 2 — Pre-flight      — validate language, classify content, set flags
Phase 3 — Submit + Poll   — kick off, background poll, surface only on done/fail
Phase 4 — Deliver         — post the result with one-line summary
```

### Phase 1 — Discovery

Ask only what you don't already have. Communicate in the user's language. **Never run a form.** One or two questions per turn, max.

**Required inputs (block until you have these):**

1. **Source video.** Public URL, local file path, or a HeyGen asset_id from a previous step. If the user hasn't supplied it, ask: *"What's the source video — a URL, file path, or an existing HeyGen asset?"*
2. **Target language(s).** Ask as an open-ended question in the user's language: *"Which language should I translate it into?"* Do NOT present a picker or pre-assigned choices — let the user type freely. They may want one language, multiple, or a region-specific variant. Accept whatever they give and validate against the canonical languages list in Phase 2.

**Important inputs (ask if not provided, with smart defaults):**

3. **Speaker count.** Single speaker is the default and what most users have. Ask once when ambiguous: *"How many distinct speakers are in the video?"* Wrong speaker count is the #1 quality killer — speaker confusion creates voice swaps mid-translation. Don't skip this for multi-person content.
4. **Content type.** You usually don't need to ask — infer from the video and confirm. The five profiles below cover ~95% of cases. Only ask if genuinely ambiguous.
5. **Caption preference.** Default ON for talking-head and corporate; default OFF for podcast/audio-only. If you flip the default, mention it briefly in Phase 4.
6. **Duration flexibility.** Ask: *"Does the translated video need to be exactly the same length as the original, or can it be slightly longer/shorter? Allowing flexibility usually sounds more natural — the translated speech ge