@marswave/listenhub-sdk

JavaScript SDK for the ListenHub API.

Install

npm i @marswave/listenhub-sdk

Quick start

OpenAPI Key (recommended for server-side)

No OAuth flow required — just pass your API Key:

import {OpenAPIClient} from '@marswave/listenhub-sdk';

const client = new OpenAPIClient({apiKey: 'lh_sk_...'});
// or set LISTENHUB_API_KEY env var and call new OpenAPIClient()

const {items: speakers} = await client.listSpeakers({language: 'en'});
const {episodeId} = await client.createFlowSpeech({
	sources: [{type: 'text', content: 'Hello world'}],
	speakers: [{speakerId: speakers[0].speakerId}],
});

OAuth (for client-side apps)

Clone the repo and run the OAuth login example — it opens a browser, handles the callback, and prints your tokens:

git clone https://github.com/marswaveai/listenhub-sdk.git
cd listenhub-sdk
pnpm i
npx tsx examples/oauth-login.ts

Client options

The SDK provides two clients for different auth modes:

// OpenAPI Key — server-side, no user login required
const openapi = new OpenAPIClient({
	apiKey: 'lh_sk_...', // or LISTENHUB_API_KEY env var
	baseURL: 'https://api.marswave.ai/openapi', // or LISTENHUB_OPENAPI_URL env var
	timeout: 60_000,
	maxRetries: 2,
});

// OAuth access token — client-side, user login required
const client = new ListenHubClient({
	accessToken: 'token', // static string or () => string | undefined
	baseURL: 'https://api.listenhub.ai/api',
	timeout: 30_000,
	maxRetries: 2,
});

Examples

OpenAPI Key

File	Description
examples/openapi-basic.ts	Create flow speech, poll, and check credits

OAuth (ListenHubClient)

File	Description
examples/oauth-login.ts	Browser-based OAuth login flow
examples/basic.ts	Checkin, API key, error handling
examples/create-podcast.ts	Create a duo podcast and poll for result
examples/create-tts.ts	Text-to-speech from plain text
examples/create-explainer-video.ts	Explainer video from a URL
examples/create-slides.ts	Slide deck presentation
examples/create-ai-image.ts	AI image generation from a prompt
examples/music.ts	Music generation and cover from audio
examples/video-generation.ts	Video generation with SeeDance2.0

Documentation

Document	Description
Architecture	Module dependency diagram and responsibilities
Client Behavior	Request/response flow, hooks, retry and refresh logic
Testing	Test layers, running tests, mock server setup

API

Auth

Method	Description
connectInit({callbackPort})	Start OAuth flow, returns authUrl and sessionId
connectToken({sessionId, code})	Exchange authorization code for tokens
refresh({refreshToken})	Refresh an expired access token
revoke({refreshToken})	Revoke a refresh token

Checkin

Method	Description
checkinSubmit()	Submit daily check-in
checkinStatus()	Get check-in streak and status

Settings

Method	Description
getApiKey()	Get current API key
regenerateApiKey()	Regenerate API key (triggers onApiKeyChanged)
getSettings()	Get episode template settings per product type

Content creation

Method	Description
createPodcast(params)	Create a podcast (solo/duo)
createTTS(params)	Create a text-to-speech audio
createExplainerVideo(params)	Create an explainer video
createSlides(params)	Create a slides presentation
createAIImage(params)	Generate an AI image from a prompt

Music

Method	Description
createMusicGenerate(params)	Generate music from a text prompt
createMusicCover(params)	Create a cover from a reference audio URL
getMusicTask(taskId)	Get music task status and details
listMusicTasks(params?)	List music tasks with optional filtering

Video Generation (SeeDance2.0)

Method	Description
createVideoGeneration(params)	Create a video generation task
getVideoGenerationTask(taskId)	Get video generation task status and details
listVideoGenerationTasks(params?)	List video generation tasks with optional filtering
estimateVideoGenerationCredits(params)	Estimate credit cost before generating

List by product

Method	Description
listPodcasts(params?)	List podcast episodes
listTTS(params?)	List TTS episodes
listExplainerVideos(params?)	List explainer videos
listSlides(params?)	List slides
listAIImages(params?)	List AI-generated items
getCreation(episodeId)	Get full creation detail
deleteCreations({ids})	Batch delete creations

Users

Method	Description
getCurrentUser()	Get current user profile
getSubscription()	Get subscription and credit usage info

Speakers

Method	Description
listSpeakers(params?)	List available speakers by language

Custom requests

client.api exposes the underlying ky instance for endpoints not yet covered by the SDK:

const user = await client.api.get('v1/users/me').json();

OpenAPIClient API

The OpenAPIClient provides access to all OpenAPI endpoints using API Key authentication.

Speakers

Method	Description
listSpeakers(params?)	List available speakers by language

Flow Speech

Method	Description
createFlowSpeech(params)	Create a flow speech episode
getFlowSpeech(episodeId)	Get flow speech status and details
getFlowSpeechTextStream(episodeId, event)	Stream script or outline text (SSE)
createFlowSpeechTTS(params)	Create flow speech from scripts

Podcast

Method	Description
createPodcast(params)	Create a podcast episode
getPodcast(episodeId)	Get podcast status and details
getPodcastTextStream(episodeId, event)	Stream script or outline text (SSE)
createPodcastTextContent(params)	Create text-only content (no audio)
generatePodcastAudio(episodeId)	Generate audio for text-only episode

TTS

Method	Description
speech(params)	Multi-speaker speech, returns audio URL
tts(params)	Single-voice TTS, returns audio stream
audioSpeech(params)	OpenAI-compatible TTS, returns stream

Storybook

Method	Description
createStorybook(params)	Create a storybook episode
getStorybook(episodeId)	Get storybook details
generateStorybookVideo(episodeId)	Generate video from storybook

Image

Method	Description
createImage(params)	Generate an image (google or openai)

Video Generation

Method	Description
createVideoGeneration(params)	Create a video generation task
getVideoGenerationTask(taskId)	Get task status and video URL
listVideoGenerationTasks(params?)	List tasks with optional filtering
estimateVideoCredits(params)	Estimate credit cost before generating

Content Extract

Method	Description
createContentExtract(params)	Extract content from a URL
getContentExtract(taskId)	Get extraction result

User

Method	Description
getSubscription()	Get subscription and credit usage info

Rate limiting

On 429 Too Many Requests, the SDK reads the Retry-After header and retries automatically, up to maxRetries times (default: 2).

License

MIT