JavaScript SDK
面向 ListenHub API 的类型化 JavaScript/TypeScript 客户端，提供 API key 与 OAuth 两种鉴权方式的客户端。
@marswave/listenhub-sdk 是 ListenHub API 的官方 JavaScript/TypeScript 客户端。它是一个扁平客户端——每个接口都是客户端对象上的一个方法——底层基于 ky 的 HTTP 层，会自动拆包标准的 { code, message, data } 信封，并为你重试 429 响应。
- 仅 ESM，自带 TypeScript 类型——无需额外安装
@types包。 - Node.js >= 20。 使用 OAuth 用户令牌鉴权时也可在浏览器中运行。
- 仅一个依赖（
ky），打包体积小。
安装
npm i @marswave/listenhub-sdk两个客户端
SDK 导出两个客户端。它们共享相同的响应处理与重试行为，区别在于鉴权方式以及所面向的 API 范围。根据代码运行的位置选择其一。
OpenAPIClient | ListenHubClient | |
|---|---|---|
| 鉴权 | API key（Authorization: Bearer） | OAuth 用户 access token |
| 运行环境 | 服务端、脚本、CI | 面向用户的应用，代表已登录用户 |
| Base URL | https://api.marswave.ai/openapi | https://api.listenhub.ai/api |
| 身份 | 你的账户 / key 所有者 | 已登录的用户 |
服务端与自动化场景使用 OpenAPIClient。 它对应的是公开的 OpenAPI 产品：传入在 listenhub.ai/settings/api-keys 创建的 API key，或设置 LISTENHUB_API_KEY 环境变量后以无参数方式构造它。
当每个请求都必须以某个用户身份运行时使用 ListenHubClient——比如用户通过 OAuth 登录的交互式应用。它的 accessToken 接受一个静态字符串，或一个 getter 函数 () => string | undefined，该函数在每次请求前被调用，因此你可以传入一个会随时间刷新的令牌。
请将 API key 视为机密。务必保存在服务端——切勿把 API key 打包进浏览器或移动端客户端代码。面向用户的应用请使用 OAuth，使每个请求都在用户自己的账户下运行。
Hello world
构造客户端、列出 speakers，并发起一个 flow speech（文本转语音）节目。下面的示例使用 OpenAPIClient，并从 LISTENHUB_API_KEY 读取 key。
import { OpenAPIClient } from '@marswave/listenhub-sdk';
const client = new OpenAPIClient(); // 读取 LISTENHUB_API_KEY
const { items: speakers } = await client.listSpeakers({ language: 'en' });
const { episodeId } = await client.createFlowSpeech({
sources: [{ type: 'text', content: 'Hello world' }],
speakers: [{ speakerId: speakers[0].speakerId }],
});生成过程是异步的：createFlowSpeech 会立即返回一个 episodeId。轮询 getFlowSpeech(episodeId) 直到 processStatus 不再是 pending，即可拿到音频 URL。完整的「创建并轮询」循环见 快速开始。
响应的处理方式
每个 ListenHub 响应都包裹在 { "code": 0, "message": "", "data": { … } } 中，其中非零的 code 表示错误。两个客户端都会替你处理这一点：
- 当
code为0时，方法直接解析为data——你完全看不到这层信封。 - 当
code非零或发生 HTTP 错误时，方法抛出ListenHubError，其中携带status、code和requestId。 - 当返回
429 Too Many Requests时，客户端读取Retry-After头并自动重试，最多重试maxRetries次（默认2）。
对于 SDK 尚未封装的接口，ListenHubClient 把底层的 ky 实例暴露为 client.api——一个复用相同认证、base URL 与重试行为的逃生通道（OpenAPIClient 不暴露它）：
import { ListenHubClient } from '@marswave/listenhub-sdk';
const userClient = new ListenHubClient({ accessToken });
const me = await userClient.api.get('v1/users/me').json();