---
id: iamzhihuix/happy-claude-skills/happy-video-gen
version: "549b4c7c"
license: MIT
install: manual
updated: 2026-04-20
---

# happy-video-gen — Create short videos from text descriptions or still images by routing to your choice of 10 providers—OpenAI Sora, Google Veo, Runway, Pika, Luma, and others—all through a single command-line interface. Supports text-to-video, image-to-video, and optional last-frame control where available, with configurable duration, aspect ratio, and resolution.

Publisher: iamzhihuix · Stars: 305 · Updated: 2026-04-20

Install (manual): `git clone https://github.com/iamzhihuix/happy-claude-skills`

## SKILL.md

# happy-video-gen

Generates short videos (text-to-video or image-to-video) across 10 providers through one CLI: `bun scripts/main.ts ...`. All providers are async — the CLI submits a job, polls until the provider finishes, then downloads the MP4 / WebM.

## Quick usage

```bash
# Text-to-video
bun scripts/main.ts --prompt "camera slowly pushes into a calico cat on grass" --ar 16:9 --duration 5 --video ./out.mp4

# Image-to-video (first frame)
bun scripts/main.ts --prompt "subtle zoom, leaves swaying" --image ./keyframe.png --duration 5 --video ./out.mp4

# Image-to-video with last-frame control (provider-dependent)
bun scripts/main.ts --prompt "seamless morph" --image ./a.png --last-frame ./b.png --video ./out.mp4
```

## When to invoke this skill

- User asks to generate / create / make / synthesize a video from text.
- User asks to animate a still image, or provides a first-frame path.
- User names any video model family (Sora, Veo, Runway, Kling, Wan, Seedance, Hailuo, Pika, Dream Machine, Vidu).

Route to `happy-dreamina` if the user explicitly mentions 即梦 / Jimeng / dreamina CLI. Route to `happy-image-gen` if the user actually wants a still image.

## Step 0: Preflight (BLOCKING)

1. **Locate EXTEND.md** (same resolution order as happy-image-gen):
   - `./.happy-skills/happy-video-gen/EXTEND.md`
   - `$XDG_CONFIG_HOME/happy-skills/happy-video-gen/EXTEND.md`
   - `~/.happy-skills/happy-video-gen/EXTEND.md`

   If none, run `bun scripts/main.ts --setup` and walk the user through `references/config/first-time-setup.md`.

2. **Verify one provider has credentials.** Check env vars in the order the CLI auto-detects (see providers.md). Do not proceed without one usable provider.

3. **Verify Bun**. Fall back to `npx -y bun` if missing.

4. **Warn about cost.** Video generation is 10–100× more expensive per call than images. If the user asks for HD 1080P / 10-second clips, confirm before firing — show them the expected provider cost bracket from `references/providers.md`.

## Step 1: Choose provider

Preference order:

1. `--provider <id>` explicitly passed.
2. EXTEND.md `default_provider`.
3. Auto-detect from env vars: `fal > ark > minimax > runway > luma > pika > vidu > google > bailian > openai`.

Pick by strength of the actual task:

- **Chinese prompts / Chinese text in frame** → `ark` (Seedance) or `bailian` (Wanx).
- **Photorealistic portraits** → `google` (Veo 3) or `runway` (Gen-4).
- **Anime / stylized** → `fal` (Kling) or `luma`.
- **Cheap draft** → `ark` Seedance Lite, `fal` Kling v2.5 turbo, `vidu` Q1.
- **Voice-synced dialogue video** (if applicable) → `google` Veo 3, `openai` Sora 2.

## Step 2: Fill parameters

- **`--prompt`**: always double-quote.
- **`--image <path>`** / **`--last-frame <path>`**: local paths, will be base64-encoded as data URIs automatically. `--last-frame` only accepted by Luma and a few FAL endpoints.
- **`--duration <seconds>`**: 5 is universal default. Caps: Sora-2 / Kling up to 10; Seedance up to 10; Luma up to 9.
- **`--ar <ratio>`**: `16:9 / 9:16 / 1:1 / 4:3 / 3:4`. See `references/aspect_ratio_map.md` for provider-specific quirks.
- **`--resolution`**: `480p / 720p / 1080p`. Not all providers honour it; most cap at 720p on cheap tiers.
- **`--poll-timeout`**: default 600s (10 min). Increase for 1080P or >5s clips.

## Step 3: Submit and wait

```bash
bun scripts/main.ts \
  --prompt "..." \
  --video ./out.mp4 \
  --provider ark \
  --duration 5 \
  --ar 16:9 \
  --resolution 720p
```

While waiting, do **not** fire another job on the same provider — concurrency caps on cheap tiers are strict (often 1). On success the CLI writes the MP4 and reports size + path. JSON output:

```json
{ "success": true, "provider": "ark", "model": "doubao-seedance-1-0-lite-t2v-250408", "video": "/abs/out.mp4", "size_bytes": 4823456, "format": "mp4" }
```

## Step 4: Timeouts and recovery

If polling exceeds `--poll-timeout`, the CLI throws with the provider-specific external id (task id / job id / operation name / request id). Capture it from stderr and resume later with provider-specific tooling. See `references/async-protocol.md` for the per-provider id format and manual resume commands.

## References

- **`references/providers.md`** — all 10 providers with env vars, defaults, cost notes, feature matrix.
- **`references/async-protocol.md`** — external id format per provider + how to resume a stuck task.
- **`references/aspect_ratio_map.md`** — `--ar` mapping per provider.
- **`references/error_codes.md`** — common errors and fixes.
- **`references/config/first-time-setup.md`** — setup walkthrough.
- **`references/config/extend-schema.md`** — EXTEND.md schema.
- **`assets/EXTEND.template.md`** — config template.


[View on SkillFed](https://skillfed.io/iamzhihuix/happy-claude-skills/happy-video-gen) · [View on GitHub](https://github.com/iamzhihuix/happy-claude-skills)