OpenAPI コマンド

listenhub openapi ネームスペースでは、すべてのコマンドが OAuth ログインではなく API キーで認証されます。環境を自分で管理でき、対話的なブラウザフローよりも長期間有効な認証情報が欲しいサーバーや CI で使ってください。

始める前に、キーを利用できるようにします — 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）。JSON は jq にパイプできます。
• 非同期の作成。 生成を開始するコマンドはジョブを送信したあと、終了状態に達するまでポーリングし、スピナーを表示します。ポーリングの間隔は 10 秒です。--no-wait は ID を即座に返して 0 で終了します。--timeout <seconds> は待機時間の上限を決めます（デフォルトはコマンドごとに異なり、以下の各グループに記載しています）。
• 終了コード。 0 成功、1 エラー、2 認証、3 タイムアウト。
• クレジット。 生成はクレジットを消費します。作成する前に該当する estimate コマンドを使い、残高は listenhub openapi subscription で確認してください。固定のコストを前提にしないでください。

config

保存された API キーを管理します。CLI はまず LISTENHUB_API_KEY を読み、次に set-key が書き込んだファイルを読みます。

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

speakers

アカウントで利用できるボイスを一覧します。ID 列が、作成系コマンドに渡す speakerId です。

listenhub openapi speakers list --language en

Name、ID、Gender、Language のテーブルを表示します。

tts、audio-speech、speech

テキストを音声に変換する 3 つの方法です。最初の 2 つはバイナリ音声をファイルにストリーミングし、3 つ目はホストされた音声 URL を返します。

tts と audio-speech は以下のオプションを共有します：

speech のオプション：

# 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 は、参照ソースやスクリプトをナレーション付きのエピソードに変換します。作成系コマンドは processStatus が success になるまでポーリングします。--timeout のデフォルトは 300 秒です。

flow-speech create のオプション：

--source-url か --source-text が少なくとも 1 つ必要です。

flow-speech tts のオプション：

スクリプトとスピーカーは位置で対応づけられます。最初の --script は最初の --speaker-id を使い、以降も同様です。スクリプトがスピーカーより多い場合は、最初のスピーカーが再利用されます。

flow-speech text-stream <episodeId> には --event <event> が必要で、値は script または outline です。生の SSE ストリームを 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

listenhub-voice-1.0 によるエンドツーエンドの音声生成です — 素のナレーション、効果音、シングルボイスの読み上げ、複数話者の対話、ボイスクローン、画像からの音声生成に対応します。generate はタスクを作成し、status が success になるまでポーリングします（--timeout のデフォルトは 300 秒）。task と tasks は既存のタスクを確認します。

listenhub-voice generate のオプション：

listenhub-voice tasks のオプション：--page <n>（デフォルト 1）、--page-size <n>（デフォルト 20、最大 100）、--status <status>（pending、generating、uploading、success、failed のいずれか）、--keyword <text>、--json。

listenhub-voice task <taskId> は --wait（終了状態までポーリング）、--timeout <seconds>（300）、--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

参考音声からボイスをクローンし、そこで生成されたプライベート音声を管理します。create は 1–6 個のローカル音声ファイルをアップロードし、クローンが完了するまでポーリングします。confirm は完了したタスクを再利用可能なボイスに変換し、そのスピーカー ID は tts、speech、audio-speech でそのまま使えます。アップロードモードのみ対応で、対話的な録音フローは Web アプリ側にあります。

クローンには、クローンされる本人の同意が必要です。--consent は同意を得ていることのあなたの宣言であり、これを付けない作成リクエストは API が拒否します。確定はプランの期間ごとのクォータ内であれば無料です。それを超えると 1 回の確定につき 300 クレジットかかり、--use-credits を渡したときにのみ実行されます。

voice-clone create のオプション：

voice-clone confirm は --task-id <id>、--name <name>、--gender <gender>、および任意の --use-credits を受け付けます。voice-clone update <speakerId> は --name と --gender のいずれか（少なくとも 1 つ）を受け付けます。

ポーリングは次の 3 つの状態のいずれかで終わります：クローン失敗（エラーコードとメッセージ）、クローン済みだが未確定（プレビュー URL。自動確定が保存できなかった場合は確定エラーも）、確定済み（スピーカー 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

ポッドキャストのエピソードを生成します。テキストと音声を 1 ステップで作ることも、2 つに分けることもできます。分ける場合は、まずテキストコンテンツを生成し、確認またはストリーミングしてから音声を生成します。作成系コマンドの --timeout はデフォルト 300 秒です。

podcast create のオプション：

podcast text-content は同じ参照ソースとスピーカーのオプション（--query、--source-url、--source-text、--speaker-id、--mode）に加えて、非同期フラグを受け付けます。--query、--source-url、--source-text のうち少なくとも 1 つが必要です。

podcast text-stream <episodeId> には --event <event> が必要で、値は script または 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 は解説エピソードとスライドエピソードを、任意で動画付きで生成します。作成は processStatus が success になるまでポーリングします。--timeout のデフォルトは 300 秒です。

storybook create のオプション：

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

image

プロンプトから AI 画像を生成します。参考画像を条件として与えることもできます。--reference はローカルのファイルパスと URL の両方を受け付けます。ローカルファイルは読み込まれてインラインで送信され、URL は参照として渡されます。

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

video

AI による動画生成です。このグループには 2 つのインターフェースがあります。汎用の video コマンド（テキスト / 画像 / 参照素材で駆動）と、video pixverse サブコマンド（PixVerse の capability API）です。どちらも status が success になるまでポーリングし、--timeout のデフォルトは 1200 秒で、24 文字の 16 進数のタスク ID を受け取ります。

video create

プロンプトは必須で、それ以外のオプションは入力モードを選ぶためのものです。フレームモード（--first-frame / --last-frame）と参照モード（--reference-image / --reference-video / --reference-audio）は排他です。

# 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 と estimate

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 は、細かい単位の生成機能（capability）に加えてマーケティング agent を提供します。--capability でいずれかを選びます：

共通の列挙値：

• 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 のオプション：

アセット系のフラグは、末尾に任意で :duration（秒）を付けられます。例：https://example.com/clip.mp4:5。末尾の :<integer> だけが長さとして扱われるため、コロンを含む URL でも問題ありません。

# 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 は --capability（必須）に加えて、--model、--language、--quality、--duration、--agent-type を受け付けます：

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

music

Mureka を基盤にした AI 音楽生成です。非同期のコマンド（generate、remix、instrumental、soundtrack、track）は status が success になるまでポーリングします。--timeout のデフォルトは 600 秒です。分析系のコマンド（recognize、describe、stem）は同期的に実行されます。

生成系コマンド全体で使えるモデルの値：auto、mureka-7.6、mureka-8、mureka-9、mureka-o2。

music generate のオプション：

music remix [audio] は、音声を位置引数のファイル、--audio-url <url>、--provider-song-id <id> のいずれかちょうど 1 つで受け取ります。--lyrics と --prompt が必要です。

music instrumental は --prompt か --reference-audio <file>（mp3/m4a、最大 10MB）のちょうど 1 つが必要で、--model を受け付けます。

music soundtrack は --image <file> か --video <file> のちょうど 1 つが必要で、--prompt と --model を受け付けます。

music track [audio] は、音声を位置引数のファイルか --provider-song-id <id>（ちょうど 1 つ）で受け取ります。--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。

# 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

URL から読みやすいコンテンツを抽出します。任意で要約もできます。非同期で、status が completed になるまでポーリングし、--timeout のデフォルトは 300 秒です。

content extract のオプション：

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

subscription

サブスクリプションのプランとクレジット残高を表示します — 利用可能なクレジットの合計、月次配分の使用量 / 総量、永久クレジット、プラン名、有効期限。

listenhub openapi subscription --json

次のステップ