video-gen

Files (4)

• SKILL.md
• happyhorse-api.md · references/
• pixverse-api.md · references/
• shared

SKILL.md (first lines)

## When to Use

- User wants to generate an AI video from a text description
- User wants to animate a still image (first-frame)
- User has reference images to guide video generation
- User wants to edit an existing video (change style, background, etc.)
- User wants to lip-sync a video to audio or TTS (PixVerse only) — "对口型", "口型同步"
- User wants a marketing ad / promo mix video (PixVerse agent)
- User says "生成视频", "做视频", "video generation", "text to video", "视频编辑", "pixverse", "口型"

## When NOT to Use

- User wants an explainer video with narration and AI visuals (use `/explainer`)
- User wants to transcribe audio/video to text (use `/asr`)
- User wants to generate an image (use `/image-gen`)

## Purpose

Generate AI videos using the ListenHub CLI. Supports three model families:

- **HappyHorse** (default) — text-to-video, image-to-video, reference-image-to-video, video-edit
- **SeeDance** — text-to-video, frame mode (first + last frame), reference mode (images, videos, audio)
- **PixVerse** — nine atomic capabilities via the Agent API (text_to_video, image_to_video, transition, multi_transition, fusion, restyle, mimic, **lip_sync**, agent). The only family that supports lip sync. OpenAPI-only, URL/ID based, and uses its own `pixverse` CLI namespace.

## Hard Constraints

- Always check CLI auth following `shared/cli-authentication.md`
- Follow `shared/cli-patterns.md` for CLI execution, errors, and interaction patterns
- Always read config following `shared/config-pattern.md` before any interaction
- Follow `shared/output-mode.md` for result presentation — `download` mode saves `{slug}.mp4` to cwd with dedupe per `shared/config-pattern.md` § Artifact Naming
- Always use `--no-wait --json` for video creation — generation takes minutes
- Never use `eval` to execute CLI commands — always invoke `listenhub video ...` directly with proper quoting

<HARD-GATE>
Use the AskUserQuestion tool for every multiple-choice step — do NOT print options
as plain text. Ask one question at a time. Wait for the user's answer before
proceeding to the next step. After all parameters are collected, summarize the
choices and ask the user to confirm. Do NOT call the video generation command
until the user has explicitly confirmed.
</HARD-GATE>

## Model Comparison

| Feature | HappyHorse (default) | SeeDance | PixVerse |
|---------|---------------------|----------|----------|
| Text-to-video | ✅ | ✅ | ✅ (`text_to_video`) |
| Image-to-video (first-frame) | ✅ | ✅ (+ last-frame) | ✅ (`image_to_video`) |
| Reference images | ✅ (1–9, with [Image N] prompt syntax) | ✅ | ✅ (`fusion`, `@refName` syntax) |
| Transition (first→last) | ❌ | ✅ (frame mode) | ✅ (`transition` / `multi_transition`) |
| Video edit | ✅ | ❌ | ❌ |
| Restyle | ❌ | ❌ | ✅ (`restyle`) |
| Mimic (motion transfer) | ❌ | ❌ | ✅ (`mimic`, locked 720p) |
| **Lip sync** | ❌ | ❌ | ✅ (`lip_sync`, audio or TTS) |
| Marketing agent (ad/promo) | ❌ | ❌ | ✅ (`agent`: ad_master / promo_mix) |
| Reference video | ❌ (use video-edit instead) | ✅ | ✅ (mimic / lip_sync source) |
| Reference audio | ❌ | ✅ | ✅ (lip_sync) |
| Resolution / quality | 720p, 1080p | 480p, 720p, 1080p | 360p, 540p, 720p, 1080p |
| Duration range | 3–15s | 4–15s | 1–60s (agent: 20/30/60) |
| Aspect ratios | 16:9, 9:16, 1:1, 4:3, 3:4, 4:5, 5:4 | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 | 9:16, 16:9, 1:1, 4:3, 3:4 |
| Prompt length | ≤2500 中文 / ≤5000 非中文 | ≤500 | ≤2048 |
| Rate limit | 5 RPM | 5 RPM | 5 RPM |
| CLI namespace | `… video create` | `… video create` | `… video pixverse generate` (OpenAPI only) |

**Lip sync is PixVerse-only** — HappyHorse and SeeDance do not support it. Mimic, restyle, fusion, transition, and the marketing agent are also PixVerse-exclusive.

## Step -1: CLI Auth Check + Video Command Gate

Follow `shared/cli-authentication.md` § Auth Check. If CLI is not installed or not logged in, auto-install and auto-login — never ask the user to run commands manually.

After standard auth check, verify the `video` subcommand is available:

```bash
if ! listenhub video --help &>/dev/null; then
  npm install -g @marswave/listenhub-cli@latest
  if ! listenhub video --help &>/dev/null; then
    echo "VIDEO_COMMAND_UNAVAILABLE"
  fi
fi
```

If `VIDEO_COMMAND_UNAVAILABLE`: stop and tell the user:

> video-gen 需要 listenhub-cli 的最新版本，当前已安装版本不包含 video 命令，请等待新版发布。

### Auth Mode Detection

The CLI supports two auth modes. Detect which one is active:

```bash
# Check if OpenAPI key is configured
OPENAPI_STATUS=$(listenhub openapi config show --json 2>/dev/null)
HAS_OPENAPI=$(echo "$OPENAPI_STATUS" | jq -r '.source // empty')

# Check if internal auth is active
AUTH=$(listenhub auth status --json 2>/dev/null)
HAS_INTERNAL=$(echo "$AUTH" | jq -r '.authenticated // false')
```

**Priority:** If both are configured, prefer internal auth (richer features). Set a session variable:

```bash
if [ "$HAS_INTERNAL" = "true" ]; then
  CMD_PREFIX="listenhub video"
elif [ -n "$HAS_OPENAPI" ]; then
  CMD_PREFIX="listenhub openapi video"
else
  # Neither configured — trigger internal auth login
  listenhub auth login
  CMD_PREFIX="listenhub video"
fi
```

All subsequent commands use `$CMD_PREFIX` instead of hardcoded `listenhub video`. The flags and JSON output format are identical between the two modes.

**OpenAPI-specific notes:**
- OpenAPI mode requires API Key (`lh_sk_...`), configured via `listenhub openapi config set-key` or env `LISTENHUB_API_KEY`
- OpenAPI mode does not support `--audio-setting` flag (video-edit audio control not yet exposed)
- Standard `listenhub openapi video create` accepts local image/video/audio paths or URLs. Local files are uploaded by the CLI before task creation; local images also get width/height/size metadata automatically.
- Remote Seedance image URLs still need explicit `--*-meta` values because the CLI does not download remote assets to infer dimensions.

From marswaveai/skills, MIT.

More from marswaveai/skills