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-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 서버 |
SDK와 CLI는 편의를 위한 계층입니다. 이들이 하는 일은 모두 OpenAPI에 대한 원시 HTTP 호출로도 할 수 있으며, 모든 엔드포인트와 파라미터, 열거형(enum)의 기준은 레퍼런스 문서입니다.
두 가지 인증 방식
두 클라이언트 모두 동일한 두 가지 인증 방식을 지원합니다. 코드가 어디서 실행되는지에 따라 선택하세요.
- 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는 SDK가 아직 래핑하지 않은 엔드포인트를 위한 ky 탈출구입니다. - CLI — 에러를 stderr로 출력하고 종료 코드를 사용합니다:
0성공,1에러,2인증,3타임아웃. 오래 걸리는 생성 작업은 10초마다 폴링하며,--no-wait를 넘기면 ID를 즉시 반환하고--timeout <s>로 대기 시간을 제한할 수 있습니다.