SDK と CLI
ListenHub API の公式 JavaScript/TypeScript SDK とコマンドラインツール、および使い分けの指針。
ListenHub は OpenAPI の上に 2 つの公式クライアントライブラリを提供しています：JavaScript/TypeScript の SDK とコマンドラインツールです。どちらも同じエンドポイントにアクセスし、標準の { code, message, data } エンベロープを自動で展開し、429 のリトライも自動で処理します — HTTP API を直接呼ぶより、書く配線コードが少なくて済みます。
ツールを選ぶ
JavaScript SDK
Node とブラウザ向けの型付きクライアント。アプリ、バックエンドサービス、スクリプトのいずれでも利用可能。
コマンドラインツール
ターミナルや CI ジョブからポッドキャスト、TTS、画像、音楽、動画を生成 — コードを書く必要はありません。
インストール
npm i @marswave/listenhub-sdkESM のみ対応。Node.js >= 20 が必要です。
npm i -g @marswave/listenhub-clilistenhub バイナリをグローバルにインストールします。Node.js >= 20 が必要です。
どちらを使うべきか？
| やりたいこと | 選ぶもの |
|---|---|
| 音声、画像、動画を生成するプロダクト機能を作る | SDK（サーバーには OpenAPIClient、ユーザー向けアプリには ListenHubClient） |
| 単発のジョブ、バッチ生成、CI/CD ステップをスクリプト化する | CLI — --json 出力を jq に流す |
| エンドポイント、パラメータ、正確なレスポンス構造を調べる | OpenAPI リファレンス |
| AI エージェントやアシスタントから ListenHub を動かす | MCP server |
SDK と CLI は利便性のためのレイヤーです。これらでできることはすべて、OpenAPI に対する生の HTTP 呼び出しでも実現できます — すべてのエンドポイント、パラメータ、列挙値はリファレンスが正となります。
2 つの認証方式
どちらのクライアントも同じ 2 つの認証方式に対応しています。コードが動作する場所に応じて選んでください。
- API キー — サーバー、スクリプト、CI 向け。キーは
Authorization: Bearer $LISTENHUB_API_KEYとして渡します。キーは listenhub.ai/settings/api-keys で作成します。SDK ではOpenAPIClient、CLI ではlistenhub openapi …コマンドグループが対応します。 - OAuth ログイン — 対話的な用途やユーザー向けの用途で、ログイン中のアカウントとして処理を実行する場合に使います。SDK では
ListenHubClient、CLI ではlistenhub auth loginが対応し、ブラウザを開いてトークンを~/.config/listenhub/配下に保存します。
API キーはシークレットとして扱ってください。サーバーサイドに留め、ブラウザやモバイルクライアントのコードに含めて配布しないでください。ユーザー向けアプリでは OAuth を使い、各リクエストがユーザー自身のアカウントで実行されるようにしてください。
// Server-side, API key
import { OpenAPIClient } from '@marswave/listenhub-sdk';
const client = new OpenAPIClient({ apiKey: process.env.LISTENHUB_API_KEY });
const { items: speakers } = await client.listSpeakers({ language: 'en' });# Same thing from the terminal
export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en --jsonエラー処理の概要
すべてのレスポンスは { "code": 0, "message": "", "data": { … } } に包まれています。code が 0 以外の場合はエラーです。
- SDK —
code 0のときはdataを展開し、それ以外の場合はListenHubError（status、code、requestIdを含む）をスローします。429の場合はRetry-Afterを読み取り、maxRetries（デフォルト2）まで再試行します。client.apiは ky のエスケープハッチで、SDK がまだラップしていないエンドポイントにアクセスできます。 - CLI — エラーは stderr に出力し、終了コードを使います：
0成功、1エラー、2認証、3タイムアウト。長時間かかる生成タスクは 10 秒ごとにポーリングします。--no-waitを渡すと ID をすぐに返し、--timeout <s>で待機時間の上限を指定できます。