API de génération en mode personnalisé

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

Description du point d'accès

Le mode personnalisé convient lorsque vos paroles, votre style et votre titre sont déjà prêts et que vous voulez contrôler la voix qui chante, la force de l'influence du style et le degré d'aléatoire de la génération.

Point d'accès : POST /api/music/create/custom

Facturation : Payant, actuellement 0,6 ¥ par appel par défaut. Chaque appel renvoie généralement 2 morceaux ; le montant réellement facturé suit la configuration tarifaire actuelle 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 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.

Paramètres de la requête

Headers

Paramètres du body

Notes sur les paramètres avancés

Genre de la voix vocal_gender

• Envoyez m ou male pour une voix masculine, f ou female pour une voix féminine.
• Le service normalise male et female en m et f respectivement.
• Avec instrumental=true, aucun paramètre de genre de voix n'est envoyé au service de génération.

Influence du style style_weight

Contrôle la force avec laquelle le résultat suit style_tags. Plus la valeur est élevée, plus le résultat tend à suivre les étiquettes que vous avez fournies.

Aléatoire weirdness_constraint

Contrôle à quel point le résultat varie et reste expérimental. Des valeurs élevées donnent généralement plus de variation ; des valeurs basses donnent généralement un résultat plus sûr.

Les deux paramètres numériques vont de 0.0 à 1.0, et 0 est une valeur explicite valide. Seule l'omission complète du champ signifie « non spécifié ».

En les renseignant, notez qu'il s'agit de fractions décimales, et non d'entiers de pourcentage. Repère suggéré : de 0.0 à 0.3 est prudent, de 0.4 à 0.6 est équilibré, de 0.7 à 1.0 est plus expérimental ; sans préférence marquée, utilisez 0.5 ou omettez-les simplement. Exemple : weirdness_constraint: 0.5, jamais 50 ni 50%.

Avec instrumental=true, le résultat est instrumental : les paroles et le genre de la voix n'agissent pas comme sur un morceau chanté ; si vous voulez du chant, envoyez false ou omettez le champ. Les champs booléens doivent utiliser true/false en JSON, jamais des chaînes.

Exemple de requête en Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nLa nuit tombe sur la mer\nune brise passe près de la fenêtre',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Brise du soir au bord de la mer',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Mode reçu d'acceptation (facultatif)

Ce point d'accès accepte aussi le mode reçu d'acceptation de l'API de génération en mode simple : avec "accept_mode": "async" dans le corps (ou l'en-tête X-Accept-Mode: async), le point d'accès renvoie immédiatement 202 et un numéro de reçu, la génération continue en arrière-plan, et vous suivez la progression avec GET /api/music/requests/{request_id}.

Utile pour les clients qui ne doivent pas garder de connexions longues, ou qui ne veulent pas qu'un timeout soit interprété comme « rien n'a été généré ». Sans ce paramètre, le comportement est exactement celui d'avant.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Brise du soir au bord de la mer",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

La forme de la réponse et la méthode d'interrogation sont dans la section « Mode reçu d'acceptation » de l'API de génération en mode simple.

Validation des paramètres

Ces cas renvoient HTTP 400, et le message de l'erreur nomme le champ invalide :

• style_weight ou weirdness_constraint n'est pas un nombre.
• Une valeur numérique est inférieure à 0.0 ou supérieure à 1.0.
• vocal_gender n'est pas l'un de m, f, male, female.

Limites des champs texte

Ces champs renvoient aussi HTTP 400 lorsqu'ils sont trop longs, et n'entrent jamais en génération ni ne sont prélevés. Le comptage se fait en caractères Unicode (un caractère han compte pour 1) et inclut les espaces de début et de fin :

Le message d'erreur a la forme style_tags must not exceed 1000 characters; received 2772 : le premier mot est le champ fautif et la fin est le nombre mesuré, donc sur un 400 vous coupez avec ces deux nombres au lieu d'essayer champ après champ. Les conventions générales sont dans « Limites des champs texte » de la Présentation de la nouvelle API.

Réponse

Le point d'accès renvoie généralement un tableau contenant 2 morceaux. Une requête asynchrone démarre normalement en pending ; conservez le song_id et lisez l'état final et l'adresse audio via l'API de consultation des morceaux. Les champs de morceau sont les mêmes que dans l'API de génération en mode simple.

Champs compatibles

Les nouvelles intégrations doivent utiliser snake_case partout. Si une même requête porte à la fois snake_case et camelCase, la valeur en snake_case l'emporte.