API de Replace Section (reemplazo de sección)

Actualizado el 2026-09-18 · equipo de Suno-API

Descripción del endpoint

Replace Section regenera en el sitio un tramo de tiempo de una canción existente. Sirve para corregir una línea de la letra o cambiar un pasaje.

Endpoint: POST /api/music/replace-section

Facturación: De pago, actualmente 0,6 ¥ por llamada por defecto. El importe realmente cobrado sigue la configuración de precios actual del back-office.

Max Mode / Variety: este endpoint admite los parámetros opcionales max_mode y variety (0-4). Con max_mode activado, esta llamada se factura al doble (0,6 → 1,2 ¥ por llamada); variety no cuesta nada extra. Qué significan y cómo enviarlos está en la sección «Parámetros avanzados» del Resumen de la nueva API.

Tiempos de espera y timeouts (importante): es un endpoint síncrono — el pedido solo se acepta y se entrega a generación cuando llega la respuesta. Según lo medido, la mayoría de las peticiones responden en 1-3 segundos, alrededor del 10% tardan más de 30 segundos y la más lenta ronda los 230 segundos. Configura el timeout del cliente en 300 segundos o más; no recibir respuesta no significa que no se haya generado nada, y no reintentes justo después de un timeout (eso duplica el pedido y vuelve a cobrar). Si la conexión se cayó, confírmalo más tarde con GET /api/music/songs. Consulta «Tiempos de espera y configuración de timeout» en el Resumen de la nueva API.

Parámetros de la petición

Headers

Parámetros del body

startSeconds y endSeconds están en segundos y admiten decimales; startSeconds debe ser menor que endSeconds y el rango debe quedar dentro de la duración de la canción original. requestedAt solo se usa cuando necesitas enviar la hora de la petición, como timestamp Unix en segundos (no milisegundos); normalmente puede omitirse.

El reemplazo también es una tarea asíncrona. El clip devuelto puede empezar en pending, y que la dirección de audio esté vacía en ese momento es normal; usa el song_id real que llega en la respuesta para consultar el resultado final.

Longitud de la sección: al menos 2 segundos (importante)

El rango a reemplazar no puede ser más corto que 2 segundos. Medido: rangos de 1,0 / 1,2 / 1,5 segundos fallaron todos, mientras que 2,0 segundos o más funcionaron.

Cuando el rango es demasiado corto, la plataforma no responde con un «error de parámetro» sino con un mensaje fácil de malinterpretar:

{"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"}}

Esa frase no es un problema de cuenta ni de plan — la sección es demasiado corta. Alarga el rango por encima de 2 segundos y vuelve a enviarlo.

Ejemplo de petición

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": "letra completa de contexto",
    "contextWindowLyrics": "letra de contexto de la ventana",
    "infillLyrics": "letra del reemplazo",
    "style": "Mandopop, acoustic",
    "title": "Versión reemplazada",
    "negativeTags": "noise"
  }'

Respuesta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Versión reemplazada",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Campos 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