This is the complete method reference for @marswave/listenhub-sdk. Methods are grouped by product. Each entry lists the signature, one line on what it does, and the underlying HTTP endpoint.

The SDK ships two clients. They share response handling (unwrap data on code 0, throw ListenHubError otherwise, auto-retry 429) but target different API surfaces and authenticate differently:

OpenAPIClient is the public OpenAPI product — that surface is the focus of this reference. ListenHubClient is the OAuth client used by first-party apps; its methods are listed under ListenHubClient methods at the end.

Conventions used below:

• "Endpoint" paths are relative to the client base URL. For OpenAPIClient that is https://api.marswave.ai/openapi/.
• Methods return the unwrapped data payload. The { code, message, data } envelope is handled for you.
• A few methods return a raw Response (binary or streaming) — these are called out explicitly.
• Never hard-code credit costs. Use the estimate*Credits methods and getSubscription() instead.

OpenAPIClient methods

Speakers

A voice is identified by its speakerId. List voices before creating any episode and pass the ids you want.

listSpeakers parameters:

Each OpenAPISpeaker carries speakerId, name, gender, language, demoAudioUrl, and an optional profile (pitch, speed, traits, styles, scenes, accent, description).

const { items } = await client.listSpeakers({ language: 'en' });
const speakerId = items[0].speakerId;

Podcast

A podcast is a multi-speaker conversation generated from a query and/or sources. Create it, then poll getPodcast until processStatus is success.

createPodcast parameters (OpenAPICreatePodcastParams):

The two-step text-then-audio flow lets you review or edit the script before paying for audio: createPodcastTextContent generates the script only, then generatePodcastAudio(episodeId, { scripts }) renders audio from scripts you optionally rewrite. getPodcastTextStream(episodeId, 'script' | 'outline') returns a streaming Response for live script/outline tokens.

OpenAPIPodcastDetail includes processStatus, title, outline, cover, audioUrl, audioStreamUrl, subtitlesUrl, scripts (per-speaker lines), credits, and failCode on failure.

Flow Speech / TTS

Flow speech turns text or a URL into narrated audio with one or more voices. TTS endpoints are lower-level: they synthesize speech from explicit scripts.

Flow speech

createFlowSpeech parameters (OpenAPICreateFlowSpeechParams):

createFlowSpeechTTS takes scripts: Array<{ content: string; speakerId: string }> plus an optional title, and renders the lines verbatim. event for the text stream is 'script' | 'outline'.

OpenAPIFlowSpeechDetail includes processStatus, title, outline, cover, audioUrl, audioStreamUrl, subtitlesUrl, scripts, and sourceProcessResult.

TTS / speech

speech takes scripts: Array<{ content: string; speakerId: string }> and returns a synchronous result: { audioUrl, audioDuration, subtitlesUrl?, taskId, credits }.

tts and audioSpeech are OpenAI-compatible single-voice synthesis. They take { input, voice, response_format? } where response_format is one of mp3 (default), opus, aac, flac, wav, pcm, and return the audio as a raw Response — read it with .arrayBuffer() or stream .body.

const res = await client.tts({ input: 'Hello world', voice: speakerId, response_format: 'mp3' });
const audio = Buffer.from(await res.arrayBuffer());

Storybook (explainer / slides)

Storybook produces page-based visual content — explainer videos and slide decks. mode selects the format. Audio is optional via skipAudio.

createStorybook parameters (OpenAPICreateStorybookParams):

After an episode succeeds, generateStorybookVideo(episodeId) renders a downloadable video from the pages. Poll getStorybook and watch videoStatus (not_generated → pending → success / fail); videoUrl appears on success.

OpenAPIStorybookDetail includes mode, processStatus, title, cover, audioUrl, audioDuration, videoUrl, videoStatus, and pages (each with text, pageNumber, imageUrl, audioTimestamp).

Image

Single-call image generation. There is no separate poll method on OpenAPIClient — the response carries the result.

createImage parameters (OpenAPICreateImageParams):

Video (SeeDance / HappyHorse + PixVerse)

Two video families share the same poll/list/estimate methods but have different create methods and parameters. SeeDance (doubao-seedance-2-*) and HappyHorse use a content array; PixVerse uses a capability-based shape.

SeeDance / HappyHorse

createVideoGeneration parameters (OpenAPICreateVideoGenerationParams):

Each content item is one of:

• { type: 'text', text }
• { type: 'image_url', image_url: { url }, role: 'first_frame' \| 'last_frame' \| 'reference_image' }
• { type: 'video_url', video_url: { url }, role: 'reference_video' }
• { type: 'audio_url', audio_url: { url }, role: 'reference_audio' }

HappyHorse rejects last_frame and audio_url content. estimateVideoCredits takes { model, resolution, duration, hasVideoInput?, inputVideoDuration?, ratio? }.

const { taskId } = await client.createVideoGeneration({
  model: 'doubao-seedance-2-pro',
  content: [{ type: 'text', text: 'A timelapse of a city at dusk' }],
  resolution: '1080p',
  duration: 5,
});

PixVerse

Poll and list PixVerse tasks with the same getVideoGenerationTask / listVideoGenerationTasks methods above.

createPixVerseVideoGeneration parameters (OpenAPICreatePixVerseVideoParams):

The nested pixverse object covers agentType, motionMode, cameraMovement, templateId, multiTransition, imageReferences, tts, soundEffect*, lipSyncTts*, brandSticker, and introOutroClip. Relevance depends on capability. estimatePixVerseVideoCredits takes { capability, model?, language?, duration?, quality?, pixverse? } with a reduced pixverse shape for the estimate.

Music

Music endpoints default to the Mureka provider. Async endpoints return a task ({ taskId, taskType, status }); poll getMusicTask. Synchronous endpoints (recognizeMusic, describeMusic, stemMusic) return their result directly.

Key create parameters:

• createMusicGenerate: { prompt?, lyrics?, model?, style?, title?, instrumental?, vocalId? }. model is one of auto, mureka-7.6, mureka-8, mureka-9, mureka-o2.
• createMusicExtend: { uploadUrl, model, continueAt, prompt?, style?, title?, instrumental?, negativeTags?, vocalGender?, styleWeight?, weirdnessConstraint?, audioWeight? }. model here is a Suno version (V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5).
• createMusicRemix: { audio?, audioFilename?, audioUrl?, providerSongId?, lyrics, prompt }. Provide exactly one of audio / audioUrl / providerSongId. Prefer this over the deprecated createMusicCover.
• createMusicInstrumental: { prompt?, referenceAudio?, referenceAudioFilename?, model? }. Provide prompt XOR referenceAudio.
• createMusicSoundtrack: { image?, video?, prompt?, model? }. Provide image XOR video.
• createMusicTrack: { audio?, providerSongId?, generateType, prompt, lyrics?, vocalGender?, generateStart?, generateEnd? }. generateType selects the stem (Vocals, Instrumental, Drums, …); lyrics is required when generateType is Vocals.

The multipart endpoints (remix, instrumental, soundtrack, track, recognize, describe, stem) take a Blob/File for the audio/image/video field. In Node 20+, wrap a buffer with new Blob([buffer]).

const { taskId } = await client.createMusicGenerate({
  prompt: 'lo-fi hip hop, mellow, rainy night',
  model: 'auto',
});
let task = await client.getMusicTask(taskId);
while (task.status === 'pending' || task.status === 'generating') {
  await sleep(10_000);
  task = await client.getMusicTask(taskId);
}
console.log(task.tracks[0]?.audioUrl);

Synchronous results: recognizeMusic returns timestamped lyricsSections; describeMusic returns { description, tags, genres, instruments }; stemMusic returns { zipUrl, midiZipUrl, expiresAt } (links expire ~24h).

Content Extract

Extract readable content from a URL (article text, optional summary). Asynchronous: create, then poll.

createContentExtract parameters (OpenAPICreateContentExtractParams):

Poll getContentExtract until status is completed. The detail carries data.content, data.metadata, data.references, and credits.

Subscription

Returns credit balance and plan info: totalAvailableCredits, the monthly/permanent/limited-time credit breakdown, resetAt, renewStatus, paidStatus, and subscriptionPlan. Use totalAvailableCredits to check your balance before an expensive job.

Files

OpenAPIClient has no dedicated file-upload method. To use a local file as input, host it at a public URL and pass that URL (for example as a source uri, a referenceImages.fileData.fileUri, or a video image_url.url). The presigned-upload flow lives on ListenHubClient — see Files below.

ListenHubClient methods

ListenHubClient authenticates with an OAuth user access token and targets https://api.listenhub.ai/api. It exposes the first-party app surface. The product shapes differ from OpenAPIClient: episodes use a nested template object, and creation methods are split per product (podcast, TTS, explainer, slides). Use this client only when each request runs under an individual signed-in user.

Auth & session

connectInit({ callbackPort }) starts the device/OAuth flow and returns an authUrl to open; connectToken({ sessionId, code }) exchanges the result for tokens. refresh({ refreshToken }) rotates an expiring access token; revoke({ refreshToken }) invalidates it.

Speakers

Parameters: { language?, status? }. Note the return shape differs from OpenAPIClient — each Speaker exposes speakerInnerId (not speakerId), plus personality, accessType, and weight. The speakerInnerId is what the episode template.speakers array expects.

Podcast

createPodcast parameters (CreatePodcastParams):

Flow Speech / TTS

createTTS parameters (CreateTTSParams): { sources, template: { type: 'flowspeech', mode: 'smart' | 'direct', speakers, language } }.

Storybook (explainer / slides)

createExplainerVideo and createSlides share a shape: { query?, sources?, style?, styleOverride?, skipAudio?, imageConfig?, template }. The template carries type: 'storybook', mode (info / story for explainers, slides for decks), speakers, language, and optional style, size (2K / 4K), aspectRatio (16:9 / 9:16 / 1:1), pageCount. createSlides defaults skipAudio to true and fixes mode to slides. exportExplainerVideo triggers the downloadable video render.

Episodes (shared)

These work across all four products on ListenHubClient.

getCreation returns the full EpisodeDetail (status, speakers, topicDetail with title/outline/audio/video/pages/scripts). deleteCreations({ ids }) batch-soft-deletes up to 100 episodes by id; passing a video episode id also soft-deletes its video task and refunds credits for any in-progress task. The per-product list* methods all hit GET v1/episodes with a productId filter and accept { page?, pageSize? }.

Image

createAIImage parameters (CreateAIImageParams):

Generation is async — poll getAIImage(imageId) until status is terminal and imageUrl is set. deleteAIImages({ ids }) batch-soft-deletes up to 100 images (owner-scoped; unknown ids ignored).

Music

ListenHubClient exposes the same music method set as OpenAPIClient (same endpoints, same parameters): createMusicGenerate, createMusicCover, createMusicExtend, createMusicRemix, createMusicInstrumental, createMusicSoundtrack, createMusicTrack, recognizeMusic, describeMusic, stemMusic, getMusicTask, listMusicTasks. See Music above for parameters and the poll loop.

Lyrics

createLyrics({ prompt }) starts an async lyrics task; poll getLyricsTask until status is success, then read variants (each { text, title, status }).

Video Generation

ListenHubClient exposes the same video methods as OpenAPIClient, with one naming difference: the SeeDance/HappyHorse estimate method is estimateVideoGenerationCredits (vs. estimateVideoCredits on OpenAPIClient).

Parameters match the Video section above.

Subscription & user

Note the endpoint differs from OpenAPIClient (v1/users/subscription vs. v1/user/subscription). getSettings returns the user's saved per-product defaults (speakers, language, duration, mode, style images).

Checkin

Daily check-in for reward credits. checkinStatus reports hasCheckedInToday, lastCheckinTime, and monthlyCheckinCount.

Settings / API key

Lets a signed-in user read or rotate their OpenAPI key. regenerateApiKey invalidates the previous key.

Files

createFileUpload({ fileKey, contentType, category }) returns a presignedUrl to PUT the bytes to, plus the fileUrl to reference afterward. getFileDownloadUrl(fileUrl) resigns a stored file URL into a time-limited downloadUrl.

The client.api escape hatch

ListenHubClient exposes its underlying ky instance as client.api for endpoints the SDK does not wrap. It applies the same auth, base URL, and retry behavior, but you parse the response yourself. Paths are relative to the base URL — no leading / (a ky requirement):

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

OpenAPIClient does not expose client.api. For an OpenAPI endpoint the SDK does not cover yet, call it with your own HTTP client using the same Authorization: Bearer header — see the OpenAPI reference.

Errors

Every method throws a ListenHubError on a non-zero code or an HTTP error. It carries status, code, and requestId — include requestId when reporting an issue.

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

try {
  await client.getPodcast('nope');
} catch (err) {
  if (err instanceof ListenHubError) {
    console.error(`[${err.status}] code ${err.code} (request ${err.requestId})`);
  } else {
    throw err;
  }
}

Next steps