Présentation de la documentation Suno API

Mis à jour le 2026-09-18 · équipe Suno-API

Une inscription par e-mail suffit pour créer une clé d'API. Une génération coûte 0,6 ¥ et renvoie 2 morceaux, avec téléchargement MP3/WAV, reprises, Extend, séparation de pistes et clonage vocal. URL de base : https://www.suno-api.io.

Cette page présente les modèles disponibles, tous les points d'entrée de génération et d'édition, la facturation et l'ordre de lecture recommandé. Si c'est votre première intégration, lisez-la de haut en bas ; les pistes de diagnostic 401/403/429 s'y trouvent aussi.

Réponses rapides

Comment obtenir une clé d'API ? Inscrivez-vous avec un e-mail, ouvrez la console, allez dans la gestion des jetons et créez un jeton. Aucun numéro de téléphone ni carte bancaire n'est nécessaire.

Combien coûte un appel ? Une génération coûte 0,6 ¥ et renvoie 2 morceaux. Les requêtes de statut, le WAV, les paroles horodatées et les suggestions de prompt sont gratuits.

Quels modèles sont pris en charge ? suno-v6 (par défaut), suno-v6-wild et suno-v6-mini. Les modèles de génération standard v5.5 et antérieurs sont retirés ; les travaux existants ne sont pas affectés.

Quelle est l'URL de base ? https://www.suno-api.io, avec l'en-tête Authorization: Bearer YOUR_API_KEY.

Modèles actuellement disponibles

Les modèles accessibles au client pour la génération standard sont suno-v6, suno-v6-wild et suno-v6-mini. Si model est omis, suno-v6 est utilisé.

Les modèles standard suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 et suno-v5-5 sont retirés. Des tâches historiques peuvent encore afficher ces noms : c'est de l'historique, pas la preuve que le modèle reste utilisable pour de nouvelles requêtes. La séparation de pistes fait exception — voir API de séparation (voix/accompagnement).

Authentification

Tous les points d'entrée publics à clé d'API utilisent les mêmes en-têtes :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL de base :

https://www.suno-api.io

Conventions générales des paramètres

• Un number dans le corps de la requête doit être un nombre JSON, jamais un pourcentage sous forme de chaîne. Une intensité de 50 % s'écrit 0.5, jamais 50 ni 50%.
• Un boolean doit valoir true ou false. N'envoyez pas true, false, 0 ou 1 comme substituts.
• Les champs marqués « non » peuvent être totalement omis. En cas de doute sur un paramètre, omettez-le et laissez le service appliquer son comportement par défaut ; n'envoyez pas de chaîne vide, null ou 0 à la place de « non transmis », car 0 est une valeur valide pour certains champs numériques.
• Les noms de champs sont sensibles à l'orthographe. Chaque page indique le champ recommandé et les alias compatibles ; envoyez-les exactement comme dans le tableau. Lorsque la documentation précise que snake_case et camelCase sont acceptés, n'envoyez pas les deux à la fois.
• Tous les champs de durée se terminant par _s ou Seconds sont en secondes et acceptent des décimales. Les horodatages Unix sont décrits séparément, en secondes ou en millisecondes.
• Un identifiant commençant par pending: est un jeton de remplacement de la plateforme, pas un identifiant de morceau réel. Ne l'utilisez que là où un point d'entrée le documente explicitement ; sinon, attendez le song_id réel.

Limites des champs de texte

Dépasser une limite renvoie directement HTTP 400 : rien n'est généré, rien n'est pré-débité et aucune tâche n'est créée. Le comptage se fait en caractères Unicode (un idéogramme compte pour 1) et les espaces en début et fin comptent aussi.

Le message d'erreur indique le champ fautif et la longueur mesurée : ces deux nombres suffisent pour ajuster le texte.

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Concerne : /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Une exception : le champ description de POST /api/music/sounds est limité à 100 caractères, car le chemin des effets sonores applique la limite plus courte de la plateforme.

Génération asynchrone et adresses audio

Les points d'entrée de génération musicale fonctionnent par défaut de façon asynchrone. Lorsque la première réponse porte un status à pending, submitted ou processing, un audio_url, video_url ou cover_url vide est normal et ne signifie pas un échec. Conservez le song_id réel (ou le client_request_id renvoyé) et interrogez le point d'entrée de requête correspondant ; ne lisez et ne téléchargez une adresse audio qu'une fois le statut terminé.

⚠️ Les adresses audio expirent au bout de 7 jours — transférez vos fichiers à temps

audio_url, wav_url, video_url et les adresses renvoyées par les points d'entrée de téléchargement sont servies depuis le stockage objet de la plateforme et expirent par défaut au bout de 7 jours (les fichiers sont recyclés ; une ancienne adresse renvoie 404 / échoue au téléchargement).

• Dans ces 7 jours, copiez les fichiers dans votre propre stockage (votre stockage objet, un CDN ou un disque de serveur). Ne traitez pas nos adresses comme des liens durables.
• Une adresse expirée n'oblige pas à régénérer le morceau et n'entraîne aucun frais supplémentaire : rappelez l'API de requête des morceaux (ou l'API de téléchargement des médias) pour obtenir une nouvelle adresse valide.

Temps d'attente et réglage des délais

Les points d'entrée de génération sont synchrones : la commande n'est acceptée et transmise à la plateforme qu'au retour de la réponse. Avant cela, le service doit planifier un compte et passer le contrôle de sécurité nécessaire, sans aucune réponse intermédiaire — aucun autre point d'entrée ne voit la commande. La seule preuve fiable qu'« une génération a eu lieu » est donc la réponse elle-même, pas ce que l'on observe pendant l'attente.

Temps d'attente mesurés (production, famille /api/music/create, du 18 au 20 septembre 2026)

• Environ 10 % des requêtes dépassent 30 secondes et environ 1 % prennent 1 à 2 minutes. Une requête lente signifie en général qu'elle a dû passer un contrôle de sécurité.
• Les champs, la forme des réponses, les codes d'erreur et la facturation sont inchangés : les intégrations existantes n'ont qu'à augmenter le délai d'attente du client, sans autre modification de code.

Exigences d'intégration

1. Réglez le délai d'attente du client à 300 secondes ou plus. Les clients réglés à 30, 60 ou 120 secondes coupent la connexion pendant l'attente.
2. L'absence de réponse ne signifie pas l'absence de génération. En cas de délai dépassé ou de connexion coupée, la commande peut déjà être acceptée et en cours de génération.
3. Ne réessayez pas immédiatement après un délai dépassé : une soumission en double crée une seconde commande et refacture.
4. Si la connexion a été coupée, listez vos morceaux avec GET /api/music/songs (du plus récent au plus ancien) un peu plus tard — les commandes acceptées apparaissent normalement. Ne resoumettez qu'après avoir confirmé que la commande est réellement absente.
5. Pour un incident, joignez l'en-tête de réponse X-Oneapi-Request-Id afin que la requête concernée soit identifiée directement.

Vous préférez ne pas garder une longue connexion ? Utilisez le mode accusé de réception. POST /api/music/create et POST /api/music/create/custom acceptent un accusé facultatif : ajoutez "accept_mode": "async" au corps (ou l'en-tête X-Accept-Mode: async) et le point d'entrée renvoie immédiatement 202 avec un numéro d'accusé, la génération se poursuivant en arrière-plan ; suivez la progression avec GET /api/music/requests/{request_id}. Un client limité à quelques dizaines de secondes ne peut plus confondre « pas de réponse » et « rien de généré », ni facturer deux fois à cause d'un nouvel essai. Voir « Mode accusé de réception » dans l'API de génération en mode simple.

Pour référence : python requests utilise timeout=300, urllib utilise urlopen(..., timeout=300), Node utilise req.setTimeout(300000), curl utilise --max-time 300.

Liste des points d'entrée recommandés

Les points d'entrée /api/voice/clone/* et /api/music/generate-with-voice relèvent de la chaîne de clonage vocal initiale et ne sont pas recommandés pour une nouvelle intégration ; utilisez plutôt l'【Recommandé】 API de profil vocal.

Paramètres avancés : Max Mode et Variety

Les points d'entrée de génération prennent en charge ces deux paramètres facultatifs (les omettre conserve le comportement et le prix précédents) :

Ces paramètres sont pris en charge par : POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Le doublement en pratique : un point d'entrée à 0,6 ¥ par appel passe à 1,2 ¥ avec max_mode ; générer avec une voix choisie coûte 1,2 ¥ par appel et 2,4 ¥ avec Max Mode ; la reprise vocale de l'【Recommandé】 API de profil vocal coûte aussi 1,2 ¥ par appel (2,4 ¥ avec max_mode).
• variety ne s'applique qu'à la famille suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini) ; l'envoyer avec un autre modèle renvoie 400.
• Les effets sonores, la séparation de pistes, le concat, le WAV et les actions d'édition Studio (crop, suppression de section, fondu, lecture inversée, vitesse, etc.) n'acceptent pas ces paramètres — les envoyer explicitement renvoie 400, afin qu'un paramètre ne soit jamais ignoré en silence.
• variety est l'entier brut 0-4 ; style_weight et weirdness_constraint sont des décimales de 0 à 1, les échelles diffèrent donc.

Champs de réponse communs des morceaux

Les points d'entrée de génération, reprise, extend, séparation et requête renvoient généralement un tableau de morceaux avec ces champs :

Quatre étapes d'intégration (exemple minimal)

Ces quatre étapes suffisent pour obtenir votre premier morceau ; la liste complète des champs de chaque étape figure sur la page correspondante de la liste des points d'entrée recommandés.

# 1) Soumettre une génération : 0,6 ¥, renvoie 2 morceaux
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright French pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Interroger jusqu'à status = completed (3-5 secondes est un bon intervalle)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "le song_id renvoyé à l’étape 1"}'

# 3) Obtenir une adresse média : les points d'entrée de lecture sont gratuits ; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "le même song_id", "kind": "song"}'

En cas de problème : 401 / 402 / 403 / 429 dans le guide des erreurs ; délais dépassés et doubles facturations dans la section « Temps d'attente et réglage des délais » ci-dessus ; le détail de chaque point d'entrée dans la liste ci-dessous.

Recommandations

• Une nouvelle intégration devrait utiliser suno-v6 partout.
• Pour les points d'entrée qui annoncent un prix par défaut, le montant réellement débité suit la configuration tarifaire du back-office et le modèle demandé.
• Les points d'entrée de génération renvoient d'abord une tâche ; récupérez l'audio final via /api/music/query.
• wait_completion=true bloque jusqu'à la fin et convient aux tests à faible volume ; en production, préférez l'interrogation périodique.
• Les points d'entrée de génération peuvent mettre longtemps à répondre — réglez le délai d'attente du client à 300 secondes ou plus et retenez que « pas de réponse » ne veut pas dire « rien de généré » ; voir la section correspondante ci-dessus.
• Les capacités d'envoi, de reprise, de remplacement et de WAV dépendent des comptes de la plateforme et des droits sur le clip source ; en cas d'échec, lisez d'abord le message ou l'error_message renvoyé.

À propos de cette documentation

Cette page a été réorganisée autour des capacités réellement exposées par la Create UI ; une nouvelle intégration devrait la lire en premier. L'ancienne documentation d'API reste disponible dans la section « Ancienne documentation d'API (compatible) » pour ceux qui souhaitent conserver leur méthode.