OpenAPI 命令

每个 `listenhub openapi` 命令的参考——面向脚本与 CI 的 API key 命名空间。

listenhub openapi 命名空间下的所有命令都用 API key 鉴权，而非 OAuth 登录。在你能掌控环境、并希望使用长期凭证而非交互式浏览器流程的服务器和 CI 中使用它。

开始之前，先让 key 可用——设置 LISTENHUB_API_KEY，或用 listenhub openapi config set-key 存储它。凭证存放位置以及 CLI 的解析顺序见认证。

export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en

本页约定

该命名空间下的每个命令都遵循相同行为：

输出。 默认人类可读文本；--json / -j 将机器可读的 JSON 打印到 stdout（错误输出到 stderr）。可用管道接入 jq。
异步创建。 启动生成的命令会先提交任务，再轮询直到任务到达终态，并打印 spinner。轮询间隔为 10 秒。--no-wait 立即返回 ID 并以 0 退出；--timeout <seconds> 限制等待时长（默认值因命令而异，各分组下有注明）。
退出码。 0 成功，1 错误，2 鉴权，3 超时。
积分。 生成会消耗积分。创建前用对应的 estimate 命令估算，用 listenhub openapi subscription 查看余额。切勿假设固定费用。

每个命令都接受 --help / -h。运行 listenhub openapi <group> <command> --help 可查看你所安装版本的确切参数。

config

管理存储的 API key。CLI 先读 LISTENHUB_API_KEY，再读 set-key 写入的文件。

命令	说明
`config set-key`	提示输入 key 并存储到 `~/.config/listenhub/openapi.json`（权限 `0600`）。key 必须以 `lh_sk_` 开头。
`config show`	显示已配置的 key（脱敏）及其来源（`env` 或 `file`）。支持 `--json`。未配置时以 `1` 退出。
`config clear`	删除存储的 key 文件。

listenhub openapi config set-key
listenhub openapi config show --json

speakers

列出你账户可用的音色。表格中的 ID 列就是你传给创建命令的 speakerId。

命令	选项	说明
`speakers list`	`--language <lang>`、`--json`	列出音色，可按语言过滤。

listenhub openapi speakers list --language en

打印一张包含 Name、ID、Gender、Language 的表。

tts、audio-speech、speech

三种把文本转为语音的方式。前两者把二进制音频流式写入文件；第三种返回托管的音频 URL。

命令	说明
`tts`	文本转语音，流式写入本地文件。
`audio-speech`	与 `tts` 相同，走兼容 OpenAI `/v1/audio/speech` 的路由。
`speech`	创建语音并返回托管的 `audioUrl`（附带时长、积分，以及可用时的字幕）。

tts 与 audio-speech 共享以下选项：

选项	默认值	说明
`--text <text>`	必填	待转换的文本。
`--voice <speakerId>`	必填	音色 ID。
`--output <file>`	必填	输出文件路径。
`--format <format>`	`mp3`	`mp3`、`opus`、`aac`、`flac`、`wav`、`pcm` 之一。

speech 选项：

选项	说明
`--script <content>`	脚本文本（必填）。
`--speaker-id <id>`	音色 ID（必填）。
`--json`、`-j`	输出 JSON。

# 把 MP3 流式写入磁盘
listenhub openapi tts \
  --text "Welcome to ListenHub." \
  --voice <speaker-id> \
  --output welcome.mp3

# 改为获取托管音频 URL
listenhub openapi speech --script "Welcome to ListenHub." --speaker-id <speaker-id>

flow-speech

Flow Speech 把素材或脚本转为带旁白的节目。创建命令轮询直到 processStatus 为 success；--timeout 默认 300 秒。

命令	说明
`flow-speech create`	从 `--source-url` / `--source-text` 创建节目。
`flow-speech get <episodeId>`	获取节目详情。
`flow-speech tts`	直接从脚本创建节目（不做素材抽取）。
`flow-speech text-stream <episodeId>`	通过 SSE 流式输出生成的文本。

flow-speech create 选项：

选项	默认值	说明
`--source-url <url>`	—	素材 URL。可重复。
`--source-text <text>`	—	素材文本。可重复。
`--speaker-id <id>`	必填	音色 ID。可重复。至少需要一个。
`--mode <mode>`	`smart`	`smart` 或 `direct`。
`--lang <lang>`	自动	语言代码。
`--no-wait`	—	返回节目 ID 而不轮询。
`--timeout <seconds>`	`300`	轮询超时。
`--json`、`-j`	—	输出 JSON。

至少需要一个 --source-url 或 --source-text。

flow-speech tts 选项：

选项	默认值	说明
`--script <content>`	必填	脚本内容。可重复。至少一个。
`--speaker-id <id>`	必填	音色 ID。可重复。至少一个。
`--title <title>`	—	节目标题。
`--no-wait`、`--timeout <seconds>`（`300`）、`--json`	—	同上。

脚本与音色按位置配对：第一个 --script 用第一个 --speaker-id，依此类推；脚本多于音色时，复用第一个音色。

flow-speech text-stream <episodeId> 需要 --event <event>，取值 script 或 outline。它把原始 SSE 流写入 stdout。

# 从一个素材 URL，双音色
listenhub openapi flow-speech create \
  --source-url "https://example.com/article" \
  --speaker-id <host-id> \
  --speaker-id <guest-id>

# 直接从脚本生成
listenhub openapi flow-speech tts \
  --script "Hello and welcome." --speaker-id <host-id> \
  --script "Glad to be here." --speaker-id <guest-id> \
  --title "Episode 1"

podcast

生成播客节目。你可以一步生成文本与音频，也可以拆成两步：先生成文本内容，审阅或流式查看后，再生成音频。创建命令的 --timeout 默认 300 秒。

命令	说明
`podcast create`	从 `--query` 和/或素材生成完整节目（文本 + 音频）。
`podcast get <episodeId>`	获取节目详情。
`podcast text-content`	仅生成脚本，不生成音频。轮询直到 `contentStatus` 为 `text-success`。
`podcast generate-audio <episodeId>`	为已有文本节目生成音频。轮询直到 `contentStatus` 为 `audio-success`。
`podcast text-stream <episodeId>`	通过 SSE 流式输出生成的文本。

podcast create 选项：

选项	默认值	说明
`--query <text>`	—	节目的主题或提示词。
`--source-url <url>`	—	素材 URL。可重复。
`--source-text <text>`	—	素材文本。可重复。
`--speaker-id <id>`	必填	音色 ID。可重复。至少一个。传多个生成多音色节目。
`--mode <mode>`	—	生成模式。
`--lang <lang>`	自动	语言代码。
`--no-wait`、`--timeout <seconds>`（`300`）、`--json`	—	标准异步参数。

podcast text-content 采用相同的素材与音色选项（--query、--source-url、--source-text、--speaker-id、--mode）外加异步参数。--query、--source-url、--source-text 中至少需要一个。

podcast text-stream <episodeId> 需要 --event <event>，取值 script 或 outline。

# 一步到位：文本 + 音频
listenhub openapi podcast create \
  --query "AI agent trends in 2026" \
  --speaker-id <host-id> \
  --mode quick

# 两步：先文本，再音频
ID=$(listenhub openapi podcast text-content \
  --query "Weekly recap" --speaker-id <host-id> --no-wait -j | jq -r '.episodeId')
listenhub openapi podcast text-stream "$ID" --event script
listenhub openapi podcast generate-audio "$ID"

storybook

Storybook 生成解说与幻灯片节目，可选附带视频。创建轮询直到 processStatus 为 success；--timeout 默认 300 秒。

命令	说明
`storybook create`	从素材创建节目。
`storybook get <episodeId>`	获取节目详情。
`storybook generate-video <episodeId>`	为节目启动视频生成。

storybook create 选项：

选项	默认值	说明
`--source-url <url>`	—	素材 URL。可重复。
`--source-text <text>`	—	素材文本。可重复。
`--speaker-id <id>`	—	音色 ID。可重复。可选。
`--skip-audio`	关	不生成音频。
`--style <style>`	—	Storybook 风格。
`--mode <mode>`	`info`	`info`、`story`、`slides` 之一。
`--lang <lang>`	自动	语言代码。
`--no-wait`、`--timeout <seconds>`（`300`）、`--json`	—	标准异步参数。

listenhub openapi storybook create \
  --source-url "https://example.com/explainer" \
  --mode slides --skip-audio

image

从提示词生成 AI 图像，可选用参考图作为条件。--reference 同时接受本地文件路径与 URL；本地文件会被读取并内联发送，URL 则按引用传递。

选项	说明
`--prompt <text>`	图像描述（必填）。
`--provider <provider>`	提供方名称（必填）。
`--model <model>`	模型名称。
`--size <size>`	`1K`、`2K`、`4K` 之一。
`--ratio <ratio>`	`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9` 之一。
`--reference <path-or-url>`	参考图，本地路径或 URL。可重复。
`--json`、`-j`	输出 JSON。

listenhub openapi image create \
  --provider <provider> \
  --prompt "A neon-lit city skyline at dusk" \
  --ratio 16:9 --size 2K

video

AI 视频生成。本分组有两套接口：通用 video 命令（由文本/图像/参考驱动）和 video pixverse 子命令（PixVerse 能力 API）。两者都轮询直到 status 为 success，--timeout 默认 1200 秒，且都接受 24 位十六进制任务 ID。

命令	说明
`video create`	创建一个生成任务。
`video get <taskId>`	获取任务详情。
`video list`	列出任务。
`video estimate`	创建前估算积分。
`video pixverse generate`	创建一个 PixVerse 任务。
`video pixverse estimate`	估算 PixVerse 任务的积分。

video create

prompt 必填，其余选项用于选择输入模式。帧模式（--first-frame / --last-frame）与参考模式（--reference-image / --reference-video / --reference-audio）互斥。

选项	默认值	说明
`--prompt <text>`	必填	视频描述 / 提示词。
`--first-frame <url>`	—	首帧图像 URL。
`--last-frame <url>`	—	尾帧图像 URL。需配合 `--first-frame`。
`--reference-image <url>`	—	参考图 URL。可重复，最多 9。
`--reference-video <url>`	—	参考视频 URL。可重复，最多 3。需配合 `--input-video-duration`。
`--reference-audio <url>`	—	参考音频 URL。可重复，最多 3。需配合 `--reference-image` 或 `--reference-video`。
`--input-video-duration <seconds>`	—	输入视频时长，`2`–`15`。与 `--reference-video` 同用时必填。
`--model <model>`	—	模型名称，例如 `doubao-seedance-2-pro`。
`--resolution <res>`	—	`480p`、`720p`、`1080p` 之一。
`--ratio <ratio>`	—	`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9` 之一。
`--duration <seconds>`	—	输出时长，`4`–`15`。
`--no-generate-audio`	默认开	关闭音频生成。
`--seed <number>`	—	随机种子，`-1` 到 `4294967295`。
`--no-wait`、`--timeout <seconds>`（`1200`）、`--json`	—	标准异步参数。

# 文本转视频
listenhub openapi video create \
  --prompt "A timelapse of clouds over a mountain range" \
  --model doubao-seedance-2-pro \
  --resolution 1080p --duration 8

# 首帧/尾帧插值
listenhub openapi video create \
  --prompt "Smooth morph between the two frames" \
  --first-frame "https://example.com/a.jpg" \
  --last-frame "https://example.com/b.jpg"

video list 选项：--page <n>（默认 1）、--page-size <n>（默认 20）、--status <status>（pending、generating、uploading、success、failed 之一）、--json。

video estimate 需要 --model、--resolution、--duration，并接受 --ratio、--has-video-input、--input-video-duration（设置了 --has-video-input 时必填）：

listenhub openapi video estimate \
  --model doubao-seedance-2-pro --resolution 1080p --duration 8

video pixverse

PixVerse 提供原子化的生成能力外加一个营销 agent。用 --capability 选择其一：

Capability	作用
`text_to_video`	从文本提示词生成。
`image_to_video`	让静态图像动起来。
`transition`	在两个素材之间过渡。
`multi_transition`	跨多个素材过渡。
`fusion`	将多个输入融合为一段片段。
`restyle`	对已有 PixVerse 视频重新风格化。
`mimic`	模仿参考的动作/风格。
`lip_sync`	由音频或 TTS 驱动口型。
`agent`	营销 agent（`ad_master`、`promo_mix`）。

共享枚举：

Model（--model）：pixverse、v6、v5、v4.5（默认 pixverse）。
Language / 区域（--language）：zh、en（默认 en）。
Quality（--quality）：360p、540p、720p、1080p（默认 720p）。
Aspect ratio（--aspect-ratio）：9:16、16:9、1:1、4:3、3:4（默认 16:9）。
Agent type（--agent-type，配合 --capability agent）：ad_master、promo_mix。

video pixverse generate 选项：

选项	默认值	说明
`--capability <capability>`	必填	上述能力之一。
`--model <model>`	`pixverse`	模型。
`--language <lang>`	`en`	服务区域。
`--prompt <text>`	—	提示词，最多 2048 字符。
`--quality <quality>`	`720p`	输出质量。
`--aspect-ratio <ratio>`	`16:9`	宽高比。
`--duration <seconds>`	`5`	整数 `1`–`60`。
`--source-task-id <id>`	—	复用此前成功的 PixVerse 任务（用于 `restyle` / `lip_sync`）。
`--image <url[:duration]>`	—	图像素材，可加 `:duration` 后缀。可重复，最多 10。
`--video <url[:duration]>`	—	视频素材，可加 `:duration` 后缀。可重复，最多 2。
`--audio <url[:duration]>`	—	音频素材，可加 `:duration` 后缀。可重复，最多 1。
`--agent-type <type>`	—	`ad_master` 或 `promo_mix`（配合 `--capability agent`）。
`--source-video-id <id>`	—	PixVerse 源视频 id（`restyle`）。
`--restyle-id <id>`	—	PixVerse restyle id（`restyle`）。
`--lip-sync-tts`	关	启用 lip-sync TTS（`--capability lip_sync`）。
`--lip-sync-speaker-id <id>`	—	lip-sync TTS 音色 id。
`--lip-sync-content <text>`	—	lip-sync TTS 内容。
`--pixverse-json <json>`	—	逃生舱：嵌套 `pixverse` 对象的原始 JSON。与各参数派生字段合并；参数优先。
`--no-wait`、`--timeout <seconds>`（`1200`）、`--json`	—	标准异步参数。

素材类参数接受可选的尾部 :duration（秒）——例如 https://example.com/clip.mp4:5。只有尾部的 :<integer> 才会被当作时长，因此自带冒号的 URL 是安全的。

# 由 TTS 驱动口型
listenhub openapi video pixverse generate \
  --capability lip_sync \
  --video "https://example.com/face.mp4" \
  --lip-sync-tts \
  --lip-sync-speaker-id <speaker-id> \
  --lip-sync-content "Hi, here's our product update."

# 营销 agent
listenhub openapi video pixverse generate \
  --capability agent \
  --agent-type ad_master \
  --prompt "30-second ad for a noise-cancelling headset" \
  --image "https://example.com/product.jpg"

video pixverse estimate 接受 --capability（必填），外加 --model、--language、--quality、--duration、--agent-type：

listenhub openapi video pixverse estimate \
  --capability text_to_video --quality 1080p --duration 5

music

AI 音乐生成，由 Mureka 提供。异步命令（generate、remix、instrumental、soundtrack、track）轮询直到 status 为 success；--timeout 默认 600 秒。分析类命令（recognize、describe、stem）同步运行。

命令	说明
`music generate`	从提示词和/或歌词生成。
`music remix [audio]`	用新歌词翻唱已有歌曲。
`music instrumental`	生成独立的纯音乐。
`music soundtrack`	从图像或视频生成音乐。
`music track [audio]`	生成单条乐器或人声轨道。
`music recognize`	从音频识别带时间戳的歌词。
`music describe`	分析音频：描述、标签、流派、乐器。
`music stem`	把音频分离成多个 stem，返回下载 URL。
`music list`	列出音乐任务。
`music get <taskId>`	获取任务详情。

各生成命令的 model 取值：auto、mureka-7.6、mureka-8、mureka-9、mureka-o2。

music generate 选项：

选项	说明
`--prompt <text>`	音乐描述。`--prompt` 与 `--lyrics` 至少需要一个。
`--lyrics <text>`	歌词。
`--style <text>`	音乐风格 / 情绪。
`--title <text>`	曲目标题。
`--model <model>`	上述 model 取值之一。
`--instrumental`	仅纯音乐，无人声。
`--vocal-id <id>`	可复用的人声 id。
`--no-wait`、`--timeout <seconds>`（`600`）、`--json`	标准异步参数。

music remix [audio] 以位置参数传入音频文件，或用 --audio-url <url>、--provider-song-id <id>——三者恰选其一。需要 --lyrics 与 --prompt。

music instrumental 需要 --prompt 与 --reference-audio <file>（mp3/m4a，最大 10MB）恰选其一；接受 --model。

music soundtrack 需要 --image <file> 与 --video <file> 恰选其一；接受 --prompt 与 --model。

music track [audio] 以位置参数传入音频文件，或用 --provider-song-id <id>（恰选其一）。需要 --generate-type（Vocals、Instrumental、Drums、Bass、Guitar……）与 --prompt；当 --generate-type 为 Vocals 时 --lyrics 必填。可选 --vocal-gender <male|female>、--generate-start <seconds>、--generate-end <seconds>。

music recognize、music describe、music stem 各需 --audio <file>（mp3/m4a，最大 10MB）。music stem 还接受 --model（audio-separation-1 或 audio-separation-2）。

music list 选项：--page <n>（默认 1）、--page-size <n>（默认 20）、--status <status>（pending、generating、uploading、success、failed）、--json。

# 从提示词生成
listenhub openapi music generate \
  --prompt "Upbeat synthwave with a driving bassline" --title "Night Drive"

# 把 mp3 分离成 stem
listenhub openapi music stem --audio track.mp3

content

从 URL 提取可读内容，可选做摘要。异步；轮询直到 status 为 completed，--timeout 默认 300 秒。

命令	说明
`content extract`	从 URL 提取内容。
`content get <taskId>`	获取提取结果。

content extract 选项：

选项	默认值	说明
`--url <url>`	必填	待提取的 URL。
`--summarize`	关	对提取的内容做摘要。
`--max-length <n>`	—	内容最大长度。
`--no-wait`、`--timeout <seconds>`（`300`）、`--json`	—	标准异步参数。

listenhub openapi content extract --url "https://example.com/article" --summarize

subscription

显示你的订阅计划与积分余额——总可用积分、当月已用/总额、永久积分、计划名称及到期时间。

命令	选项	说明
`subscription`	`--json`	显示订阅与积分信息。

listenhub openapi subscription --json