happy-video-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过一个CLI工具

bun scripts/main.ts ...

，基于10家提供商生成短视频（文本转视频或图像转视频）。所有提供商均支持异步操作——CLI提交任务，轮询直至提供商完成，然后下载MP4/WebM格式文件。

Quick usage

快速使用

bash

undefined

bash

undefined

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

undefined

bun scripts/main.ts --prompt "seamless morph" --image ./a.png --last-frame ./b.png --video ./out.mp4

undefined

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.

用户要求根据文本生成/创建/制作/合成视频。
用户要求将静态图像动画化，或提供首帧路径。
用户提及任何视频模型系列（Sora、Veo、Runway、Kling、Wan、Seedance、海螺、Pika、Dream Machine、Vidu）。

若用户明确提及即梦/Jimeng/dreamina CLI，则转至

happy-dreamina

；若用户实际需要静态图像，则转至

happy-image-gen

。

Step 0: Preflight (BLOCKING)

步骤0：预检查（阻塞操作）

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

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.
Verify Bun. Fall back to
```
npx -y bun
```
if missing.
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
```
.

定位EXTEND.md（优先级与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

若找不到该文件，运行

bun scripts/main.ts --setup

，并引导用户查看

references/config/first-time-setup.md

完成设置。

验证至少一家提供商有凭证：按照CLI自动检测的顺序检查环境变量（详见providers.md）。若无可用提供商，请勿继续。
验证Bun环境：若未安装Bun，可回退使用
```
npx -y bun
```
。
提醒成本问题：视频生成每次调用的成本是图像生成的10-100倍。若用户要求生成1080P高清或时长超过10秒的视频片段，执行前需确认——向用户展示
```
references/providers.md
```
中对应提供商的预期成本区间。

Step 1: Choose provider

步骤1：选择提供商

Preference order:

```
--provider <id>
```
explicitly passed.
EXTEND.md
```
default_provider
```
.

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.

优先级顺序：

显式传入
```
--provider <id>
```
参数。
EXTEND.md中配置的
```
default_provider
```
。

自动从环境变量检测：

fal > ark > minimax > runway > luma > pika > vidu > google > bailian > openai

。

可根据任务特性选择：

中文提示/画面含中文文本 →
```
ark
```
（Seedance）或
```
bailian
```
（万相）。
写实风格人像 →
```
google
```
（Veo 3）或
```
runway
```
（Gen-4）。
动漫/风格化内容 →
```
fal
```
（Kling）或
```
luma
```
。
低成本草稿 →
```
ark
```
Seedance Lite、
```
fal
```
Kling v2.5 turbo、
```
vidu
```
Q1。
语音同步对话视频（若支持）→
```
google
```
Veo 3、
```
openai
```
Sora 2。

Step 2: Fill parameters

步骤2：填充参数

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

--prompt
：需始终使用双引号包裹。
--image <路径>
/ --last-frame <路径>
：本地路径，将自动编码为base64格式的Data URI。
```
--last-frame
```
仅被Luma和部分FAL端点支持。
--duration <秒数>
：通用默认值为5秒。上限：Sora-2/Kling最长10秒；Seedance最长10秒；Luma最长9秒。

--ar <比例>
：

16:9 / 9:16 / 1:1 / 4:3 / 3:4

。提供商特定注意事项详见

references/aspect_ratio_map.md

。

--resolution
：
```
480p / 720p / 1080p
```
。并非所有提供商都支持该参数；多数低成本套餐上限为720p。
--poll-timeout
：默认600秒（10分钟）。生成1080P或时长超过5秒的视频时可延长此时间。

Step 3: Submit and wait

步骤3：提交并等待

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" }

bash

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

等待期间，请勿在同一提供商上提交另一个任务——低成本套餐的并发限制严格（通常为1）。成功后，CLI将写入MP4文件并报告文件大小和路径。JSON输出示例：

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

步骤4：超时与恢复

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.

若轮询超时（超过

--poll-timeout

设置），CLI将抛出包含提供商特定外部ID（任务ID/作业ID/操作名称/请求ID）的错误。从stderr中捕获该ID，之后可使用提供商特定工具恢复任务。各提供商的ID格式及手动恢复命令详见

references/async-protocol.md

。

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.

references/providers.md
— 包含10家提供商的环境变量配置、默认设置、成本说明及功能矩阵。
references/async-protocol.md
— 各提供商的外部ID格式及如何恢复卡住的任务。
references/aspect_ratio_map.md
— 各提供商的
```
--ar
```
参数映射。
references/error_codes.md
— 常见错误及修复方案。
references/config/first-time-setup.md
— 首次设置向导。
references/config/extend-schema.md
— EXTEND.md文件的 schema 规范。
assets/EXTEND.template.md
— 配置模板。