OpenAPI Commands

The listenhub openapi namespace runs every command against your API key instead of an OAuth login. Use it on servers and in CI, where you control the environment and want a long-lived credential rather than an interactive browser flow.

Before you start, make the key available — set LISTENHUB_API_KEY or store it with listenhub openapi config set-key. See Authentication for where credentials live and how the CLI resolves them.

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

Conventions used on this page

Every command in this namespace shares the same behavior:

• Output. Human-readable text by default; --json / -j prints machine-readable JSON to stdout (errors go to stderr). Pipe JSON into jq.
• Async creation. Commands that start generation submit a job and then poll until it reaches a terminal state, printing a spinner. Polling runs on a 10-second interval. --no-wait returns the ID immediately and exits 0; --timeout <seconds> caps the wait (default varies by command, noted per group below).
• Exit codes. 0 success, 1 error, 2 auth, 3 timeout.
• Credits. Generation consumes credits. Use the relevant estimate command before creating, and check your balance with listenhub openapi subscription. Never assume a fixed cost.

config

Manage the stored API key. The CLI reads LISTENHUB_API_KEY first, then the file written by set-key.

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

speakers

List the voices available to your account. The ID column is the speakerId you pass to creation commands.

listenhub openapi speakers list --language en

Prints a table of Name, ID, Gender, and Language.

tts, audio-speech, speech

Three ways to turn text into speech. The first two stream binary audio to a file; the third returns a hosted audio URL.

tts and audio-speech share these options:

speech options:

# Stream an MP3 to disk
listenhub openapi tts \
  --text "Welcome to ListenHub." \
  --voice <speaker-id> \
  --output welcome.mp3

# Get a hosted audio URL instead
listenhub openapi speech --script "Welcome to ListenHub." --speaker-id <speaker-id>

flow-speech

Flow Speech turns sources or scripts into a narrated episode. Creation commands poll until processStatus is success; the default --timeout is 300 seconds.

flow-speech create options:

At least one --source-url or --source-text is required.

flow-speech tts options:

Scripts and speakers are paired by position: the first --script uses the first --speaker-id, and so on; if there are more scripts than speakers, the first speaker is reused.

flow-speech text-stream <episodeId> requires --event <event>, one of script or outline. It writes the raw SSE stream to stdout.

# From a source URL, two voices
listenhub openapi flow-speech create \
  --source-url "https://example.com/article" \
  --speaker-id <host-id> \
  --speaker-id <guest-id>

# Directly from scripts
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"

listenhub-voice

End-to-end audio generation with listenhub-voice-1.0 — plain narration, sound effects, single-voice speech, multi-speaker dialogue, voice cloning, or image-to-audio. generate creates a task and polls until status is success (default --timeout 300s); task and tasks inspect existing tasks.

listenhub-voice generate options:

listenhub-voice tasks options: --page <n> (default 1), --page-size <n> (default 20, max 100), --status <status> (one of pending, generating, uploading, success, failed), --keyword <text>, --json.

listenhub-voice task <taskId> accepts --wait (poll until terminal), --timeout <seconds> (300), and --json.

# Single built-in voice
listenhub openapi listenhub-voice generate \
  --text "Welcome to ListenHub. Here is your daily briefing." \
  --voice "speaker:zh_female_warm" \
  --duration-hint 20

# Two-voice dialogue (@音频N assigns lines in order)
listenhub openapi listenhub-voice generate \
  --text "@音频1 Hi there! @音频2 Hello, how can I help?" \
  --voice "reference:https://example.com/host.mp3" \
  --voice "speaker:zh_male_calm"

# Image to audio
listenhub openapi listenhub-voice generate \
  --text "Describe this scene as a short narrated clip." \
  --image-url "https://example.com/scene.jpg"

voice-clone

Clone a voice from reference audio, then manage the private voices it produces. create uploads 1–6 local audio files and polls until cloning finishes; confirm turns a finished task into a reusable voice whose speaker ID works with tts, speech and audio-speech. Upload mode only — the interactive recording flow lives in the web app.

Cloning requires the consent of the person being cloned: --consent is your declaration that you hold it, and the API rejects a create without it. Confirming is free within your plan's per-period quota; beyond it each confirmation costs 300 credits and only happens when you pass --use-credits.

voice-clone create options:

voice-clone confirm takes --task-id <id>, --name <name>, --gender <gender>, and optional --use-credits. voice-clone update <speakerId> takes --name and/or --gender (at least one).

Polling ends in one of three states: cloning failed (error code and message), cloned but not confirmed (preview URL, plus a confirm error when auto-confirm could not save it), or confirmed (speaker ID).

# Two-step: clone, listen, then confirm
listenhub openapi voice-clone create --file ./reference.mp3 --lang en --consent
listenhub openapi voice-clone confirm \
  --task-id 6915bde9cca4d3c8ecb3eaf5 --name "My API Voice" --gender female

# One-shot: clone and confirm in the same flow
listenhub openapi voice-clone create \
  --file ./part-1.mp3 --file ./part-2.mp3 --lang ja \
  --consent --auto-confirm --name "My API Voice" --gender female --use-credits

# Speak with the cloned voice
listenhub openapi speech --script "Hello from my own voice." \
  --speaker-id voice-clone-6915bde9cca4d3c8ecb3eaf5

# Manage private voices
listenhub openapi voice-clone speakers
listenhub openapi voice-clone delete 6915c0a2cca4d3c8ecb3eb01

podcast

Generate a podcast episode. You can produce text and audio in one step, or split the two: generate the text content first, review or stream it, then generate audio. Creation commands default to a 300-second --timeout.

podcast create options:

podcast text-content takes the same source and speaker options (--query, --source-url, --source-text, --speaker-id, --mode) plus the async flags. At least one of --query, --source-url, or --source-text is required.

podcast text-stream <episodeId> requires --event <event>, one of script or outline.

# One-shot: text + audio
listenhub openapi podcast create \
  --query "AI agent trends in 2026" \
  --speaker-id <host-id> \
  --mode quick

# Two-step: text first, then audio
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 produces explainer and slides episodes, optionally with video. Creation polls until processStatus is success; the default --timeout is 300 seconds.

storybook create options:

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

image

Generate an AI image from a prompt, optionally conditioned on reference images. --reference accepts both local file paths and URLs; local files are read and sent inline, URLs are passed by reference.

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

video

AI video generation. This group has two surfaces: the generic video commands (text/image/reference driven) and the video pixverse subcommands (PixVerse capability API). Both poll until status is success with a default --timeout of 1200 seconds, and both take a 24-character hex task ID.

video create

The prompt is required; everything else selects an input mode. Frame mode (--first-frame / --last-frame) and reference mode (--reference-image / --reference-video / --reference-audio) are mutually exclusive.

# Text to video
listenhub openapi video create \
  --prompt "A timelapse of clouds over a mountain range" \
  --model doubao-seedance-2-pro \
  --resolution 1080p --duration 8

# First/last frame interpolation
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 and estimate

video list options: --page <n> (default 1), --page-size <n> (default 20), --status <status> (one of pending, generating, uploading, success, failed), --json.

video estimate requires --model, --resolution, and --duration, and accepts --ratio, --has-video-input, and --input-video-duration (required when --has-video-input is set):

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

video pixverse

PixVerse exposes atomic generation capabilities plus a marketing agent. Pick one with --capability:

Shared enums:

• Model (--model): pixverse, v6, v5, v4.5 (default pixverse).
• Language / region (--language): zh, en (default en).
• Quality (--quality): 360p, 540p, 720p, 1080p (default 720p).
• Aspect ratio (--aspect-ratio): 9:16, 16:9, 1:1, 4:3, 3:4 (default 16:9).
• Agent type (--agent-type, with --capability agent): ad_master, promo_mix.

video pixverse generate options:

Asset flags accept an optional trailing :duration in seconds — for example https://example.com/clip.mp4:5. Only a trailing :<integer> is treated as a duration, so URLs with their own colons are safe.

# Lip-sync from 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."

# Marketing 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 takes --capability (required), plus --model, --language, --quality, --duration, and --agent-type:

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

music

AI music generation, backed by Mureka. Async commands (generate, remix, instrumental, soundtrack, track) poll until status is success; the default --timeout is 600 seconds. The analysis commands (recognize, describe, stem) run synchronously.

Model values across the generation commands: auto, mureka-7.6, mureka-8, mureka-9, mureka-o2.

music generate options:

music remix [audio] takes the audio as a positional file, or --audio-url <url>, or --provider-song-id <id> — exactly one. Requires --lyrics and --prompt.

music instrumental requires exactly one of --prompt or --reference-audio <file> (mp3/m4a, max 10MB); accepts --model.

music soundtrack requires exactly one of --image <file> or --video <file>; accepts --prompt and --model.

music track [audio] takes the audio as a positional file or --provider-song-id <id> (exactly one). Requires --generate-type (Vocals, Instrumental, Drums, Bass, Guitar, …) and --prompt; --lyrics is required when --generate-type is Vocals. Optional --vocal-gender <male|female>, --generate-start <seconds>, --generate-end <seconds>.

music recognize, music describe, and music stem each require --audio <file> (mp3/m4a, max 10MB). music stem also accepts --model (audio-separation-1 or audio-separation-2).

music list options: --page <n> (default 1), --page-size <n> (default 20), --status <status> (pending, generating, uploading, success, failed), --json.

# Generate from a prompt
listenhub openapi music generate \
  --prompt "Upbeat synthwave with a driving bassline" --title "Night Drive"

# Separate an mp3 into stems
listenhub openapi music stem --audio track.mp3

content

Extract readable content from a URL, optionally summarized. Async; polls until status is completed with a default --timeout of 300 seconds.

content extract options:

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

subscription

Show your subscription plan and credit balance — total available credits, the monthly allotment used/total, permanent credits, plan name, and expiry.

listenhub openapi subscription --json

Next steps