video-gen
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWhen 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 says "生成视频", "做视频", "video generation", "text to video", "视频编辑"
- 用户希望根据文本描述生成AI视频
- 用户希望将静态图片制作成动画(首帧动画)
- 用户有参考图片用于指导视频生成
- 用户希望编辑现有视频(更改风格、背景等)
- 用户说出“生成视频”、“做视频”、“video generation”、“text to video”、“视频编辑”
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
- 用户需要带旁白和AI视觉效果的解说视频(使用)
/explainer - 用户需要将音频/视频转录为文本(使用)
/asr - 用户需要生成图片(使用)
/image-gen
Purpose
功能用途
Generate AI videos using the ListenHub CLI. Supports two 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)
使用ListenHub CLI生成AI视频。支持两大模型系列:
- HappyHorse(默认)——文本转视频、图片转视频、参考图片转视频、视频编辑
- SeeDance——文本转视频、帧模式(首帧+尾帧)、参考模式(图片、视频、音频)
Hard Constraints
硬性约束
- Always check CLI auth following
shared/cli-authentication.md - Follow for CLI execution, errors, and interaction patterns
shared/cli-patterns.md - Always read config following before any interaction
shared/config-pattern.md - Follow for result presentation —
shared/output-mode.mdmode savesdownloadto cwd with dedupe per{slug}.mp4§ Artifact Namingshared/config-pattern.md - Always use for video creation — generation takes minutes
--no-wait --json - Never use to execute CLI commands — always invoke
evaldirectly with proper quotinglistenhub video ...
- 始终遵循检查CLI授权
shared/cli-authentication.md - 遵循执行CLI命令、处理错误和交互流程
shared/cli-patterns.md - 在任何交互前,始终遵循读取配置
shared/config-pattern.md - 遵循展示结果——
shared/output-mode.md模式会将download保存到当前工作目录,并按照{slug}.mp4§ 产物命名规则去重shared/config-pattern.md - 视频创建时始终使用参数——生成过程需要数分钟
--no-wait --json - 绝不要使用执行CLI命令——始终直接调用
eval并正确添加引号listenhub video ...
Model Comparison
模型对比
| Feature | HappyHorse (default) | SeeDance |
|---|---|---|
| Text-to-video | ✅ | ✅ |
| Image-to-video (first-frame) | ✅ | ✅ (+ last-frame) |
| Reference images | ✅ (1–9, with [Image N] prompt syntax) | ✅ |
| Video edit | ✅ | ❌ |
| Reference video | ❌ (use video-edit instead) | ✅ |
| Reference audio | ❌ | ✅ |
| Resolution | 720p, 1080p | 480p, 720p, 1080p |
| Duration range | 3–15s | 4–15s |
| Extra ratios | 4:5, 5:4 | — |
| Prompt length | ≤2500 中文 / ≤5000 非中文 | ≤500 |
| 功能 | HappyHorse(默认) | SeeDance |
|---|---|---|
| 文本转视频 | ✅ | ✅ |
| 图片转视频(首帧) | ✅ | ✅(支持尾帧) |
| 参考图片 | ✅(1–9张,使用[Image N]提示语法) | ✅ |
| 视频编辑 | ✅ | ❌ |
| 参考视频 | ❌(请使用视频编辑功能) | ✅ |
| 参考音频 | ❌ | ✅ |
| 分辨率 | 720p、1080p | 480p、720p、1080p |
| 时长范围 | 3–15秒 | 4–15秒 |
| 额外比例 | 4:5、5:4 | — |
| 提示词长度 | ≤2500个中文 / ≤5000个非中文 | ≤500 |
Step -1: CLI Auth Check + Video Command Gate
步骤-1:CLI授权检查 + 视频命令验证
Follow § Auth Check. If CLI is not installed or not logged in, auto-install and auto-login — never ask the user to run commands manually.
shared/cli-authentication.mdAfter standard auth check, verify the subcommand is available:
videobash
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
fiIf : stop and tell the user:
VIDEO_COMMAND_UNAVAILABLEvideo-gen 需要 listenhub-cli 的最新版本,当前已安装版本不包含 video 命令,请等待新版发布。
遵循 § 授权检查。如果未安装CLI或未登录,自动安装并自动登录——绝不要让用户手动运行命令。
shared/cli-authentication.md完成标准授权检查后,验证子命令是否可用:
videobash
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如果出现:停止操作并告知用户:
VIDEO_COMMAND_UNAVAILABLEvideo-gen 需要 listenhub-cli 的最新版本,当前已安装版本不包含 video 命令,请等待新版发布。
Auth Mode Detection
授权模式检测
The CLI supports two auth modes. Detect which one is active:
bash
undefinedCLI支持两种授权模式。检测当前激活的模式:
bash
undefinedCheck if OpenAPI key is configured
检查是否配置了OpenAPI密钥
OPENAPI_STATUS=$(listenhub openapi config show --json 2>/dev/null)
HAS_OPENAPI=$(echo "$OPENAPI_STATUS" | jq -r '.source // empty')
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"
fiAll subsequent commands use instead of hardcoded . The flags and JSON output format are identical between the two modes.
$CMD_PREFIXlistenhub videoOpenAPI-specific notes:
- OpenAPI mode requires API Key (), configured via
lh_sk_...or envlistenhub openapi config set-keyLISTENHUB_API_KEY - OpenAPI mode does not support flag (video-edit audio control not yet exposed)
--audio-setting - All media inputs must be URLs in OpenAPI mode (no local file upload) — if user provides local paths, inform them: "OpenAPI 模式需要使用公网 URL,请先上传文件后提供链接。"
AUTH=$(listenhub auth status --json 2>/dev/null)
HAS_INTERNAL=$(echo "$AUTH" | jq -r '.authenticated // false')
**优先级:**如果两种模式都已配置,优先使用内部授权(功能更丰富)。设置会话变量:
```bash
if [ "$HAS_INTERNAL" = "true" ]; then
CMD_PREFIX="listenhub video"
elif [ -n "$HAS_OPENAPI" ]; then
CMD_PREFIX="listenhub openapi video"
else
# 两种模式都未配置——触发内部授权登录
listenhub auth login
CMD_PREFIX="listenhub video"
fi后续所有命令都使用,而非硬编码的。两种模式的参数和JSON输出格式完全一致。
$CMD_PREFIXlistenhub videoOpenAPI模式注意事项:
- OpenAPI模式需要API密钥(),可通过
lh_sk_...或环境变量listenhub openapi config set-key配置LISTENHUB_API_KEY - OpenAPI模式不支持参数(视频编辑的音频控制尚未开放)
--audio-setting - OpenAPI模式下所有媒体输入必须为URL(不支持本地文件上传)——如果用户提供本地路径,告知他们:"OpenAPI 模式需要使用公网 URL,请先上传文件后提供链接。"
Step 0: Config Setup
步骤0:配置设置
Follow Step 0 (Zero-Question Boot).
shared/config-pattern.mdIf file doesn't exist — silently create with defaults and proceed:
bash
mkdir -p ".listenhub/video-gen"
echo '{"outputMode":"inline"}' > ".listenhub/video-gen/config.json"
CONFIG_PATH=".listenhub/video-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")Session defaults (not persisted unless user reconfigures):
- model:
happyhorse - resolution:
1080p - ratio:
16:9 - duration:
5
Do NOT ask any setup questions. Proceed directly to the Interaction Flow.
If file exists — read config silently and proceed:
bash
CONFIG_PATH=".listenhub/video-gen/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/video-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")遵循步骤0(零提问启动)。
shared/config-pattern.md如果配置文件不存在——自动创建默认配置并继续:
bash
mkdir -p ".listenhub/video-gen"
echo '{"outputMode":"inline"}' > ".listenhub/video-gen/config.json"
CONFIG_PATH=".listenhub/video-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")会话默认值(除非用户重新配置,否则不持久化):
- model:
happyhorse - resolution:
1080p - ratio:
16:9 - duration:
5
**不要询问任何设置问题。**直接进入交互流程。
如果配置文件存在——静默读取配置并继续:
bash
CONFIG_PATH=".listenhub/video-gen/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/video-gen/config.json"
CONFIG=$(cat "$CONFIG_PATH")Setup Flow (user-initiated reconfigure only)
设置流程(仅用户主动要求重新配置时运行)
Only run when the user explicitly asks to reconfigure. Display current settings:
当前配置 (video-gen):
输出方式: {outputMode}Then ask:
- outputMode: Follow § Setup Flow Question.
shared/output-mode.md
Save immediately:
bash
NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")仅当用户明确要求重新配置时运行。显示当前设置:
当前配置 (video-gen):
输出方式: {outputMode}然后询问:
- outputMode: 遵循§ 设置流程问题。
shared/output-mode.md
立即保存:
bash
NEW_CONFIG=$(echo "$CONFIG" | jq --arg m "$OUTPUT_MODE" '. + {"outputMode": $m}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")Interaction Flow
交互流程
Step 1: Collect Prompt
步骤1:收集提示词
Ask the user for a video description. If they haven't provided one:
描述你想要生成的视频内容。
Free text input. Use as-is — do not modify the prompt unless the user asks for help.
询问用户视频描述。如果用户未提供:
描述你想要生成的视频内容。
接受自由文本输入。直接使用输入内容——除非用户请求帮助,否则不要修改提示词。
Step 2: Mode Routing
步骤2:模式路由
Question: "你有参考素材想提供吗?"
Options:
- "没有,纯文字生成" — Text-to-video mode, skip to Step 4
- "有图片,想做首帧动画" — Image-to-video (first-frame) → Step 3a
- "有参考图片(风格/角色参考)" — Reference-image mode → Step 3b
- "有视频,想编辑/修改" — Video-edit mode → Step 3c问题: "你有参考素材想提供吗?"
选项:
- "没有,纯文字生成" — 文本转视频模式,跳至步骤4
- "有图片,想做首帧动画" — 图片转视频(首帧)→ 步骤3a
- "有参考图片(风格/角色参考)" — 参考图片模式 → 步骤3b
- "有视频,想编辑/修改" — 视频编辑模式 → 步骤3cStep 3a: Image-to-Video (First-Frame)
步骤3a:图片转视频(首帧)
-
first-frame (required): Ask for the image path or URL.
- Supported formats: jpg, jpeg, png, webp
- Local files max 20MB
- Image: width & height ≥ 300px, ratio between 1:2.5 and 2.5:1
-
last-frame (optional, SeeDance only): If model is SeeDance, ask if there is a last-frame image.
Question: "有尾帧图片吗?(仅 SeeDance 支持)"
Options:
- "没有,只用首帧" — Skip last-frame
- "有" — Collect last-frame path/URLAfter collecting, proceed to Step 4.
Note: HappyHorse i2v mode has no parameter — ratio is determined by the input image. SeeDance still accepts .
ratio--ratio-
first-frame(必填):询问图片路径或URL。
- 支持格式:jpg、jpeg、png、webp
- 本地文件最大20MB
- 图片:宽高≥300px,比例在1:2.5到2.5:1之间
-
last-frame(可选,仅SeeDance支持):如果使用SeeDance模型,询问是否有尾帧图片。
问题: "有尾帧图片吗?(仅 SeeDance 支持)"
选项:
- "没有,只用首帧" — 跳过尾帧
- "有" — 收集尾帧路径/URL收集完成后,进入步骤4。
**注意:**HappyHorse的图片转视频模式没有参数——比例由输入图片决定。SeeDance仍支持参数。
ratio--ratioStep 3b: Reference-Image Mode
步骤3b:参考图片模式
Collect reference images (1–9 images required).
Ask for image paths/URLs:
- Supported formats: jpg, jpeg, png, webp
- Max 20MB per file
- HappyHorse: short edge ≥ 400px recommended
HappyHorse prompt syntax: When multiple reference images are provided, the user can use , etc. in the prompt to refer to specific images. Inform the user of this capability.
[Image 1][Image 2]SeeDance additional references (only if model is SeeDance):
- reference-video (optional, max 3): mp4, mov, max 50MB
- reference-audio (optional, max 3): mp3, wav, max 20MB (must pair with image or video)
After collecting, proceed to Step 4.
收集参考图片(需要1–9张)。
询问图片路径/URL:
- 支持格式:jpg、jpeg、png、webp
- 单文件最大20MB
- HappyHorse:建议短边≥400px
**HappyHorse提示词语法:**当提供多张参考图片时,用户可以在提示词中使用、等指代特定图片。告知用户此功能。
[Image 1][Image 2]SeeDance额外参考素材(仅使用SeeDance模型时):
- reference-video(可选,最多3个):mp4、mov,最大50MB
- reference-audio(可选,最多3个):mp3、wav,最大20MB(必须搭配图片或视频)
收集完成后,进入步骤4。
Step 3c: Video-Edit Mode (HappyHorse Only)
步骤3c:视频编辑模式(仅HappyHorse支持)
If model is SeeDance, inform the user: "视频编辑仅 HappyHorse 模型支持,已自动切换。" and set model to .
happyhorse-
video (required): Ask for the video path or URL.
- Supported formats: mp4, mov (H.264 recommended)
- Duration: 3–60s (output capped at 15s)
- Max 100MB, ≥ 360px short edge, ≤ 4096px long edge
- URL only (no base64)
-
reference-image (optional, 0–5): Ask if there are reference images for the edit.
-
audio-setting:
Question: "音频如何处理?"
Options:
- "自动(模型决定)" — audio_setting: auto
- "保留原声" — audio_setting: originAfter collecting, proceed to Step 4.
Note: Video-edit has no or parameters — output matches input video.
ratioduration如果使用SeeDance模型,告知用户:"视频编辑仅 HappyHorse 模型支持,已自动切换。" 并将模型设置为。
happyhorse-
video(必填):询问视频路径或URL。
- 支持格式:mp4、mov(推荐H.264编码)
- 时长:3–60秒(输出时长上限15秒)
- 最大100MB,短边≥360px,长边≤4096px
- 仅支持URL(不支持base64)
-
reference-image(可选,0–5张):询问是否有用于编辑的参考图片。
-
audio-setting:
问题: "音频如何处理?"
选项:
- "自动(模型决定)" — audio_setting: auto
- "保留原声" — audio_setting: origin收集完成后,进入步骤4。
**注意:**视频编辑模式没有或参数——输出与输入视频一致。
ratiodurationStep 4: Optional Parameter Adjustment
步骤4:可选参数调整
Read session defaults and present. Adjust display based on mode:
For text-to-video and reference-image modes:
Question: "要调整生成参数吗?当前默认配置:\n 模型: happyhorse\n 分辨率: 1080p\n 比例: 16:9\n 时长: 5 秒"
Options:
- "用默认,直接生成" — Proceed to Step 5
- "我要调整参数" — Ask each parameter belowFor image-to-video (first-frame) mode:
Question: "要调整生成参数吗?当前默认配置:\n 模型: happyhorse\n 分辨率: 1080p\n 时长: 5 秒"
Options:
- "用默认,直接生成" — Proceed to Step 5
- "我要调整参数" — Ask each parameter belowFor video-edit mode: Skip Step 4 entirely — no adjustable generation params (only resolution).
If adjusting, ask each parameter one at a time:
Model:
Question: "模型?"
Options:
- "happyhorse(推荐)" — Higher quality, video-edit support
- "doubao-seedance-2-pro" — SeeDance pro, supports last-frame & audio ref
- "doubao-seedance-2-fast" — SeeDance fastResolution:
Question: "分辨率?"
Options:
- "1080p(推荐)" — High quality (default for HappyHorse)
- "720p" — Standard quality
- "480p" — Low quality (SeeDance only)Constraint: if user selects 480p and model is , inform "HappyHorse 不支持 480p,已切换为 720p。"
Constraint: if user selects 1080p and model is , silently upgrade to and inform "1080p 需要使用 pro 模型,已自动切换。"
happyhorsedoubao-seedance-2-fastdoubao-seedance-2-proAspect ratio (not shown for i2v or video-edit):
Question: "画面比例?"
Options:
- "16:9" — Landscape, widescreen
- "9:16" — Portrait, phone screen
- "1:1" — Square
- "Other" — 4:3, 3:4, 4:5, 5:4 (4:5/5:4 HappyHorse only)Duration:
Question: "时长?"
Options:
- "5 秒(推荐)" — Standard
- "8 秒" — Medium
- "10 秒" — Long
- "Other" — Custom (HappyHorse: 3–15, SeeDance: 4–15)Seed (optional): Only ask if the user mentions wanting to reproduce a result. Otherwise skip.
读取会话默认值并展示。根据模式调整展示内容:
文本转视频和参考图片模式:
问题: "要调整生成参数吗?当前默认配置:\n 模型: happyhorse\n 分辨率: 1080p\n 比例: 16:9\n 时长: 5 秒"
选项:
- "用默认,直接生成" — 进入步骤5
- "我要调整参数" — 逐个询问以下参数图片转视频(首帧)模式:
问题: "要调整生成参数吗?当前默认配置:\n 模型: happyhorse\n 分辨率: 1080p\n 时长: 5 秒"
选项:
- "用默认,直接生成" — 进入步骤5
- "我要调整参数" — 逐个询问以下参数**视频编辑模式:**完全跳过步骤4——没有可调整的生成参数(仅分辨率可选)。
如果需要调整,逐个询问参数:
模型:
问题: "模型?"
选项:
- "happyhorse(推荐)" — 画质更高,支持视频编辑
- "doubao-seedance-2-pro" — SeeDance专业版,支持尾帧和音频参考
- "doubao-seedance-2-fast" — SeeDance快速版分辨率:
问题: "分辨率?"
选项:
- "1080p(推荐)" — 高画质(HappyHorse默认)
- "720p" — 标准画质
- "480p" — 低画质(仅SeeDance支持)约束:如果用户选择480p且模型为,告知用户"HappyHorse 不支持 480p,已切换为 720p。"
约束:如果用户选择1080p且模型为,自动升级为并告知用户"1080p 需要使用 pro 模型,已自动切换。"
happyhorsedoubao-seedance-2-fastdoubao-seedance-2-pro画面比例(图片转视频或视频编辑模式不展示):
问题: "画面比例?"
选项:
- "16:9" — 横屏,宽屏
- "9:16" — 竖屏,手机屏幕
- "1:1" — 正方形
- "Other" — 4:3、3:4、4:5、5:4(4:5/5:4仅HappyHorse支持)时长:
问题: "时长?"
选项:
- "5 秒(推荐)" — 标准时长
- "8 秒" — 中等时长
- "10 秒" — 较长时长
- "Other" — 自定义(HappyHorse:3–15秒,SeeDance:4–15秒)Seed(可选):仅当用户提到需要复现结果时询问,否则跳过。
Step 5: Cost Estimate + Execution Confirmation
步骤5:成本估算 + 执行确认
Build and run the estimate command (no — direct invocation):
evalbash
ESTIMATE=$($CMD_PREFIX estimate \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--ratio "16:9" \
--json 2>/tmp/lh-err)
EXIT_CODE=$?For video-edit mode — add and :
--has-video-input--input-video-duration- If user provided a URL: ask duration or use ffprobe if local
- Local files: detect with ffprobe as best-effort:
If ffprobe is unavailable or fails, skip estimate — show "预估不可用" in the summary.bash
INPUT_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "/path/to/ref.mp4" 2>/dev/null | cut -d. -f1)
bash
ESTIMATE=$($CMD_PREFIX estimate \
--model "happyhorse" \
--resolution "1080p" \
--has-video-input \
--input-video-duration "$INPUT_DUR" \
--json 2>/tmp/lh-err)
EXIT_CODE=$?Parse estimate result:
bash
if [ $EXIT_CODE -eq 0 ]; then
TOKENS=$(echo "$ESTIMATE" | jq -r '.tokens // empty')
CREDITS=$(echo "$ESTIMATE" | jq -r '.credits // empty')
else
TOKENS=""
CREDITS=""
fi
rm -f /tmp/lh-errPresent confirmation summary:
Ready to generate video:
Prompt: {prompt text}
模式: {纯文字 / 首帧动画 / 参考图 / 视频编辑}
模型: {model}
分辨率: {resolution}
比例: {ratio or "跟随输入"}
时长: {duration} 秒 {or "跟随输入"}
素材: {无 / first-frame: path / references: N 个 / video: path}
预估费用: {tokens} tokens / {credits} credits ← or "预估不可用" if estimate failed
确认生成?Wait for explicit confirmation before executing.
构建并运行估算命令(不要使用——直接调用):
evalbash
ESTIMATE=$($CMD_PREFIX estimate \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--ratio "16:9" \
--json 2>/tmp/lh-err)
EXIT_CODE=$?视频编辑模式——添加和参数:
--has-video-input--input-video-duration- 如果用户提供URL:询问时长,或如果是本地文件则使用ffprobe检测
- 本地文件:尽量使用ffprobe检测:
如果ffprobe不可用或检测失败,跳过估算——在汇总中显示"预估不可用"。bash
INPUT_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "/path/to/ref.mp4" 2>/dev/null | cut -d. -f1)
bash
ESTIMATE=$($CMD_PREFIX estimate \
--model "happyhorse" \
--resolution "1080p" \
--has-video-input \
--input-video-duration "$INPUT_DUR" \
--json 2>/tmp/lh-err)
EXIT_CODE=$?解析估算结果:
bash
if [ $EXIT_CODE -eq 0 ]; then
TOKENS=$(echo "$ESTIMATE" | jq -r '.tokens // empty')
CREDITS=$(echo "$ESTIMATE" | jq -r '.credits // empty')
else
TOKENS=""
CREDITS=""
fi
rm -f /tmp/lh-err展示确认汇总:
准备生成视频:
提示词: {prompt text}
模式: {纯文字 / 首帧动画 / 参考图 / 视频编辑}
模型: {model}
分辨率: {resolution}
比例: {ratio or "跟随输入"}
时长: {duration} 秒 {or "跟随输入"}
素材: {无 / first-frame: 路径 / references: N 个 / video: 路径}
预估费用: {tokens} tokens / {credits} credits ← 如果估算失败则显示"预估不可用"
确认生成?等待用户明确确认后再执行。
Execution & Polling
执行与轮询
Submit (foreground)
提交(前台)
Invoke directly — never build a command string with . Substitute the actual collected values into the command. is either (internal auth) or (API Key auth), determined in Step -1.
$CMD_PREFIX createeval$CMD_PREFIXlistenhub videolistenhub openapi videoText-to-video:
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?Image-to-video (first-frame):
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--first-frame "/path/to/first.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?Reference-image mode:
bash
RESULT=$($CMD_PREFIX create \
--prompt "[Image 1]中的角色在城市中行走" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--reference-image "/path/to/ref1.png" \
--reference-image "/path/to/ref2.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?Video-edit mode (HappyHorse):
bash
RESULT=$($CMD_PREFIX create \
--prompt "将背景替换为星空" \
--model "happyhorse" \
--resolution "1080p" \
--reference-video "/path/to/input.mp4" \
--audio-setting "origin" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?SeeDance frame mode (with optional last-frame):
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 8 \
--first-frame "/path/to/first.png" \
--last-frame "/path/to/last.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?SeeDance reference mode (images, videos, audio):
bash
RESULT=$($CMD_PREFIX create \
--prompt "保持参考视频的运镜和色调风格" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 5 \
--reference-video "/path/to/ref.mp4" \
--reference-image "/path/to/ref.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?Flags only when needed:
- — only if user disabled audio (SeeDance only)
--no-generate-audio - — only if user specified a seed
--seed 12345 - — video-edit mode, keep original audio
--audio-setting origin - — only for reference-video URLs (local files auto-detected by CLI)
--input-video-duration N
Error check:
bash
if [ $EXIT_CODE -ne 0 ]; then
ERROR=$(cat /tmp/lh-err)
case $EXIT_CODE in
2) echo "Auth error" ;;
*) echo "Error: $ERROR" ;;
esac
rm -f /tmp/lh-err
# Handle error per shared/cli-patterns.md
fi
rm -f /tmp/lh-err
TASK_ID=$(echo "$RESULT" | jq -r '.taskId')Tell the user the task is submitted: "任务已提交,ID: {TASK_ID},正在生成中…"
直接调用——绝不要用构建命令字符串。将收集到的实际值代入命令。是步骤-1中确定的(内部授权)或(API密钥授权)。
$CMD_PREFIX createeval$CMD_PREFIXlistenhub videolistenhub openapi video文本转视频:
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?图片转视频(首帧):
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--first-frame "/path/to/first.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?参考图片模式:
bash
RESULT=$($CMD_PREFIX create \
--prompt "[Image 1]中的角色在城市中行走" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--reference-image "/path/to/ref1.png" \
--reference-image "/path/to/ref2.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?视频编辑模式(HappyHorse):
bash
RESULT=$($CMD_PREFIX create \
--prompt "将背景替换为星空" \
--model "happyhorse" \
--resolution "1080p" \
--reference-video "/path/to/input.mp4" \
--audio-setting "origin" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?SeeDance帧模式(可选尾帧):
bash
RESULT=$($CMD_PREFIX create \
--prompt "用户的视频描述" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 8 \
--first-frame "/path/to/first.png" \
--last-frame "/path/to/last.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?SeeDance参考模式(图片、视频、音频):
bash
RESULT=$($CMD_PREFIX create \
--prompt "保持参考视频的运镜和色调风格" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 5 \
--reference-video "/path/to/ref.mp4" \
--reference-image "/path/to/ref.png" \
--no-wait --json 2>/tmp/lh-err)
EXIT_CODE=$?仅在需要时添加参数:
- — 仅当用户禁用音频时(仅SeeDance支持)
--no-generate-audio - — 仅当用户指定seed时
--seed 12345 - — 视频编辑模式,保留原音频
--audio-setting origin - — 仅用于参考视频URL(本地文件由CLI自动检测)
--input-video-duration N
错误检查:
bash
if [ $EXIT_CODE -ne 0 ]; then
ERROR=$(cat /tmp/lh-err)
case $EXIT_CODE in
2) echo "Auth error" ;;
*) echo "Error: $ERROR" ;;
esac
rm -f /tmp/lh-err
# 按照shared/cli-patterns.md处理错误
fi
rm -f /tmp/lh-err
TASK_ID=$(echo "$RESULT" | jq -r '.taskId')告知用户任务已提交:"任务已提交,ID: {TASK_ID},正在生成中…"
Poll (background)
轮询(后台)
Run with and (21 minutes):
run_in_background: truetimeout: 1260000bash
TASK_ID="{taskId from above}"
for i in $(seq 1 120); do
RESULT=$($CMD_PREFIX get "$TASK_ID" --json 2>/dev/null)
STATUS=$(echo "$RESULT" | jq -r '.status')
case "$STATUS" in
success) echo "$RESULT"; exit 0 ;;
failed) echo "FAILED: $RESULT" >&2; exit 1 ;;
*) sleep 10 ;;
esac
done
echo "TIMEOUT" >&2; exit 2Status flow: → → → |
pendinggeneratinguploadingsuccessfailed设置和(21分钟)运行:
run_in_background: truetimeout: 1260000bash
TASK_ID="{taskId from above}"
for i in $(seq 1 120); do
RESULT=$($CMD_PREFIX get "$TASK_ID" --json 2>/dev/null)
STATUS=$(echo "$RESULT" | jq -r '.status')
case "$STATUS" in
success) echo "$RESULT"; exit 0 ;;
failed) echo "FAILED: $RESULT" >&2; exit 1 ;;
*) sleep 10 ;;
esac
done
echo "TIMEOUT" >&2; exit 2状态流程: → → → |
pendinggeneratinguploadingsuccessfailedResult Presentation
结果展示
On success, parse the result (note: returns , not ):
get.id.taskIdbash
VIDEO_URL=$(echo "$RESULT" | jq -r '.videoUrl')
DURATION=$(echo "$RESULT" | jq -r '.duration')
RESOLUTION=$(echo "$RESULT" | jq -r '.resolution')
RATIO=$(echo "$RESULT" | jq -r '.ratio')
SEED=$(echo "$RESULT" | jq -r '.seed')
CREDITS=$(echo "$RESULT" | jq -r '.creditCharged')Read from config. Follow for behavior.
OUTPUT_MODEshared/output-mode.mdinlinebothPresent:
视频已生成!
URL: {videoUrl}
时长: {duration}s
分辨率: {resolution}
比例: {ratio}
Seed: {seed}
消耗: {creditCharged} creditsdownloadbothshared/config-pattern.mdbash
SLUG="{topic-slug}" # e.g. "赛博朋克城市夜景"
NAME="${SLUG}.mp4"
BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
curl -sS -o "$NAME" "$VIDEO_URL"Present:
已保存到当前目录:
{NAME}On failure: Display error and suggest checking prompt or parameters.
On timeout: Tell the user to check later:
生成超时。你可以稍后用(或listenhub video get {taskId} --json)查询结果。listenhub openapi video get {taskId} --json
成功时,解析结果(注意:返回,而非):
get.id.taskIdbash
VIDEO_URL=$(echo "$RESULT" | jq -r '.videoUrl')
DURATION=$(echo "$RESULT" | jq -r '.duration')
RESOLUTION=$(echo "$RESULT" | jq -r '.resolution')
RATIO=$(echo "$RESULT" | jq -r '.ratio')
SEED=$(echo "$RESULT" | jq -r '.seed')
CREDITS=$(echo "$RESULT" | jq -r '.creditCharged')从配置中读取。遵循的行为规则。
OUTPUT_MODEshared/output-mode.mdinlineboth展示内容:
视频已生成!
URL: {videoUrl}
时长: {duration}秒
分辨率: {resolution}
比例: {ratio}
Seed: {seed}
消耗: {creditCharged} creditsdownloadbothshared/config-pattern.mdbash
SLUG="{topic-slug}" # 例如:"赛博朋克城市夜景"
NAME="${SLUG}.mp4"
BASE="${NAME%.*}"; EXT="${NAME##*.}"; i=2
while [ -e "$NAME" ]; do NAME="${BASE}-${i}.${EXT}"; i=$((i+1)); done
curl -sS -o "$NAME" "$VIDEO_URL"展示内容:
已保存到当前目录:
{NAME}失败时:展示错误信息并建议检查提示词或参数。
超时时:告知用户稍后查询:
生成超时。你可以稍后用(或listenhub video get {taskId} --json)查询结果。listenhub openapi video get {taskId} --json
Querying Past Tasks
查询历史任务
Users can ask to check a previous task or list recent tasks:
bash
undefined用户可以查询特定任务或列出最近任务:
bash
undefinedGet a specific task
查询特定任务
$CMD_PREFIX get "{taskId}" --json
$CMD_PREFIX get "{taskId}" --json
List recent tasks
列出最近任务
$CMD_PREFIX list --json
Present results using the same format as the success output above.$CMD_PREFIX list --json
使用与成功输出相同的格式展示结果。Error Handling
错误处理
Reuse standard error codes:
shared/cli-patterns.md| Code | Meaning | Action |
|---|---|---|
| 0 | Success | Parse JSON output |
| 1 | General error | Display stderr to user |
| 2 | Auth error | Internal: re-login via |
| 3 | Timeout | Suggest checking task status later |
复用的标准错误代码:
shared/cli-patterns.md| 代码 | 含义 | 操作 |
|---|---|---|
| 0 | 成功 | 解析JSON输出 |
| 1 | 通用错误 | 向用户展示stderr内容 |
| 2 | 授权错误 | 内部授权:通过 |
| 3 | 超时 | 建议用户稍后检查任务状态 |
API Reference
API参考
- CLI authentication:
shared/cli-authentication.md - CLI execution patterns:
shared/cli-patterns.md - Config pattern:
shared/config-pattern.md - Output mode:
shared/output-mode.md - HappyHorse API:
references/happyhorse-api.md
- CLI授权:
shared/cli-authentication.md - CLI执行模式:
shared/cli-patterns.md - 配置模式:
shared/config-pattern.md - 输出模式:
shared/output-mode.md - HappyHorse API:
references/happyhorse-api.md
Composability
组合性
| Direction | Description |
|---|---|
| Routed when user mentions video generation via |
| Same routing via |
| Independent terminal skill, no downstream dependencies |
| 方向 | 描述 |
|---|---|
| 当用户通过 |
| 通过 |
| 独立终端技能,无下游依赖 |
Examples
示例
Text-to-video (HappyHorse)
文本转视频(HappyHorse)
"帮我生成一个视频:赛博朋克城市夜景"
bash
listenhub video create \
--prompt "赛博朋克城市夜景" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--no-wait --json"帮我生成一个视频:赛博朋克城市夜景"
bash
listenhub video create \
--prompt "赛博朋克城市夜景" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--no-wait --jsonImage-to-video (HappyHorse)
图片转视频(HappyHorse)
"把这张图片变成动画视频" + 提供图片路径
bash
listenhub video create \
--prompt "将静态场景转化为流畅动画" \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--first-frame "/path/to/scene.png" \
--no-wait --json"把这张图片变成动画视频" + 提供图片路径
bash
listenhub video create \
--prompt "将静态场景转化为流畅动画" \
--model "happyhorse" \
--resolution "1080p" \
--duration 5 \
--first-frame "/path/to/scene.png" \
--no-wait --jsonReference-Image Mode (HappyHorse)
参考图片模式(HappyHorse)
"参考这两张图片的风格,生成一段视频"
bash
listenhub video create \
--prompt "[Image 1]中的角色在[Image 2]的场景中漫步" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--reference-image "/path/to/character.png" \
--reference-image "/path/to/scene.png" \
--no-wait --json"参考这两张图片的风格,生成一段视频"
bash
listenhub video create \
--prompt "[Image 1]中的角色在[Image 2]的场景中漫步" \
--model "happyhorse" \
--resolution "1080p" \
--ratio "16:9" \
--duration 5 \
--reference-image "/path/to/character.png" \
--reference-image "/path/to/scene.png" \
--no-wait --jsonVideo Edit (HappyHorse)
视频编辑(HappyHorse)
"把这个视频的背景换成星空"
bash
listenhub video create \
--prompt "将背景替换为深邃的星空,保持人物动作不变" \
--model "happyhorse" \
--resolution "1080p" \
--reference-video "/path/to/input.mp4" \
--audio-setting "origin" \
--no-wait --json"把这个视频的背景换成星空"
bash
listenhub video create \
--prompt "将背景替换为深邃的星空,保持人物动作不变" \
--model "happyhorse" \
--resolution "1080p" \
--reference-video "/path/to/input.mp4" \
--audio-setting "origin" \
--no-wait --jsonSeeDance Frame Mode
SeeDance帧模式
"用首帧和尾帧生成过渡动画"
bash
listenhub video create \
--prompt "从白天自然过渡到夜晚" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 8 \
--first-frame "/path/to/day.png" \
--last-frame "/path/to/night.png" \
--no-wait --json"用首帧和尾帧生成过渡动画"
bash
listenhub video create \
--prompt "从白天自然过渡到夜晚" \
--model "doubao-seedance-2-pro" \
--resolution "720p" \
--ratio "16:9" \
--duration 8 \
--first-frame "/path/to/day.png" \
--last-frame "/path/to/night.png" \
--no-wait --json