API de génération de discours (Speech)

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

Description du point d'accès

Speech transforme un texte de discours ou une description d'une phrase en audio « parole/discours », avec musique de fond en option. Il convient aux discours, aux toasts, à la narration, aux textes de voix off, aux contenus audio et à des cas similaires.

Attention : ce point d'accès produit de l'audio parlé, pas une chanson chantée (ni mélodie, ni voix chantée). Pour du chant, utilisez l'API de génération en mode simple ou l'API de génération en mode personnalisé.

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

Facturation : Payant, actuellement 0,6 ¥ par appel par défaut. Chaque appel renvoie généralement 2 audios ; le montant réellement facturé suit la configuration tarifaire du back-office.

Max Mode / Variety : ce point d'accès accepte les paramètres optionnels max_mode et variety (0-4). Avec max_mode activé, cet appel est facturé au double (0,6 → 1,2 ¥ par appel) ; variety ne coûte rien de plus. Leur signification et leur envoi sont décrits dans la section « Paramètres avancés » de la Présentation de la nouvelle API.

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 quelques secondes (1 à 10 s) ; mais, comme les autres points d'accès de génération synchrones, cela peut être plus long dans des cas extrêmes. 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.

Conformité du contenu : la plateforme vérifie le texte au regard du droit d'auteur et des règles de contenu. S'il est jugé comme comportant des éléments protégés (par exemple citer les paroles de quelqu'un d'autre ou le texte littéral d'une œuvre connue), cet appel échoue et le montant est intégralement remboursé automatiquement. Passez à votre propre formulation, ou transformez la citation en paraphrase, puis réessayez.

Paramètres de la requête

Headers

Paramètres du body

Ce point d'accès ne prend pas en charge duration : l'envoyer renvoie HTTP 400, il n'est pas ignoré en silence. La durée du discours dépend de la longueur du contenu de script.

Exemples de requête

Requête minimale (le texte seul)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Bonjour à toutes et à tous ! Aujourd'\''hui, mon propos porte sur l'\''art de bien employer notre temps et d'\''aller de l'\''avant."
  }'

Requête complète (ton, genre et musique de fond désactivée)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Exemple en Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Bonjour à tous. Je vais faire le point sur l\'avancement de cette semaine.',
        'tone': 'posé et clair, compte rendu de réunion',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # généralement 2 éléments
for item in items:
    print(item['song_id'], item['status'])

Notes sur les paramètres

script (le discours, obligatoire)

• Collez le contenu que vous voulez dire ; vous pouvez aussi écrire une seule description et laisser le modèle rédiger le discours (par exemple « une mise au point à la mi-temps pour une équipe menée de vingt points, du murmure à un rugissement à pleine voix »).
• Les retours à la ligne, les paragraphes et les indications de scène comme [pause] s'écrivent directement et le modèle les suivra autant que possible.
• La limite est de 3000 caractères (comptés en caractères Unicode ; un idéogramme chinois compte pour 1) ; au-delà, la réponse est 400 et rien n'est facturé.

tone (ton et contexte, facultatif)

Il décrit comment parler, et non quoi dire. Il est conseillé d'y mettre quatre types d'informations : ton, débit/rythme, émotion, lieu.

Énergique et puissant, en accélérant depuis un rythme lent, pauses nettes ; amphithéâtre, devant tout l'établissement
Chaleureux et doux, rythme posé ; réception de mariage
Posé et mesuré, rythme régulier et clair ; rapport au conseil

La limite est de 1000 caractères. Si vous ne le transmettez pas, le modèle le déduit du contenu de script.

gender / vocal_gender (genre de l'orateur, facultatif)

• Pour une voix masculine, transmettez m ou male ; pour une voix féminine, f ou female ; le serveur les normalise en m / f.
• Les deux noms de champ fonctionnent ; n'en utilisez qu'un : gender est la forme recommandée pour ce point d'accès ; si vous utilisez déjà le mode personnalisé, vous pouvez continuer avec vocal_gender.
• Ne rien transmettre signifie « indifférent », et c'est le modèle qui décide.

backing_music (musique de fond, facultatif)

• Par défaut true (avec musique de fond), comme sur la version web de Suno.
• false donne un discours en voix seule, pratique si vous voulez ajouter ensuite votre propre musique ou doublage.
• Doit être un booléen JSON true / false ; les chaînes "true" et "1" sont aussi acceptées, mais les booléens sont recommandés.

model (modèle, facultatif)

Les trois modèles côté client sont disponibles au même prix (0,6 ¥ par appel). Le discours est généré par la famille Suno v6 ; sans valeur, il est traité comme suno-v6. Sauf préférence explicite, ce champ n'est généralement pas nécessaire.

Validation des paramètres et limites de texte

Les cas suivants renvoient HTTP 400, et tous sont bloqués avant la facturation, donc aucun frais n'est généré :

Limites des champs texte

Un dépassement renvoie aussi HTTP 400 et ne lance pas la génération et ne pré-facture rien. Le comptage se fait en caractères Unicode (un idéogramme chinois compte pour 1) et inclut les espaces de début et de fin :

L'erreur a la forme script must not exceed 3000 characters; received 4120 : le premier mot est le champ qui dépasse et la fin est le nombre réel, donc sur un 400 vous pouvez couper directement avec ces deux nombres.

Réponse

La réponse est un tableau de morceaux exactement identique à celui des autres points d'accès de génération (généralement 2 éléments) ; conservez le song_id et utilisez l' API de consultation et d'historique des morceaux pour voir l'état final et l'adresse audio :

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Bien employer son temps",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Échec de génération et remboursements

En cas d'échec, le montant de l'appel est intégralement remboursé automatiquement ; inutile de contacter le support. Le motif figure dans la réponse ou dans le error_message de l'API de consultation et d'historique des morceaux.

La cause la plus fréquente est un contenu jugé comme comportant des éléments protégés, par exemple :

Your lyrics contain copyrighted material. Please change it and try again.

Dans ce cas, remplacez le texte par votre propre formulation (ou transformez la citation en paraphrase) puis renvoyez-le.

Questions fréquentes

Q : Pourquoi le résultat est-il de la « parole » et non du chant ? R : Ce point d'accès est celui du discours, et sa sortie est de l'audio parlé. Pour chanter, utilisez les points d'accès de génération ou du mode personnalisé.

Q : Pourquoi 2 éléments à chaque fois ? R : Comme les autres points d'accès de génération de la plateforme, une génération produit 2 candidats ; consultez-les séparément par song_id et gardez celui qui vous convient.

Q : Comment contrôler la durée ? R : Elle dépend de la longueur de script ; ce point d'accès n'accepte pas le paramètre duration.

Q : Puis-je choisir une voix (par exemple ma voix clonée) ? R : La version actuelle ne le permet pas. Le discours utilise un ensemble fixe de voix, et gender choisit masculin ou féminin ; si vous voulez votre propre voix, utilisez la capacité correspondante de l'API de création de profil vocal (recommandé).

Q : Que se passe-t-il si je ne transmets pas tone ? R : Le modèle déduit le ton et le rythme du contenu de script. Pour reproduire un style de façon stable, écrivez ton, débit et lieu dans tone.

Champs compatibles

Pour les nouvelles intégrations, utilisez snake_case partout. Les autres champs (script, tone, song_title, backing_music) n'ont pas d'alias camelCase.

Étapes suivantes

Une fois le song_id obtenu :

1. Utilisez l'API de consultation et d'historique des morceaux pour voir l'état de génération et l'adresse audio ;
2. Une fois terminé, utilisez l'API de téléchargement et d'écoute des médias de morceaux pour le télécharger ou l'écouter ;
3. Pour des téléchargements par lots ou une copie vers votre stockage, voir les points d'accès du centre de téléchargement.