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

# 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

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:

{ "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.