API de clonage vocal et de génération avec voix (non recommandé)

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

⛔ Ancienne chaîne, non recommandée pour les nouvelles intégrations. Cette page décrit la chaîne persona d'origine (voice_task_id / generate-with-voice). Elle fonctionne toujours, mais n'est plus recommandée aux clients ; le menu de gauche la signale comme « non recommandé ».

Pour une nouvelle intégration, utilisez l'【Recommandé】 API de profil vocal : créez un profil vocal à partir d'un échantillon de voix (POST /api/music/voice-profile/create), puis servez-vous-en pour reprendre une chanson choisie ou pour en chanter une nouvelle. Le profil vocal est une ressource de premier ordre : il peut être listé, consulté et supprimé, et son audio source est conservé de façon permanente.

Si votre produit a besoin de la boucle complète « créer une voix → la réutiliser durablement → reprendre des chansons », privilégiez la nouvelle chaîne.

Avertissement important : une voix clonée peut expirer.

Le voice_id / voice_task_id produit par le clonage vocal n'est pas une ressource utilisable indéfiniment : il peut cesser de fonctionner à cause de sa durée de validité, de l'état du compte ou de l'état de la voix. Les intégrateurs ne doivent pas cloner une fois puis réutiliser pour toujours un identifiant de voix mis en cache localement.

Bonne pratique :

• Conservez voice_task_id, voice_id, is_available, updated_at et l'heure de la dernière génération réussie.
• Avant chaque génération avec une voix clonée, appelez GET /api/voice/clone/tasks/{voice_task_id} ou POST /api/voice/clone/tasks/{voice_task_id}/check et confirmez que is_available=true.
• Si l'endpoint renvoie que la voix est indisponible, que la tâche n'existe pas ou selected voice is not ready, invitez l'utilisateur à cloner à nouveau ou à choisir une autre voix disponible.
• Ne promettez pas à l'utilisateur final qu'une voix clonée est un « actif permanent » ; indiquez dans l'interface du produit que « la voix peut expirer et nécessiter une nouvelle validation ou un nouveau clonage ».

Description du point d'accès

Ce groupe d'endpoints crée une voix réutilisable et génère des chansons avec elle. L'appelant n'a besoin que de la clé API émise par la plateforme ; le serveur se charge de la soumission des tâches, de la synchronisation d'état, de la facturation et des téléchargements.

Authentification : Authorization: Bearer YOUR_API_KEY

Facturation :

• Validation de voix, clonage vocal, consultation d'état, suppression et téléchargements : gratuits.
• L'entrée de clonage en une étape de l'espace de travail : 5 ¥ fixes par appel ; elle réalise automatiquement la validation de la voix source et le second audio de vérification, et rembourse en cas d'échec.
• Enchaîner automatiquement sur l'audio de vérification après un clonage ordinaire : 5 ¥ fixes par appel ; remboursé en cas d'échec selon le flux existant.
• Générer une chanson avec une voix clonée : payant, 1,2 ¥ fixes par appel ; chaque appel renvoie généralement 2 tâches de substitution.
• Avec le Max Mode activé (max_mode: true sur POST /api/music/generate-with-voice), les 1,2 ¥ par appel sont facturés au double, soit 2,4 ¥ par appel ; la génération de voix prend aussi en charge variety (0-4, sans surcoût) ; les règles de valeur se trouvent dans la section « Paramètres avancés » de la présentation de la nouvelle API.

Déroulé des appels

1. Appelez POST /api/voice/clone/validate pour envoyer la voix source et obtenir un voice_task_id.
2. Attendez ou interrogez GET /api/voice/clone/tasks/{voice_task_id} jusqu'à obtenir validate_info.
3. L'utilisateur lit ce texte à voix haute et enregistre l'audio de vérification.
4. Appelez POST /api/voice/clone/tasks/{voice_task_id}/generate pour soumettre l'audio de vérification.
5. Appelez POST /api/voice/clone/tasks/{voice_task_id}/check ou continuez à interroger la tâche jusqu'à is_available=true.
6. Appelez POST /api/music/generate-with-voice pour générer une chanson avec cette voix.
7. L'endpoint de génération renvoie d'abord des tâches de substitution ; une fois la génération terminée et le song_id réel obtenu, les endpoints de téléchargement permettent de récupérer un fichier unique ou une archive.
8. (Facultatif) Quand la voix n'est plus nécessaire, appelez DELETE /api/voice/clone/voices/{voice_task_id} pour la supprimer ; la sémantique est en section 6.

Il existe aussi le clonage en une étape : sur la première page d'enregistrement/d'envoi de voix de l'espace de travail, vous pouvez choisir de tout terminer d'un coup ; le système réalise alors la validation et la création de la voix ensemble, sans que vous ayez à enregistrer un second audio de vérification ; facturé 5 ¥ par appel, remboursé en cas d'échec.

Champs de la tâche de voix

1. Soumettre la voix source à validation

Point d'accès : POST /api/voice/clone/validate

Paramètres du corps

vocal_end_s - vocal_start_s doit respecter le minimum de segment vocal. Envoyez un enregistrement vocal clair, sans accompagnement ni bruit manifestes.

Exemple de requête

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Ma voix féminine en chinois",
    "description": "Voix féminine en chinois, claire et naturelle",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Ma voix féminine en chinois",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Interroger une tâche de voix

Point d'accès : GET /api/voice/clone/tasks/{voice_task_id}

Exemple de requête

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Ma voix féminine en chinois",
      "validate_info": "Lisez à voix haute le texte de vérification renvoyé ici",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Régénérer le texte de vérification

Point d'accès : POST /api/voice/clone/tasks/{voice_task_id}/regenerate

À appeler lorsque le texte de vérification ne se prête pas à une lecture à voix haute ou qu'une nouvelle validation est nécessaire.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Soumettre l'audio de vérification et créer la voix

Point d'accès : POST /api/voice/clone/tasks/{voice_task_id}/generate

Paramètres du corps

Exemple de requête

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Ma voix féminine en chinois"
  }'

5. Vérifier si la voix est utilisable

Point d'accès : POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Quand la tâche est utilisable, is_available vaut true dans la réponse et un voice_id est renvoyé.

6. Supprimer une voix

Point d'accès : DELETE /api/voice/clone/voices/{voice_task_id}

Facturation : gratuite.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Ce qui se passe après la suppression

• La voix ne peut plus générer de nouvelles chansons : appeler POST /api/music/generate-with-voice avec ce voice_task_id (ou son voice_id) est refusé avec le message selected voice is not ready, sans aucun débit.
• Les chansons déjà générées avec elle ne sont pas affectées du tout : lecture, téléchargement, prolongation, remplacement et séparation fonctionnent comme avant.
• Cette tâche de voix disparaît des requêtes : GET /api/voice/clone/tasks/{voice_task_id} renvoie record not found.
• L'audio source est conservé selon la politique de conservation permanente de la plateforme (depuis le 2026-09-23, la suppression n'efface plus l'échantillon vocal que vous avez envoyé), mais cela ne signifie pas qu'il est récupérable : cette ancienne tâche est terminée et, pour continuer avec la même voix, il faut refaire tout le parcours de clonage, ce qui donne un nouveau voice_task_id.
• Suppression en double : supprimer à nouveau la même tâche renvoie record not found (elle est déjà à l'état supprimé et n'est plus consultable).

7. Générer une chanson avec une voix clonée

Point d'accès : POST /api/music/generate-with-voice

Facturation : 1,2 ¥ par appel.

Paramètres du corps

suno-v6, suno-v6-wild et suno-v6-mini sont pris en charge ; un modèle vide est traité comme suno-v6. Les anciens modèles V5/V5.5 sont retirés, mais d'anciennes tâches peuvent encore afficher leurs noms.

La structure de requête partagée interprète aussi des champs de compatibilité Create UI comme task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId et voiceId, mais ce ne sont pas des paramètres client valides pour cet endpoint : la tâche de voix doit être envoyée via voice_task_id, la vérification facultative de voix via voice_id, et la génération musicale avec voix ne lit jamais les champs sound.

Comment remplir les paramètres de génération

• Avec customMode=false, prompt contient la description de la chanson ; avec customMode=true, prompt contient les paroles complètes, et style et title doivent aussi être renseignés. N'envoyez pas les paroles dans le champ de description du mode inspiration et ne traitez pas une description de chanson comme des paroles de mode avancé.
• weirdnessConstraint et styleWeight sont des proportions décimales de 0.0 à 1.0 ; on ne peut pas envoyer 50 ni 50%. 0.5 est une valeur équilibrée ; les omettre signifie « non spécifié », et 0 est une valeur explicite valide.
• vocalGender n'accepte que m, male, f ou female. instrumental n'est qu'un champ de compatibilité sur cet endpoint : la génération avec voix clonée est toujours traitée comme une chanson chantée.
• waitAudio ne change pas le comportement ici ; l'endpoint renvoie toujours les tâches de substitution de façon asynchrone. Un audio_url vide dans le résultat initial est normal : interrogez avec client_request_id et ne lisez l'adresse audio qu'une fois le résultat terminé.

En-têtes

Comportement de Idempotency-Key :

• La première requête écrit un enregistrement d'idempotence persistant avant la facturation ;
• Si la même clé avec la même requête est déjà terminée, la première réponse d'acceptation est rejouée, sans second débit ni seconde tâche ;
• La même clé avec un corps différent est refusée ;
• La même clé encore en cours renvoie une erreur « en cours » stable, et n'expose un client_request_id sûr que lorsqu'il a été généré ;
• Après l'échec de la première requête sous une clé, l'état d'échec est conservé ; une nouvelle tentative exige une nouvelle clé.

Conditions de reprise avec sourceClipId

La reprise à partir d'une source côté API client est gérée entièrement côté serveur : l'accès à la chanson source est résolu par le serveur et le client ne transmet aucune information de compte. La faisabilité est déterminée par la réponse réelle de l'endpoint.

La source doit appartenir à l'utilisateur d'API courant, être une chanson de l'espace de travail terminée qui n'est pas pending: et disposer d'un audio utilisable. Sont prises en charge la génération ordinaire, les sources d'envoi ordinaire et la chanson finale issue d'un envoi renforcé ; les enregistrements intermédiaires d'envoi renforcé sont refusés avant facturation. Le serveur n'accepte que l'identifiant de chanson source transmis par le client, jamais un identifiant de compte ; une source indisponible ou inachevée renvoie une erreur avant facturation.

Exemple de requête

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Écris une chanson pop chinoise sur un bord de mer par nuit d'été",
    "style": "Mandopop, warm piano, emotional",
    "title": "Brise de mer par nuit d'été",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brise de mer par nuit d'été",
        "prompt": "Écris une chanson pop chinoise sur un bord de mer par nuit d'été"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Brise de mer par nuit d'été",
        "prompt": "Écris une chanson pop chinoise sur un bord de mer par nuit d'été"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

À propos des tâches de substitution et du song_id final

generate-with-voice est un endpoint de génération asynchrone. Une réponse réussie signifie seulement que la tâche de génération a été soumise, pas que la chanson est terminée.

Signification des champs clés de la réponse :

Attention : un placeholder_id commençant par pending: ne peut pas servir de song_id final, ni être transmis à /api/music/query ou aux endpoints de téléchargement. Appeler /api/music/query avec seulement des valeurs pending:* peut renvoyer un tableau vide [], car la chanson réelle n'est pas encore terminée ou la tâche de substitution n'a pas encore été remplacée par l'identifiant final.

Exemple incorrect :

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Parcours correct :

1. Appelez POST /api/music/generate-with-voice pour soumettre la tâche de génération avec voix.
2. Conservez client_request_id, items[].placeholder_id et items[].client_request_index de la réponse.
3. Interrogez GET /api/music/generate-with-voice/results?client_request_id=cu_xxx en boucle.
4. Quand items[].song_id a une valeur qui ne commence pas par pending:, appelez /api/music/query, /api/music/download-file ou /api/music/download-all.

La version actuelle ajoute un endpoint public de consultation :

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Il renvoie les résultats des tâches du même client_request_id pour l'utilisateur courant, ce qui permet au client de retrouver lui-même le song_id final. Dans la liste renvoyée :

• song_id est l'identifiant réel de la chanson ;
• placeholder_id n'apparaît que tant que la tâche est encore à l'état de substitution ;
• une valeur commençant par pending: ne peut pas être utilisée avec /api/music/query ni avec les endpoints de téléchargement.

Si vous n'avez conservé que le client_request_id ou un identifiant de substitution pending:*, appelez d'abord cet endpoint de résultats ; si le song_id réel reste introuvable, transmettez le client_request_id au support technique pour qu'il le localise.

Consulter les résultats de la génération avec voix

Point d'accès : GET /api/music/generate-with-voice/results

Facturation : gratuite.

Paramètres de requête

Exemple de requête

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse en cours

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Brise de mer par nuit d'été"
      }
    ]
  }
}

Exemple de réponse terminée

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Brise de mer par nuit d'été",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Valeurs du status de premier niveau

8. Télécharger un fichier unique

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

Paramètres du corps

Exemple de requête

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": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

La réponse est un flux de fichier ; le Content-Type et le nom du fichier suivent ce que renvoie le backend.

9. Télécharger les ressources de la chanson dans une archive

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

Paramètres du corps

Exemple de requête

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": "song_abc123"
  }' \
  --output song.zip

L'archive contient généralement l'audio, la pochette et metadata.json ; si un type de ressource n'a pas encore été généré, il n'est pas inclus dans l'archive.

Erreurs courantes

Les erreurs de ce groupe renvoient toujours HTTP 200 : jugez le résultat avec le champ success du corps (false signifie échec, avec la raison dans message) et ne vous fiez pas uniquement au code de statut HTTP. La sémantique complète de la suppression d'une voix (reste-t-elle utilisable, peut-elle être restaurée) se trouve en section 6.