Suno Client : piloter Suno depuis Node.js

Suno Client 0.1.0 est publié sur npm ce midi. C’est un client TypeScript pour Node qui pilote Suno : lancer une génération, suivre les morceaux en cours, récupérer l’audio, les paroles et les données musicales. Je l’ai écrit pour la musique de mes directs, et il est open source, sur GitHub.

Avant toute chose : ce n’est pas une API officielle

Suno n’a pas d’API publique. Suno Client parle aux points d’accès de l’application web, avec votre session de navigateur, ce qui sort des conditions d’utilisation de Suno. Un bannissement tomberait sur un compte payant, celui-là même qui détient sans doute les droits commerciaux de vos morceaux. Le dépôt le dit en tête de page, et je le redis ici : décidez si ce risque vous convient avant de construire dessus.

Le vrai problème : savoir quand Suno bouge

Tous les clients non officiels finissent par casser, parce que Suno modifie son API et que personne ne s’en aperçoit avant la production. Début août 2026, Suno a cessé d’accepter un titre non renseigné, et le client open source le plus complet est resté en panne deux semaines. Ses 134 tests n’ont rien vu : ils vérifiaient son propre format de sortie et ne touchaient jamais le réseau.

Suno Client est donc construit autour d’une seule question : comment apprendre que Suno a changé avant que vos utilisateurs ne s’en chargent ?

Trois garde-fous

Une sonde de schéma gratuite. Suno vérifie le format d’une requête avant le reste. Une requête au bon format mais qui vise un modèle inexistant est donc refusée sans rien générer et sans coûter de crédit, et la raison du refus dit si notre format est toujours accepté. Si Suno se plaint du jeton, tout va bien ; s’il se plaint d’un champ, le format a bougé, et la sonde nomme le champ. Elle continue de fonctionner quand le compte est bloqué par un captcha.

Gratuite en crédits, la sonde ne l’est pas en réputation : chaque essai est une création refusée, et une rafale ressemble à un abus. Pendant le développement, elle a d’ailleurs déclenché le captcha du compte de test. Elle ne tourne donc qu’une fois par jour, avec une seule variante.

Une empreinte des réponses. Les schémas Zod laissent passer les champs inconnus, pour qu’un ajout de Suno ne casse jamais la lecture. À côté, chaque réponse est comparée à une empreinte de référence : un champ nouveau est une simple information, un champ que le client lit et qui disparaît ou change de type est une erreur.

Des erreurs qui disent quoi faire. Chaque erreur porte deux indications : retryable, la même requête pourra réussir plus tard, et alert, il faut un humain. Un programme qui tourne longtemps traverse les premières et s’arrête bruyamment sur les secondes. Traiter un changement de format comme un incident passager, c’est brûler des crédits sur des requêtes qui ne réussiront jamais.

Pensé pour un direct

Une génération Suno prend environ deux minutes, et c’est justement la partie intéressante quand on la raconte en direct. Lancer une génération rend donc une tâche qu’on suit morceau par morceau :

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}`);
  }
}

La tâche se reprend après un redémarrage, à partir des identifiants des morceaux. Et un seul appel, suno.track(), rend tout ce qu’il faut à un overlay : titre, style, paroles, pochette, paroles minutées mot à mot, mesures, tempo et tonalité. Les mesures viennent de la grille rythmique calculée par Suno, pas d’un tempo fixe : les visuels restent calés même quand le morceau ralentit. Ces données sont lues sur des points d’accès qui, à ma connaissance, ne figuraient encore dans aucun autre client non officiel.

Trois choses à garder en tête quand les demandes viennent d’inconnus : un texte refusé par Suno arrive comme invalid_input, il faut répondre dans le chat et ne pas réessayer ; un compte bloqué par un captcha ne peut plus générer, et seul un humain sur suno.com peut le débloquer ; chaque appel coûte 10 crédits et rend deux morceaux.

Installer

npm install suno-client, sous Node 22 ou plus. Le paquet est livré en ESM et en CommonJS, avec ses types, et la version 0.1.0 passe 262 tests. Pour la licence, j’ai choisi la WTFPL : mettre des conditions sur un client issu de la rétro-ingénierie aurait été une plaisanterie d’un autre genre.

Le détail de ce qui marche, de ce qui ne marche pas et de ce que ça a coûté d’apprendre est dans docs/STATUS.md. Much music. Such types.