SDK 与 CLI

ListenHub API 的官方 JavaScript/TypeScript SDK 与命令行工具，以及如何在二者之间做选择。

ListenHub 在 OpenAPI 之上提供了两个官方客户端库：JavaScript/TypeScript SDK 和命令行工具。两者访问相同的接口，自动帮你解开标准的 { code, message, data } 包裹，并自动处理 429 重试——相比直接调用 HTTP API，你需要写的样板代码更少。

选择你的工具

JavaScript SDK

面向 Node 与浏览器的强类型客户端。可用于应用、后端服务或脚本。

命令行工具

在终端或 CI 任务中生成播客、TTS、图片、音乐与视频——无需写代码。

安装

npm i @marswave/listenhub-sdk

仅支持 ESM。要求 Node.js >= 20。

npm i -g @marswave/listenhub-cli

全局安装 listenhub 命令。要求 Node.js >= 20。

我该用哪一个？

你想要…	选择
在产品中实现生成音频、图片或视频的功能	SDK（服务端用 `OpenAPIClient`，面向用户的应用用 `ListenHubClient`）
编写一次性任务、批量生成或 CI/CD 步骤	CLI——用 `--json` 输出配合 `jq` 处理
查看接口、参数和精确的响应结构	OpenAPI 参考
从 AI 智能体或助手驱动 ListenHub	MCP 服务

SDK 与 CLI 都是便捷封装层。它们能做的一切，你也可以直接通过 OpenAPI 的原始 HTTP 调用完成——每个接口、参数和枚举都以参考文档为准。

两种认证方式

两个客户端都支持以下两种认证方式，按代码运行的位置来选择。

API Key——用于服务端、脚本和 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 Key 当作密钥对待，仅保留在服务端——绝不要把密钥打包进浏览器或移动端客户端代码。面向用户的应用请使用 OAuth，让每个请求都在用户自己的账户下执行。

// 服务端，使用 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' });

# 在终端中完成同样的事
export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en --json

错误处理速览

每个响应都包裹在 { "code": 0, "message": "", "data": { … } } 中。code 非零即表示错误。

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> 可限定等待时长。