video-gen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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 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
    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>
  • 始终遵循
    shared/cli-authentication.md
    检查CLI授权
  • 遵循
    shared/cli-patterns.md
    执行CLI命令、处理错误和交互流程
  • 在任何交互前,始终遵循
    shared/config-pattern.md
    读取配置
  • 遵循
    shared/output-mode.md
    展示结果——
    download
    模式会将
    {slug}.mp4
    保存到当前工作目录,并按照
    shared/config-pattern.md
    § 产物命名规则去重
  • 视频创建时始终使用
    --no-wait --json
    参数——生成过程需要数分钟
  • 绝不要使用
    eval
    执行CLI命令——始终直接调用
    listenhub video ...
    并正确添加引号
<HARD-GATE> 每一步多选操作都要使用AskUserQuestion工具——不要以纯文本形式打印选项。一次只问一个问题。等待用户回答后再进行下一步。收集所有参数后,汇总用户的选择并请求确认。在用户明确确认前,不要调用视频生成命令。 </HARD-GATE>

Model Comparison

模型对比

FeatureHappyHorse (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
Resolution720p, 1080p480p, 720p, 1080p
Duration range3–15s4–15s
Extra ratios4:5, 5:4
Prompt length≤2500 中文 / ≤5000 非中文≤500
功能HappyHorse(默认)SeeDance
文本转视频
图片转视频(首帧)✅(支持尾帧)
参考图片✅(1–9张,使用[Image N]提示语法)
视频编辑
参考视频❌(请使用视频编辑功能)
参考音频
分辨率720p、1080p480p、720p、1080p
时长范围3–15秒4–15秒
额外比例4:5、5:4
提示词长度≤2500个中文 / ≤5000个非中文≤500

Step -1: CLI Auth Check + Video Command Gate

步骤-1:CLI授权检查 + 视频命令验证

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 命令,请等待新版发布。
遵循
shared/cli-authentication.md
§ 授权检查。如果未安装CLI或未登录,自动安装并自动登录——绝不要让用户手动运行命令。
完成标准授权检查后,验证
video
子命令是否可用:
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
如果出现
VIDEO_COMMAND_UNAVAILABLE
:停止操作并告知用户:
video-gen 需要 listenhub-cli 的最新版本,当前已安装版本不包含 video 命令,请等待新版发布。

Auth Mode Detection

授权模式检测

The CLI supports two auth modes. Detect which one is active:
bash
undefined
CLI支持两种授权模式。检测当前激活的模式:
bash
undefined

Check 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"
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)
  • 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
后续所有命令都使用
$CMD_PREFIX
,而非硬编码的
listenhub video
。两种模式的参数和JSON输出格式完全一致。
OpenAPI模式注意事项:
  • 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
shared/config-pattern.md
Step 0 (Zero-Question Boot).
If 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")
遵循
shared/config-pattern.md
步骤0(零提问启动)。
如果配置文件不存在——自动创建默认配置并继续:
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:
  1. outputMode: Follow
    shared/output-mode.md
    § Setup Flow Question.
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}
然后询问:
  1. 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
  - "有视频,想编辑/修改" — 视频编辑模式 → 步骤3c

Step 3a: Image-to-Video (First-Frame)

步骤3a:图片转视频(首帧)

  1. 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
  2. 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/URL
After collecting, proceed to Step 4.
Note: HappyHorse i2v mode has no
ratio
parameter — ratio is determined by the input image. SeeDance still accepts
--ratio
.
  1. first-frame(必填):询问图片路径或URL。
    • 支持格式:jpg、jpeg、png、webp
    • 本地文件最大20MB
    • 图片:宽高≥300px,比例在1:2.5到2.5:1之间
  2. last-frame(可选,仅SeeDance支持):如果使用SeeDance模型,询问是否有尾帧图片。
问题: "有尾帧图片吗?(仅 SeeDance 支持)"
选项:
  - "没有,只用首帧" — 跳过尾帧
  - "有" — 收集尾帧路径/URL
收集完成后,进入步骤4。
**注意:**HappyHorse的图片转视频模式没有
ratio
参数——比例由输入图片决定。SeeDance仍支持
--ratio
参数。

Step 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
[Image 1]
,
[Image 2]
etc. in the prompt to refer to specific images. Inform the user of this capability.
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
.
  1. 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)
  2. reference-image (optional, 0–5): Ask if there are reference images for the edit.
  3. audio-setting:
Question: "音频如何处理?"
Options:
  - "自动(模型决定)" — audio_setting: auto
  - "保留原声" — audio_setting: origin
After collecting, proceed to Step 4.
Note: Video-edit has no
ratio
or
duration
parameters — output matches input video.
如果使用SeeDance模型,告知用户:"视频编辑仅 HappyHorse 模型支持,已自动切换。" 并将模型设置为
happyhorse
  1. video(必填):询问视频路径或URL。
    • 支持格式:mp4、mov(推荐H.264编码)
    • 时长:3–60秒(输出时长上限15秒)
    • 最大100MB,短边≥360px,长边≤4096px
    • 仅支持URL(不支持base64)
  2. reference-image(可选,0–5张):询问是否有用于编辑的参考图片。
  3. audio-setting:
问题: "音频如何处理?"
选项:
  - "自动(模型决定)" — audio_setting: auto
  - "保留原声" — audio_setting: origin
收集完成后,进入步骤4。
**注意:**视频编辑模式没有
ratio
duration
参数——输出与输入视频一致。

Step 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 below
For image-to-video (first-frame) mode:
Question: "要调整生成参数吗?当前默认配置:\n  模型: happyhorse\n  分辨率: 1080p\n  时长: 5 秒"
Options:
  - "用默认,直接生成" — Proceed to Step 5
  - "我要调整参数" — Ask each parameter below
For 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 fast
Resolution:
Question: "分辨率?"
Options:
  - "1080p(推荐)" — High quality (default for HappyHorse)
  - "720p" — Standard quality
  - "480p" — Low quality (SeeDance only)
Constraint: if user selects 480p and model is
happyhorse
, inform "HappyHorse 不支持 480p,已切换为 720p。" Constraint: if user selects 1080p and model is
doubao-seedance-2-fast
, silently upgrade to
doubao-seedance-2-pro
and inform "1080p 需要使用 pro 模型,已自动切换。"
Aspect 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
,告知用户"HappyHorse 不支持 480p,已切换为 720p。" 约束:如果用户选择1080p且模型为
doubao-seedance-2-fast
,自动升级为
doubao-seedance-2-pro
并告知用户"1080p 需要使用 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
eval
— direct invocation):
bash
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
--has-video-input
and
--input-video-duration
:
  • If user provided a URL: ask duration or use ffprobe if local
  • Local files: detect with ffprobe as best-effort:
    bash
    INPUT_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "/path/to/ref.mp4" 2>/dev/null | cut -d. -f1)
    If ffprobe is unavailable or fails, skip estimate — show "预估不可用" in the summary.
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-err
Present 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.
构建并运行估算命令(不要使用
eval
——直接调用):
bash
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检测:
    bash
    INPUT_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "/path/to/ref.mp4" 2>/dev/null | cut -d. -f1)
    如果ffprobe不可用或检测失败,跳过估算——在汇总中显示"预估不可用"。
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
$CMD_PREFIX create
directly — never build a command string with
eval
. Substitute the actual collected values into the command.
$CMD_PREFIX
is either
listenhub video
(internal auth) or
listenhub openapi video
(API Key auth), determined in Step -1.
Text-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:
  • --no-generate-audio
    — only if user disabled audio (SeeDance only)
  • --seed 12345
    — only if user specified a seed
  • --audio-setting origin
    — video-edit mode, keep original audio
  • --input-video-duration N
    — only for reference-video URLs (local files auto-detected by CLI)
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},正在生成中…"
直接调用
$CMD_PREFIX create
——绝不要用
eval
构建命令字符串。将收集到的实际值代入命令。
$CMD_PREFIX
是步骤-1中确定的
listenhub video
(内部授权)或
listenhub openapi video
(API密钥授权)。
文本转视频:
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=$?
仅在需要时添加参数:
  • --no-generate-audio
    — 仅当用户禁用音频时(仅SeeDance支持)
  • --seed 12345
    — 仅当用户指定seed时
  • --audio-setting origin
    — 视频编辑模式,保留原音频
  • --input-video-duration N
    — 仅用于参考视频URL(本地文件由CLI自动检测)
错误检查:
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
run_in_background: true
and
timeout: 1260000
(21 minutes):
bash
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
Status flow:
pending
generating
uploading
success
|
failed
设置
run_in_background: true
timeout: 1260000
(21分钟)运行:
bash
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
状态流程:
pending
generating
uploading
success
|
failed

Result Presentation

结果展示

On success, parse the result (note:
get
returns
.id
, not
.taskId
):
bash
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
OUTPUT_MODE
from config. Follow
shared/output-mode.md
for behavior.
inline
or
both
: Display video URL and metadata.
Present:
视频已生成!

  URL: {videoUrl}
  时长: {duration}s
  分辨率: {resolution}
  比例: {ratio}
  Seed: {seed}
  消耗: {creditCharged} credits
download
or
both
: Save to current working directory with a topic-based slug per
shared/config-pattern.md
§ Artifact Naming:
bash
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
,而非
.taskId
):
bash
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_MODE
。遵循
shared/output-mode.md
的行为规则。
inline
both
模式
:展示视频URL和元数据。
展示内容:
视频已生成!

  URL: {videoUrl}
  时长: {duration}秒
  分辨率: {resolution}
  比例: {ratio}
  Seed: {seed}
  消耗: {creditCharged} credits
download
both
模式
:按照
shared/config-pattern.md
§ 产物命名规则,将视频保存到当前工作目录,生成基于主题的文件名:
bash
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
undefined

Get 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
shared/cli-patterns.md
standard error codes:
CodeMeaningAction
0SuccessParse JSON output
1General errorDisplay stderr to user
2Auth errorInternal: re-login via
listenhub auth login
. OpenAPI: check API Key via
listenhub openapi config show
3TimeoutSuggest checking task status later
复用
shared/cli-patterns.md
的标准错误代码:
代码含义操作
0成功解析JSON输出
1通用错误向用户展示stderr内容
2授权错误内部授权:通过
listenhub auth login
重新登录。OpenAPI:通过
listenhub openapi config show
检查API密钥
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

组合性

DirectionDescription
listenhub
router →
video-gen
Routed when user mentions video generation via
/listenhub
listenhub-cli
router →
video-gen
Same routing via
/listenhub-cli
video-gen
→ (none)
Independent terminal skill, no downstream dependencies
方向描述
listenhub
路由 →
video-gen
当用户通过
/listenhub
提及视频生成时触发路由
listenhub-cli
路由 →
video-gen
通过
/listenhub-cli
触发相同路由
video-gen
→ (无)
独立终端技能,无下游依赖

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

Image-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 --json

Reference-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 --json

Video 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 --json

SeeDance 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