API de séparation (voix et accompagnement)

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

Description du point d'accès

La séparation découpe un morceau existant en voix, accompagnement ou résultats multipistes. Le flux d'intégration recommandé est le suivant :

1. Si l'audio source n'est pas un morceau généré sur cette plateforme, appelez d'abord l'API d'envoi d'audio source.
2. Appelez POST /api/music/separate pour soumettre la tâche de séparation.
3. Interrogez le résultat avec l'API de consultation et d'historique des morceaux.
4. Utilisez les points d'accès de téléchargement pour récupérer le fichier audio de chaque résultat de séparation.

Point d'accès : POST /api/music/separate

Facturation : Payant. stem_mode=two actuellement 0,6 ¥ par appel par défaut ; stem_mode=twelve est un découpage multipiste et actuellement 3,0 ¥ par appel par défaut. Le montant réellement facturé suit la configuration tarifaire du back-office.

Temps d'attente et timeouts (important) : c'est un point d'accès synchrone — 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 ; 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.

Authentification

Paramètres de la requête

À propos de stem_mode

À propos de la séparation

La séparation est une capacité fixe et indépendante : il n'y a pas de modèle de génération de morceaux à renseigner ni à choisir. Le client envoie simplement le morceau source et stem_mode ; le serveur s'en charge selon le mode.

D'où viennent les nombres : une soumission produit 2 versions (deux résultats du même matériel), donc le nombre est 2 × les pistes de ce mode : 4 pour two et 24 pour twelve. Fiez-vous toujours à la longueur réelle du tableau clips dans la réponse ; n'écrivez pas de boucle sur un nombre fixe (une piste peut échouer et les pistes réussies sont renvoyées normalement).

Quelles pistes chaque mode renvoie

Les 12 pistes du mode twelve (les noms sont fixés par la plateforme ; l'ordre peut varier) :

Le mode two renvoie deux pistes, (Vocals) et (Instrumental), chacune en 2 versions. Les titres de pistes de two et twelve sont des noms fixes (ils ne portent pas le nom du morceau source), donc n'espérez pas déduire du titre de quel morceau il s'agit.

Les titres de pistes ne peuvent pas servir de clé unique. Les deux versions contiennent des pistes de même nom (par exemple deux (Vocals), deux (Strings)), et une séparation renvoie de nombreuses pistes. Utilisez toujours song_id comme identifiant et song_title uniquement pour l'affichage ; n'utilisez pas non plus les index du tableau (l'ordre peut changer).

Exemples de requête

Séparation voix / accompagnement (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Découpage multipiste (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Réponse

En cas de succès, un tableau de résultats de séparation est généralement renvoyé. Chaque résultat est un clip de morceau indépendant et doit continuer à être interrogé jusqu'à ce que status passe à un état terminé.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Ci-dessus, seules 2 des 4 entrées du mode two sont montrées ; en pratique 4 sont renvoyées (2 versions × {(Vocals), (Instrumental)}) ; le mode twelve en renvoie 24. Le nombre réel correspond à la longueur du tableau clips.

Le client n'a généralement besoin de conserver que clips[].song_id ; les consultations et téléchargements suivants s'articulent autour de ces ID.

Remarques

• Les résultats de séparation n'apparaissent pas dans l'historique de GET /api/music/songs (cette liste ne renvoie que les morceaux générés ordinaires). Après une soumission réussie, conservez clips[].song_id immédiatement, sinon vous ne pourrez plus les retrouver.
• Chaque piste est une œuvre indépendante : chaque piste a son propre song_id et doit être interrogée jusqu'à la fin puis téléchargée séparément.
• La facturation est indépendante du nombre d'entrées : elle se fait par appel (two 0,6 ¥ par appel, twelve 3,0 ¥ par appel), et 4 ou 24 entrées coûtent le même prix.
• Téléchargement : utilisez le song_id de cette piste avec POST /api/music/download-url / download-file (gratuit), ou directement l'audio_url du résultat de la consultation ; pour le MIDI, voir l'API de récupération MIDI.
• Ne soumettez pas deux fois : la séparation est un point d'accès synchrone, donc après un timeout confirmez d'abord avec la consultation des morceaux au lieu de réessayer tout de suite (cela duplique la commande et refacture).
• Masquez les pistes devenues inutiles avec l'API de suppression des stems.

Consulter les résultats de séparation

Après une soumission réussie, interrogez les résultats avec clips[].song_id via POST /api/music/query.

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": "stem_clip_id_1,stem_clip_id_2"
  }'

Exemple de consultation terminée :

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Télécharger les fichiers de stems

Une fois un résultat de séparation terminé, vous pouvez télécharger un fichier de stem individuel avec le point d'accès de téléchargement.

Point d'accès : POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind accepte :

Pour empaqueter les ressources liées à un résultat de séparation, appelez :

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Description des statuts

Erreurs courantes

Notes de compatibilité

L'ancienne documentation utilisait des exemples à objet unique comme success/task_id/vocals_url/instrumental_url. La séparation actuelle s'appuie sur le tableau de morceaux clips[] : chaque résultat de séparation possède son propre song_id, et les consultations et téléchargements suivants s'articulent autour de ces song_id.

Pages associées

• Si vous voulez seulement séparer la voix et l'accompagnement sans choisir de mode, utilisez l'API de suppression de la voix ; c'est la forme rapide à deux pistes de ce point d'accès et elle est actuellement gratuite.
• Masquez les pistes de séparation devenues inutiles avec l'API de suppression des stems (suppression logique, sans frais).
• Pour le MIDI d'un stem, voir l'API de récupération MIDI ; pour l'audio, la pochette et les autres médias, l' API de téléchargement et d'écoute des médias de morceaux.