API Replace Section (remplacement de passage)

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

Description du point d'accès

Replace Section régénère sur place un intervalle de temps d'un morceau existant. Cela convient pour corriger une ligne de paroles ou remplacer un passage.

Point d'accès : POST /api/music/replace-section

Facturation : Payant, actuellement 0,6 ¥ par appel par défaut. 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

startSeconds et endSeconds sont en secondes et acceptent des décimales ; startSeconds doit être inférieure à endSeconds, et l'intervalle doit rester dans la durée du morceau d'origine. requestedAt ne sert que si vous devez transmettre l'heure de la requête, sous forme d'horodatage Unix en secondes (pas en millisecondes) ; il peut normalement être omis.

Le remplacement est aussi une tâche asynchrone. Le clip renvoyé peut commencer en pending, et une adresse audio vide à ce moment-là est normale ; utilisez le vrai song_id renvoyé pour interroger le résultat final.

Longueur du passage : au moins 2 secondes (important)

L'intervalle à remplacer ne peut pas être inférieur à 2 secondes. Mesuré : les intervalles de 1,0 / 1,2 / 1,5 seconde ont tous échoué, alors que 2,0 seconde et plus ont fonctionné.

Quand l'intervalle est trop court, la plateforme ne répond pas par une « erreur de paramètre » mais par un message facile à mal interpréter :

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

Cette phrase n'est pas un problème de compte ni de forfait — le passage est trop court. Allongez l'intervalle au-delà de 2 secondes et renvoyez.

Exemple de requête

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "paroles de contexte complètes",
    "contextWindowLyrics": "paroles de contexte de la fenêtre",
    "infillLyrics": "paroles de remplacement",
    "style": "Mandopop, acoustic",
    "title": "Version remplacée",
    "negativeTags": "noise"
  }'

Réponse

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Version remplacée",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Champs compatibles

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags