Suno Client: driving Suno from Node.js

Suno Client 0.1.0 went out on npm at noon today. It’s a TypeScript client for Node that drives Suno: start a generation, follow songs in progress, retrieve the audio, the lyrics and the musical data. I wrote it for the music on my streams, and it’s open source, on GitHub.

First things first: this is not an official API

Suno has no public API. Suno Client talks to the web app’s endpoints with your browser session, which is outside Suno’s terms of service. A ban would land on a paid account, the very one that presumably holds the commercial rights to your songs. The repository says so at the top of the page, and I’ll say it again here: decide whether that risk works for you before building on it.

The real problem: knowing when Suno moves

Every unofficial client breaks eventually, because Suno changes its API and nobody notices before production does. In early August 2026, Suno stopped accepting a missing title, and the most complete open-source client stayed broken for two weeks. Its 134 tests saw nothing: they checked its own output format and never touched the network.

So Suno Client is built around a single question: how do you find out Suno changed before your users do it for you?

Three safeguards

A free schema probe. Suno checks a request’s format before anything else. So a request in the right format but naming a model that doesn’t exist gets rejected without generating anything and without costing a credit, and the reason for the rejection tells you whether your format is still accepted. If Suno complains about the token, all is well; if it complains about a field, the format has moved, and the probe names the field. It keeps working when the account is behind a captcha.

Free in credits, the probe isn’t free in reputation: each attempt is a rejected create, and a burst looks like abuse. During development, it actually tripped the test account’s captcha. So it runs once a day, with a single variant.

A fingerprint of every response. The Zod schemas let unknown fields through, so an addition on Suno’s side never breaks parsing. Alongside, every response is compared with a reference fingerprint: a new field is just information, while a field the client reads that disappears or changes type is an error.

Errors that say what to do. Every error carries two flags: retryable, the same request may succeed later, and alert, a human is needed. A long-running program keeps going through the first kind and stops loudly on the second. Treating a format change as a passing glitch means burning credits on requests that will never succeed.

Built for a live stream

A Suno generation takes about two minutes, and that’s exactly the interesting part when you narrate it live. So starting a generation returns a job you follow song by song:

const job = await suno.generate({ title, tags, lyrics });

for await (const update of job.watch()) {
  for (const clip of update.changed) {
    await chat.say(`${clip.title}: ${clip.status}`);
  }
}

The job can be resumed after a restart, from the song ids. And a single call, suno.track(), returns everything an overlay needs: title, style, lyrics, cover art, word-by-word lyric timings, bar lines, tempo and key. The bar lines come from Suno’s own beat grid, not from a fixed tempo, so visuals stay locked even when the song slows down. That data comes from endpoints that, as far as I know, no other unofficial client exposed yet.

Three things to keep in mind when requests come from strangers: text Suno rejects arrives as invalid_input, so answer in chat and don’t retry; an account behind a captcha can’t generate anymore, and only a human on suno.com can clear it; each call costs 10 credits and returns two songs.

Install

npm install suno-client, on Node 22 or newer. The package ships as ESM and CommonJS, with its types, and version 0.1.0 passes 262 tests. For the licence I picked the WTFPL: putting terms on a reverse-engineered client would have been a joke of a different kind.

The details of what works, what doesn’t and what it cost to find out are in docs/STATUS.md. Much music. Such types.