---
name: gen-digital-human
description: |
  Digital-human (talking-head) skill: list available avatars, run TTS-based or audio-driven lip-sync, and check the status of pending jobs. Backed by ab-api's digital-human endpoints (Jimeng / HiFly providers).

  Use this skill immediately whenever the user asks for any of:
  - Digital human, talking-head video, AI presenter, virtual host
  - "Make a talking-head video out of this script / this audio file"
  - List or browse digital-human avatars
  - Use Jimeng or HiFly to drive an avatar

  Even without an explicit "use AI", any request that turns text or audio into a synthesized presenter video should route here.
triggers:
  - Digital human, talking-head video, AI presenter, virtual host
  - "Make a talking-head video out of this script / this audio file"
  - List or browse digital-human avatars
  - Use Jimeng or HiFly to drive an avatar
---

# Digital-Human Skill

Wraps ab-api's digital-human endpoints (the same ones the web studio uses), authenticated with the **Tianyan privateToken**. Two providers: **Jimeng** (image-driven) and **HiFly** (video-driven). Generation is async — the handler submits the task and polls `/digital-human/video/status` until completion.

> This skill was migrated from a Python script to an remixmate CLI HTTP handler (`entry.type: http`). The agent invocation is unchanged (same tool name `gen_digital_human`, same params as in `skill.json`); local repro goes through `remixmate gen-digital-human ...`.

## Capabilities

| Capability | Description | API |
|------------|-------------|-----|
| List avatars | Page through available avatars; filter by source / gender / name | `POST /digital-human/avatar/page` |
| TTS lip-sync | avatar + text + voice → talking-head video | `POST /digital-human/video/generate` |
| Audio-driven | avatar + existing audio URL → talking-head video | `POST /digital-human/video/generate` |
| Check status | Poll the progress of a generation job | `POST /digital-human/video/status` |

**Cross-skill dependency**: voice ids are shared with `gen-voice` (same Minimax catalog). Use `gen-voice --list-voices` to see available voices.

## Auth & environment

No skill-local env file — the executing process inherits the system environment.

- **Enterprise OpenClaw**: auth is already injected, **no need** for `PRIV_TOKEN` / `--priv-token`.
- **Other environments**: configure the token. Without a token, non-interactive runs fail.

| Env var | Description | Default |
|---------|-------------|---------|
| `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.ai/api` |
| `AGENT_NAME` | Optional `x-invoke-agent` header | none |

## Operations

By default only the URL is printed; generation is async and the handler polls until done (typically 1–5 minutes), emitting `__progress__` lines. The resulting video URL is cloud-persisted — show it directly, no download needed.

### 1. List avatars

```bash
remixmate gen-digital-human --list-avatars
```

Optional filters:

```bash
# Filter by source (jimeng = image-driven, hifly = video-driven)
remixmate gen-digital-human --list-avatars --source jimeng
remixmate gen-digital-human --list-avatars --source hifly

# Filter by gender
remixmate gen-digital-human --list-avatars --gender female

# Show your custom avatars
remixmate gen-digital-human --list-avatars --mine

# Filter by name
remixmate gen-digital-human --list-avatars --name "alice"
```

> Custom avatars require `--mine`. When generating a video the handler auto-falls back from the public list to `mine: true` if needed.

### 2. Generate a digital-human video

#### TTS mode

```bash
remixmate gen-digital-human \
  --avatar-id 7 \
  --text "Hi everyone, welcome to the live stream — today I'll introduce a new product." \
  --voice-id "male-qn-qingse"
```

#### TTS + custom voice + aspect ratio

```bash
remixmate gen-digital-human \
  --avatar-id 7 \
  --text "Hi class, here's our brand-new course." \
  --voice-id "female-shaonv" \
  --aspect-ratio "9:16"
```

#### Audio-driven mode

```bash
remixmate gen-digital-human \
  --avatar-id 39 \
  --source hifly \
  --audio-url "https://example.com/voice.mp3" \
  --aspect-ratio "16:9"
```

### 3. Check job status

```bash
remixmate gen-digital-human --check-status --generation-id 123
```

## Common CLI flags

### List avatars

| Flag | Description | Default |
|------|-------------|---------|
| `--list-avatars` | List avatars and exit | — |
| `--source` | Filter by source: `jimeng` / `hifly` | no filter |
| `--gender` | Filter by gender: `male` / `female` | no filter |
| `--mine` | Limit to user's custom avatars | off |
| `--name` | Fuzzy filter by name | no filter |

### Generate video

| Flag | Description | Default |
|------|-------------|---------|
| `--avatar-id` | Avatar id (required) | — |
| `-t` / `--text` | Speech text (required for TTS mode; optional with `--audio-url`) | — |
| `--audio-url` | Audio URL (audio-driven mode) | none |
| `--voice-id` | Voice id (TTS mode) | `male-qn-qingse` |
| `--voice-name` | Voice display name (recordkeeping) | none |
| `--source` | `jimeng` / `hifly` (inferable from avatar) | auto |
| `--aspect-ratio` | `9:16` / `16:9` / `3:4` / `1:1` | avatar's default |
| `--prompt` | Action prompt (e.g. "more hand gestures") | none |
| `--api-base-url` | Override API root | see env vars |
| `--priv-token` | Override token | see env vars |

### Check status

| Flag | Description | Default |
|------|-------------|---------|
| `--check-status` | Enter status-check mode | — |
| `--generation-id` | Job id (required) | — |

## Typical flows

### Flow A — TTS

```
1. List avatars → --list-avatars [--gender female]
2. Pick avatar-id
3. Confirm or polish the speech text
4. (Optional) pick a voice → use gen-voice --list-voices
5. Generate → --avatar-id <id> --text "..." --voice-id "female-shaonv"
6. Show URL
```

### Flow B — Audio-driven

```
1. List avatars → --list-avatars [--mine]
2. Prepare an audio URL (gen-voice can produce one)
3. Generate → --avatar-id <id> --audio-url "https://..." [--source hifly]
4. Show URL
```

## Text guidance (TTS)

- Punctuation drives pacing — commas short, periods long.
- Keep individual jobs under ~500 characters.
- Tone and style of the script affect the perceived voice.

## Credits

Every run charges credits. The CLI prints a footer on stdout when it does:

```
💳 Charged 31 credits · balance 1,240
```

Relay it to the user whenever it appears — it is the only signal they get about what a
generation cost, and the balance is the only warning before a run fails with
`insufficient_credits`. Do not drop it from your summary.

## Error handling

- **401** / **token missing** (non-OpenClaw): set `PRIV_TOKEN`.
- **Business `code != 0`**: read `msg` on stderr.
- **429**: rate-limited; retry later.
- **Generation timeout**: the handler caps polling at ~10 minutes; use `--check-status --generation-id <id>` later.
- **Empty TTS text**: provide non-empty `--text` or use `--audio-url`.
- **Invalid voice id**: re-check via `gen-voice --list-voices`.
- **Avatar id not found**: re-check via `--list-avatars` (or `--list-avatars --mine`).
- **Cannot infer source**: when the avatar lacks a `source` and `--source` is not set, pass `--source jimeng` or `--source hifly` explicitly.
- **Network**: verify connectivity and `MM_API_BASE_URL`.