【Recommandé】 API de profil vocal

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

✅ Chaîne recommandée pour les nouvelles intégrations. D'après les évaluations réelles de nombreux utilisateurs, les chansons générées par cette chaîne conservent très bien la voix d'origine : la voix de la piste finale ressemble davantage à la personne de l'échantillon que vous avez envoyé, c'est donc la voie que nous recommandons actuellement aux clients.

Comparaison : l'API de clonage vocal et de génération avec voix précédente fonctionne toujours, mais le menu la signale comme « non recommandé » et elle n'est plus conseillée pour les nouvelles intégrations.

• Date du document : 2026-09-26
• Périmètre : créer votre propre voix → l'utiliser pour reprendre une chanson choisie / chanter une nouvelle chanson → suivre l'avancement → télécharger les résultats
• Tous les endpoints, champs et réponses ont été vérifiés par des appels réels (ce qui est marqué « mesuré » a été vérifié en détail)

Remarque : ce document ne décrit que les endpoints que vous devez appeler. Le traitement des médias, l'ordonnancement des tâches et la validation du contenu sont assurés automatiquement par le serveur ; le client ne les implémente pas.

0. Prise en main en cinq minutes

Quatre étapes suffisent pour transformer un échantillon vocal en deux chansons finies.

① Créer la voix   POST /api/music/voice-profile/create      → obtenir voice_id (status=ready)
② Reprendre       POST /api/music/voice-profile/cover       → obtenir 2 song_id immédiatement
③ Suivre          POST /api/music/query                     → interroger jusqu'à status=completed
④ Télécharger     GET  /api/music/download?song_id=…&kind=mp3

Exemple minimal (curl) :

API_KEY="sk-votre-cle"
BASE="https://www.suno-api.io"

# ① Créer la voix (envoyer un échantillon vocal ; 10 s ou plus recommandé, moins de 10 Mo)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Ma voix" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Reprendre une chanson avec cette voix (song_clip_id = le clip id de la chanson à reprendre)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntexte des paroles…",
        "style_requirements": "folk lent, guitare acoustique",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Interroger (envoyer plusieurs ids d'un coup, séparés par des virgules)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Télécharger le mp3 une fois terminé (seul status=completed donne un fichier)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Conventions communes

1.1 Domaine et environnement

Tous les chemins ci-dessous sont relatifs à la Base URL ; par exemple l'adresse complète de POST /api/music/voice-profile/create est https://www.suno-api.io/api/music/voice-profile/create.

1.2 Authentification

Tous les endpoints utilisent le même en-tête de requête, dont la valeur est la clé API que vous avez créée dans la console :

Authorization: Bearer sk-xxxxxxxx

• Le préfixe Bearer est facultatif ; celui de sk- aussi (Authorization: sk-xxx fonctionne de la même façon).
• Clé absente ou invalide → HTTP 401, avec un corps du type {"success":false,"message":"…"} (le texte varie selon la langue de la requête).
• Chaque clé ne peut voir et ne peut agir que sur les chansons et les voix de son propre compte.

1.3 Formats du corps de la requête

• Créer une voix : multipart/form-data (envoi d'un fichier) est recommandé ; application/json (une URL ou du base64) est également pris en charge.
• Les autres endpoints : application/json.

1.4 Deux enveloppes de réponse (le client n'a besoin de connaître que celles-ci)

Les endpoints de « gestion des voix » (create / create-from-clip / list / detail / delete) utilisent l'enveloppe métier :

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

La « reprise avec voix » passe par le canal de génération et utilise l'enveloppe de génération : le succès est code/message/data, l'échec un objet error :

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Comment décider : regardez d'abord le code HTTP, puis success === false, enfin code !== 200 ou la présence d'error. Un échec métier ne garantit pas un HTTP différent de 200 (les endpoints de gestion des voix renvoient toujours HTTP 200 en cas d'erreur), vous ne pouvez donc pas vous fier au seul code de statut.

1.5 Idempotence

Créer une voix (y compris « créer à partir d'un audio existant ») est réellement idempotent : sous la même clé, renvoyer le même client_request_id ne crée qu'une seule voix et la seconde tentative renvoie directement le premier résultat (success=true, le même voice_id). L'usage prévu est que le client génère lui-même un id (un UUID, par exemple) et réutilise la même valeur lors d'une nouvelle tentative après un délai dépassé.

L'envoi d'une reprise ne déduplique pas au niveau de la requête (c'est une génération facturée), aussi notez deux points :

1. L'identifiant d'envoi se place dans l'en-tête X-Create-Ui-Client-Request-Id: <votre id d'envoi>. Il est écrit dans l'enregistrement de tâche côté serveur pour faciliter l'investigation ultérieure ; il n'empêche pas un débit en double.
2. Un délai dépassé ≠ un échec : la requête peut déjà avoir été acceptée et être en cours de génération. Avant de réessayer, consultez GET /api/music/songs?p=1&page_size=20 (les paramètres de pagination sont p / page_size ; l'orthographe compatible ps fonctionne aussi) pour voir si une nouvelle chanson avec generation_type=voice_profile_cover est déjà apparue, et ne renvoyez la même requête que si ce n'est pas le cas.

Les corps de create et create-from-clip acceptent aussi un champ client_request_id (voir §3 et §4).

1.6 Aperçu de la facturation

Les prix peuvent être lus à tout moment depuis un endpoint public, donc ne les figez pas dans le code (voir §9) :

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← prix de base d'une reprise avec voix
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← prix du clonage renforcé
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

La reprise utilise un pré-débit + un remboursement en cas d'échec :

• Une requête rejetée (paramètres erronés, un 4xx/5xx de la plateforme, solde insuffisant en soi) n'est pas facturée : lors d'un envoi avec une voix inexistante, le solde n'a pas bougé du tout dans nos mesures (delta = 0) ;
• Une tâche acceptée qui échoue finalement (y compris une erreur de service de la plateforme) passe par la voie de remboursement du serveur et rend le montant pré-débité.

1.7 Dictionnaire des états

Le status de la voix :

Le status de la chanson (la valeur renvoyée par les endpoints de consultation) :

2. Aperçu des endpoints

3. Créer une voix

POST /api/music/voice-profile/create

Enregistrez un extrait d'audio vocal comme « voix » et obtenez un voice_id. Pour la plateforme, une voix n'est que « un audio + son clip dans le catalogue » ; une fois la création réussie, cet audio source est donc conservé définitivement (pour les reprises ultérieures).

3.1 Trois formes d'entrée (choisissez-en une)

Forme A : envoi de fichier multipart (recommandée)

Content-Type: multipart/form-data

file=<binaire audio>         # obligatoire
title=<nom de la voix>       # facultatif ; si vide, le nom du fichier sans extension
file_name=<nom d'origine du fichier>
source_file_name=<nom d'origine du fichier>
source_kind=upload|record    # facultatif, marque d'origine (envoi / enregistrement) ; par défaut upload
enhanced=false|true          # facultatif, true = clonage renforcé (voir §3.5)
client_request_id=<clé d'idempotence>   # facultatif
voice_id=<ID personnalisé>   # facultatif, rarement utilisé

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Ma voix" \
  -F "source_kind=upload"

Forme B : JSON + une URL d'audio publique

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Ma voix"
      }'

• L'URL doit être un lien direct HTTPS accessible publiquement ; le serveur le télécharge une fois et le stocke dans notre stockage objet.
• Vous pouvez aussi mettre l'adresse dans le champ audio_url, l'effet est équivalent (si les deux sont envoyés, file_url l'emporte).
• Si l'adresse est déjà sur le stockage objet de cette plateforme (*.myqcloud.com/create-ui/voice-source/...), rien n'est retéléchargé : elle est enregistrée directement.

Forme C : JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Ma voix"
}

• Le préfixe data:audio/xxx;base64, comme le base64 pur sont acceptés.
• La taille est limitée (le base64 gonfle de 1,33×), utilisez donc la forme A pour les gros fichiers.

3.2 Exigences sur l'audio

3.3 Réponse

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Ma voix",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Référence des champs (create / list / detail partagent le même ensemble de champs) :

created_at / updated_at sont des horodatages en secondes (10 chiffres), pas en millisecondes.

3.4 Erreurs courantes

3.5 Clonage renforcé (enhanced=true)

Pour les cas où « l'échantillon vocal porte lui-même des paroles protégées / il faut un envoi renforcé ». Facturé au tarif d'envoi renforcé (10 ¥ par appel par défaut, remboursé automatiquement en cas d'échec) :

• La réponse est immédiatement status=processing + task_id (pas encore de clip_id) et l'exécution est asynchrone ;
• Pendant le traitement, utilisez GET /api/music/voice-profile/{voice_id} pour consulter l'avancement, qui renvoie progress_percent / progress_stage / progress_message ;
• À la fin, status passe à ready et clip_id, audio_url, image_url sont complétés ;
• En cas d'échec, status=failed et error_message indique quelque chose comme « l'envoi renforcé a échoué ; le montant a été remboursé automatiquement, réessayez plus tard » ;
• Un clonage renforcé prend nettement plus de temps qu'une création standard (minutes), ne l'attendez donc pas avec un délai synchrone.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Ma voix" -F "enhanced=true"

4. Créer une voix à partir d'un audio existant

Si vous préférez ne pas renvoyer de fichier : copiez directement un audio que vous avez déjà envoyé ou déjà généré en voix. Gratuit et idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id : le clip id d'un audio terminé de votre compte (équivalent au song_id de la chanson).
• Renvoyer le même clip ne crée pas de nouvel enregistrement : cela renvoie directement la voix existante avec reused: true (mesuré).

La réponse reprend tous les champs de §3.3 plus deux champs en lecture seule :

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Erreurs (le message tel que renvoyé ; il est recommandé de l'afficher ou de le localiser) :

5. Liste / détail / suppression des voix

5.1 Liste

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Ma voix", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Les champs sont exactement ceux de §3.3. Par défaut, les voix supprimées ne sont pas renvoyées.

5.2 Détail

GET /api/music/voice-profile/{voice_id}

Renvoie un seul objet de voix (data est l'objet lui-même, pas un tableau). Tant qu'un clonage renforcé est en cours, il ajoute en plus :

5.3 Suppression

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Après suppression, la voix disparaît de la liste et ne peut plus servir aux nouvelles reprises : un envoi avec ce voice_id renvoie 400 (voir §6.4).
• Les chansons déjà générées avec elle ne sont absolument pas affectées ; lecture, téléchargement, prolongation, remplacement et séparation fonctionnent comme avant.
• Supprimer une voix inexistante, ou qui n'appartient pas à ce compte, renvoie {"success":false,"message":"voice not found"}.

6. Reprendre avec une voix (l'endpoint central)

POST /api/music/voice-profile/cover
Content-Type: application/json

Un envoi génère 2 chansons (comme la génération ordinaire).

6.1 Deux scénarios

Le resolved_scene de la réponse renvoie cover ou sing, ce qui vous permet de confirmer la voie suivie.

6.2 Champs de la requête

Il est recommandé d'envoyer aussi l'en-tête X-Create-Ui-Client-Request-Id: <le même id d'envoi> : c'est le seul élément écrit dans l'enregistrement de tâche côté serveur et il sert de clé principale pour l'investigation ultérieure (voir §1.5).

Unités à surveiller : audio_weight / style_weight / weirdness_constraint sont des décimaux de 0 à 1, variety est un entier de 0 à 4 et duration est en secondes. Les confondre entraîne un refus ou des résultats étranges.

Les paroles sont facultatives dans le scénario B (le modèle gère tout seul), mais envoyez toujours lyrics quand un contenu précis doit être chanté.

6.3 Réponse

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Tâche] Ceci est une reprise. … (la partie structurelle fixe du serveur + les consignes de reprise / de style que vous avez saisies)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Points clés :

1. Identifiez les chansons finies avec clips[].song_id (cet endpoint ne renvoie pas de champ id).
2. Vous obtenez 2 valeurs de song_id immédiatement, alors que status est encore processing (ce qui signifie seulement qu'elles ont été acceptées) et que audio_url est vide ; il faut interroger jusqu'à completed avant de télécharger. play_url est le flux d'écoute de la plateforme, il peut déjà apparaître à l'envoi et expirera.
3. description est le prompt que le serveur envoie finalement (la partie structurelle fixe + les cover_requirements / style_requirements que vous avez saisis) ; c'est très utile pour enquêter sur un résultat.
4. source_updates est le résultat du traitement des médias côté serveur et le client peut l'ignorer.
5. Le title que vous envoyez est écrit dans l'enregistrement de tâche côté serveur et apparaît comme song_title dans les consultations ultérieures ; que clips[].song_title soit vide dans la réponse d'envoi est normal.

6.4 Erreurs

{ "error": { "message": "cette voix n'existe pas ou a été supprimée (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Un solde insuffisant renvoie une erreur de facturation dès l'envoi et ne laisse jamais de tâche à moitié faite.

6.5 Modèles disponibles (noms côté client)

Utilisez les noms de modèles côté client (ceux ci-dessus). chirp-* sont des noms internes à la plateforme et ne doivent pas être utilisés directement.

7. Suivre l'avancement

7.1 Consultation par lot (recommandée)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids est une chaîne séparée par des virgules (pas un tableau).
• La réponse est un tableau nu (directement [...], sans enveloppe success / data) :

[
  {
    "song_id": "0f2a…",
    "song_title": "Deux tigres",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Tâche] Ceci est une reprise. … (le prompt final du serveur)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Conseil d'interrogation : toutes les 5 à 10 secondes, avec un délai global de 10 à 15 minutes (le compte froid le plus lent mesuré a pris environ 4 min 30 ; de très rares cas prennent plus longtemps). Ne jugez pas la fin au fait que audio_url est vide : utilisez status.

Note de compatibilité : cet endpoint identifie les chansons par song_id ; quelques anciennes réponses comportaient un champ id, donc row.song_id || row.id est la façon sûre de le lire.

7.2 Détail d'une chanson

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Deux tigres",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Deux tigres",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Ici created_at / completed_at sont des secondes Unix (contrairement aux chaînes ISO de la consultation par lot, les clients doivent donc les distinguer).
• wav_url / video_url sont les entrées de téléchargement de cette plateforme (relatives au domaine courant) et un GET récupère le fichier ; ce sont des chaînes vides quand la plateforme n'a pas produit ce média.
• parameter_retention indique à quels paramètres d'envoi cette chanson peut être rattachée : core_parameters_available=true signifie que les paramètres centraux (paroles / style / source) sont consultables, et avec extended_parameters_available=false les paramètres étendus listés ci-dessus n'ont pas été conservés (les reprises avec voix sont actuellement dans cette catégorie).

7.3 Ma liste d'œuvres

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=mot-clé

Paramètres de pagination : p (numéro de page, à partir de 1) / page_size (éléments par page ; ps est une orthographe compatible). status et q facultatifs (un mot-clé du titre). Tri par date de création décroissante par défaut.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Deux tigres",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Utilisez generation_type=voice_profile_cover pour distinguer « les chansons issues d'une reprise avec voix » des autres résultats de génération.

8. Télécharger les chansons finies

8.1 Prendre le mp3 directement (recommandé, gratuit)

Les trois fonctionnent ; choisissez-en une :

1. Utiliser l'audio_url du résultat de consultation (un lien direct vers le stockage objet, le plus simple).
2. GET /api/music/download?song_id=<id>&kind=mp3 → renvoie directement le flux d'octets audio (avec le nom du fichier déjà dans Content-Disposition).
3. POST /api/music/download-url (pour obtenir une adresse temporaire signée).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Valeurs de kind : mp3 (équivalent à song) / playback (lecture en streaming) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) n'est disponible que pour certaines chansons pour l'instant ; en cas d'échec, générez le fichier vous-même avec l'API des paroles horodatées. La réponse est le flux d'octets du fichier, avec Content-Type et Content-Disposition (nom du fichier) déjà définis ; les wav_url / video_url renvoyés par GET /api/music/songs/{song_id} sont la même entrée avec kind=wav|video.

8.2 Convertir en wav / récupérer les paroles / les métadonnées (facturé)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files accepte : mp3 / wav / lyrics / metadata, jusqu'à 10 chansons à la fois.
• Facturé par chanson réussie (0,2 ¥ chacune) ; une chanson entièrement en échec n'est pas facturée, et un format en échec n'apparaît que dans songs[].errors.
• Pour récupérer des fichiers déjà obtenus auparavant, utilisez d'abord l'endpoint gratuit POST /api/music/free2/cached (les mêmes song_ids + files) afin d'obtenir des adresses archivées ; ses songs[].missing_files listent les formats non mis en cache qu'il faut préparer à nouveau.

9. Consulter les prix

GET /api/pricing/catalog

Un endpoint public ne nécessitant aucune authentification. Tous les prix unitaires que le client doit afficher sont dans data.catalog.meta (chaînes) :

Les prix sont ajustés dans le back-office, donc lisez-les en direct plutôt que de les figer dans le client. Le débit réel d'une reprise = voice_generation_price × (max_mode_factor en plus si max_mode est vrai).

10. Limites et mises en garde

1. Taille d'envoi : ≤ 10 Mo (le serveur accepte davantage, mais la passerelle d'entrée tronque les corps surdimensionnés à 10 MiB, ce qui se manifeste par « rejeté par Suno » ; bloquez-le d'abord de votre côté).
2. Durée de l'échantillon : au moins 6 s, 10–60 s recommandé ; trop court et la plateforme refuse.
3. Contenu de l'échantillon : voix propre ; évitez tout ce qui ressemble de près à un enregistrement existant (la comparaison du catalogue le refuse).
4. Limites de texte : lyrics ≤ 3000 caractères ; il est conseillé de garder style_requirements / negative_tags / title dans 1000 / 1000 / 100 caractères respectivement (les exigences de style et de reprise sont concaténées au prompt, gardez donc le total sous 3000 caractères).
5. Les paroles ne sont pas réécrites : ce que vous passez est ce qui est chanté (caractère par caractère), sans troncature locale.
6. Chaque chanson produit 2 pistes ; ne supposez pas un résultat unique.
7. L'audio source est conservé définitivement : supprimer une voix ne nettoie pas son audio source ; cela maintient les reprises ultérieures possibles et la traçabilité de conformité.
8. La voix doit être prête : une voix en processing ne peut pas servir aux reprises.
9. Délai de la requête : sur un compte froid, le premier envoi a pris jusqu'à environ 4 min 30 dans nos mesures, réglez donc le délai client à ≥ 6 minutes. Les reprises ne dédupliquent pas au niveau de la requête, donc après un délai dépassé, vérifiez si une nouvelle chanson est déjà apparue (§1.5) avant de décider de renvoyer.
10. Propriété de la voix : les voix appartiennent à leur créateur ; une reprise n'accepte que les voix prêtes et non supprimées. Une voix inexistante, supprimée ou appartenant à un autre compte renvoie 400 : cette voix n'existe pas ou a été supprimée (voice_id=…).

11. Questions fréquentes (FAQ)

Q1. Créer une voix coûte-t-il de l'argent ? La création standard et « créer à partir d'un audio existant » sont gratuites ; seules les reprises (1,2 ¥ / MAX 2,4 ¥) et les clonages renforcés (10 ¥ par défaut) sont facturés.

Q2. Puis-je utiliser comme échantillon une chanson finie avec accompagnement ? Déconseillé. Tout ce qui contient de la musique, ou ressemble de près à un enregistrement existant du catalogue, est refusé par la plateforme (This audio matches an existing recording in our catalog.). Utilisez un enregistrement purement vocal et sec.

Q3. Pourquoi audio_url est-il vide après l'envoi d'une reprise ? L'envoi signifie seulement que la tâche a été acceptée et status est encore processing. Une adresse lisible/téléchargeable n'apparaît qu'après avoir interrogé /api/music/query jusqu'à status=completed.

Q4. Faut-il envoyer des paroles dans le scénario B (sans song_clip_id) ? Facultatif. Envoyez lyrics pour chanter un contenu précis ; sans cela le modèle gère tout seul, mais avec moins de contrôle.

Q5. Un audio envoyé par le client peut-il servir directement de voix ? Oui : via la forme file_url de create, ou en l'envoyant d'abord comme chanson puis en appelant create-from-clip.

Q6. L'argent est-il remboursé en cas d'échec ? Une requête rejetée d'emblée (paramètres erronés / erreur de la plateforme) n'est pas facturée, d'après nos mesures ; une tâche acceptée qui échoue finalement rend le montant pré-débité. En échec terminal, la tâche indique status=failed plus error_message.

Q7. Après avoir supprimé une voix, puis-je encore écouter les chansons générées avant avec elle ? Oui. La suppression n'affecte que la possibilité d'utiliser cette voix pour de nouvelles reprises.

Q8. Quelle durée de chanson puis-je reprendre d'un coup ? duration accepte de 1 à 480 secondes ; si vous l'omettez, la plateforme décide d'après la chanson d'origine / le média. Attention : les pistes finies de la plateforme font au minimum environ 30 secondes ; avec une valeur plus petite, les mesures donnaient encore 29,96 / 29,76 secondes.

Annexe A : exemple complet (Node.js, avec interrogation et téléchargement)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Créer la voix (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Reprendre
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "folk lent, guitare acoustique",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Interroger jusqu'à la fin (toutes les 5 secondes, 15 minutes au maximum)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // tableau nu
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Télécharger
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Ma voix");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nparoles…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Annexe B : journal des modifications