Guide de démarrage rapide

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

Ce guide vous mène de la création de la clé d'API au premier morceau généré, à la consultation de l'avancement puis au téléchargement de l'audio, en cinq minutes environ. Les exemples sont prêts à être copiés et exécutés.

Le modèle de génération par défaut est suno-v6. Les modèles de suno-v2 à suno-v5-5 sont retirés : ils peuvent subsister dans des tâches anciennes mais n'acceptent plus de nouvelles requêtes.

Téléchargez, installez et configurez suno-api agent kit depuis cette adresse  https://www.suno-api.io/suno-agent-kit.zip

Recommandé : laissez l’IA terminer l’intégration

L’IA lit 00_START_HERE.md et vous aide pour l’inscription, l’enregistrement de la clé API, le solde, la présentation des fonctionnalités et la première génération. Les actions payantes sont confirmées avant exécution et les timeouts ne sont pas relancés automatiquement.

Étape 1 : obtenir une clé d'API

1. Ouvrez https://www.suno-api.io.
2. Cliquez sur Obtenir une clé d'API et inscrivez-vous. Une adresse e-mail suffit, sans numéro de téléphone.
3. Dans la console, ouvrez la gestion des jetons et créez une clé.
4. Copiez-la immédiatement : elle n'est affichée qu'une fois. Rechargez le solde avec un code de recharge avant le premier appel payant.

Étape 2 : configurer la requête

Tous les appels partagent la même URL de base et les mêmes en-têtes :

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Étape 3 : envoyer la première requête

Exemple 1 — générer depuis une phrase

Décrivez le morceau et l'API écrit les paroles, la mélodie et l'arrangement :

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "une chanson folk entraînante sur le premier jour du printemps",
    "model": "suno-v6"
  }'

Réponse :

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Histoire de printemps",
    "description": "une chanson folk entraînante sur le premier jour du printemps",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Pas du printemps",
    "description": "une chanson folk entraînante sur le premier jour du printemps",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Chaque exécution renvoie deux prises différentes pour que vous choisissiez. Une génération coûte 0,6 ¥.

Exemple 2 — consulter l'avancement

Passez les song_id renvoyés à l'endpoint de consultation :

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Pendant le traitement :

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Histoire de printemps",
    "progress": "60%"
  }
]

Une fois terminé :

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Histoire de printemps",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

Le status passe par pending, submitted, processing puis completed. Les adresses peuvent être vides pendant le traitement : jugez d'après le status, pas d'après la présence de audio_url.

Étape 4 : télécharger le fichier

Quand le status vaut completed, récupérez simplement l'audio_url. Les téléchargements MP3 et WAV sont illimités et sans frais supplémentaires. Pour un audio sans perte à monter ensuite, utilisez l'endpoint WAV.

Cas d'usage courants

Musique de fond pour une vidéo

{
  "description": "musique lo-fi calme pour une vidéo produit, sans voix, dynamique régulière",
  "instrumental": true,
  "model": "suno-v6"
}

Avec instrumental à true, la sortie ne contient pas de voix.

Paroles et style personnalisés

{
  "lyrics": "[Verse 1]\nLes lumières de la ville s'éteignent\n\n[Chorus]\nNous continuons d'avancer",
  "style": "acoustic pop, voix féminine chaleureuse, 92 BPM",
  "model": "suno-v6"
}

Interroger jusqu'à la fin

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "une chanson folk sur le printemps", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Gestion des erreurs

Principaux codes

Format d'erreur

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Temps d'attente et timeouts (important) : les points d'accès de génération sont synchrones — la commande n'est acceptée et transmise à la génération qu'à l'arrivée de la réponse. D'après les mesures, la plupart des requêtes répondent en 1 à 3 secondes, environ 10 % prennent plus de 30 secondes et la plus longue avoisine 230 secondes. Réglez le timeout du client à 300 secondes ou plus (le --max-time 300 de l'exemple) ; l'absence de réponse ne signifie pas qu'aucune génération n'a eu lieu, et ne réessayez pas juste après un timeout (cela duplique la commande et refacture). Si la connexion a été coupée, vérifiez plus tard avec GET /api/music/songs. Voir « Temps d'attente et réglage du timeout » dans la Présentation de la nouvelle API.

Bonnes pratiques

• Gardez la clé côté serveur, jamais dans un navigateur ou une application distribuée.
• Interrogez toutes les 10 à 15 secondes plutôt qu'en boucle serrée.
• Conservez les song_id : c'est le seul identifiant pour récupérer l'audio plus tard.
• Réessayez sur 429 et 500 ; corrigez la cause avant de relancer 400 et 401.
• Les échecs sont remboursés automatiquement : une tâche ratée ne coûte rien.
• Timeout du client : un point d'accès de génération n'est accepté qu'au retour de la réponse ; réglez le timeout à 300 secondes ou plus.
• Nouvelles tentatives : ne réessayez que sur un échec explicite (4xx/5xx). Après un timeout ou une coupure, vérifiez d'abord avec GET /api/music/songs si la commande a été acceptée, pour éviter un doublon et une double facturation.

Étapes suivantes

• Authentification — clés, erreurs et limites
• Modèles pris en charge — noms de modèles, pistes et modèles retirés