Node.js integration guide

Node.js Music API

Node.js and TypeScript developers who want to add music generation to a service without hosting an audio model.

The approach

Use the official @musicapi/sdk. It has zero runtime dependencies, ships ESM and CommonJS, is fully typed, and runs on Node 18 and newer. The generateAndWait helper submits a job and resolves with the finished song, so you do not have to write the polling loop yourself.

Install

npm install @musicapi/sdk

How it works

  1. 1

    Install the SDK with npm, pnpm, or bun.

  2. 2

    Create an API key in the MusicAPI dashboard and expose it as the MUSICAPI_KEY environment variable.

  3. 3

    Construct a client with that key, then call client.sonic.generateAndWait with a prompt and a model version.

  4. 4

    Iterate the returned data array and use each song's audio_url, which is a ready-to-stream MP3.

  5. 5

    Catch MusicAPIError to branch on auth, credit, and rate-limit failures cleanly.

Full working example

Copy this, set the MUSICAPI_KEY environment variable, and run it. It is a real request against the live API.

ts
import { MusicAPI, MusicAPIError } from "@musicapi/sdk"

const client = new MusicAPI({ apiKey: process.env.MUSICAPI_KEY! })

async function main() {
  try {
    // Submit a generation and wait for the finished song(s).
    const result = await client.sonic.generateAndWait(
      {
        custom_mode: false,
        mv: "sonic-v5",
        gpt_description_prompt: "uplifting synthwave with female vocals",
      },
      { pollIntervalMs: 5000, timeoutMs: 300_000 }
    )

    for (const song of result.data) {
      console.log(song.title, song.audio_url)
    }
  } catch (err) {
    if (err instanceof MusicAPIError) {
      console.error(err.status, err.code, err.message)
      if (err.isAuthError) console.error("Check MUSICAPI_KEY.")
      if (err.isCreditError) console.error("Out of credits.")
    } else {
      throw err
    }
  }
}

main()

Pricing

MusicAPI is pay-as-you-go with credit packs, plus predictable monthly subscriptions. The per-credit rate is the same across packs and subscriptions. See the pricing page for current rates, free credits, and volume options.

FAQ

Do I have to write a polling loop?

No. client.sonic.generateAndWait submits the job and resolves once the audio is ready. If you prefer to manage state yourself, client.sonic.create returns a task_id and client.sonic.getTask polls it.

Does the SDK work in TypeScript and in the browser?

Yes. The package is fully typed and ships both ESM and CommonJS builds. It runs on Node 18 and newer and in browsers, using the global fetch by default.

How are errors and rate limits handled?

Every non-2xx response throws a MusicAPIError with status, code, and message. 429 and 5xx are retried automatically with backoff. Flags like isAuthError, isCreditError, and isRateLimited let you branch without string matching.

Build it in 5 minutes

Get free credits on signup and run real generations before any payment. No credit card required to start.

Start free

API details verified 2026-05-18. The API surface evolves; the pricing page always has current rates.