API de separación (voz y acompañamiento)

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

Descripción del endpoint

La separación divide una canción existente en voz, acompañamiento o resultados multipista. El flujo de integración recomendado es:

1. Si el audio de origen no es una canción generada en esta plataforma, llama primero a la API de subida de audio de origen.
2. Llama a POST /api/music/separate para enviar la tarea de separación.
3. Sondea el resultado con la API de consulta e historial de canciones.
4. Usa los endpoints de descarga para bajar el archivo de audio de cada resultado de separación.

Endpoint: POST /api/music/separate

Facturación: De pago. stem_mode=two actualmente 0,6 ¥ por llamada por defecto; stem_mode=twelve es un split multipista y actualmente 3,0 ¥ por llamada por defecto. El importe realmente cobrado sigue la configuración de precios del back-office.

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.

Autenticación

Parámetros de la petición

Sobre stem_mode

Sobre la separación

La separación es una capacidad fija e independiente: no hay que rellenar ni elegir un modelo de generación de canciones. El cliente solo envía la canción de origen y stem_mode; el servidor se encarga según el modo.

De dónde salen los números: un envío produce 2 versiones (dos resultados del mismo material), así que el número es 2 × las pistas de ese modo: 4 para two y 24 para twelve. Guíate siempre por la longitud real del array clips de la respuesta; no escribas un bucle con un número fijo (alguna pista puede fallar y las correctas se devuelven igualmente).

Qué pistas devuelve cada modo

Las 12 pistas del modo twelve (los nombres los fija la plataforma; el orden puede variar):

El modo two devuelve dos pistas, (Vocals) e (Instrumental), cada una en 2 versiones. Los títulos de pista de two y twelve son nombres fijos (no llevan el nombre de la canción de origen), así que no esperes deducir de qué canción se trata por el título.

Los títulos de pista no sirven como clave única. En las dos versiones aparecen pistas con el mismo nombre (por ejemplo dos (Vocals), dos (Strings)), y una separación devuelve muchas pistas. Usa siempre song_id como identificador y song_title solo para mostrar; tampoco uses índices del array (el orden puede cambiar).

Ejemplos de petición

Separación voz / acompañamiento (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Split multipista (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Respuesta

En caso correcto se suele devolver un array de resultados de separación. Cada resultado es un clip de canción independiente y hay que seguir consultándolo hasta que status pase a un estado completado.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Arriba solo se muestran 2 de las 4 entradas del modo two; en la práctica se devuelven 4 (2 versiones × {(Vocals), (Instrumental)}); el modo twelve devuelve 24. El número real es la longitud del array clips.

Normalmente el cliente solo necesita guardar clips[].song_id; las consultas y descargas posteriores giran en torno a esos ID.

Notas

• Los resultados de separación no aparecen en el historial de GET /api/music/songs (esa lista solo devuelve canciones generadas normales). Tras un envío correcto, guarda clips[].song_id de inmediato; si no, después no habrá forma de encontrarlos.
• Cada pista es una obra independiente: cada pista tiene su propio song_id y hay que sondearla hasta completarla y descargarla por separado.
• La facturación no depende del número de entradas: se cobra por llamada (two 0,6 ¥ por llamada, twelve 3,0 ¥ por llamada), y 4 entradas o 24 cuestan lo mismo.
• Descarga: usa el song_id de esa pista con POST /api/music/download-url / download-file (gratis), o directamente el audio_url del resultado de la consulta; para MIDI consulta la API de obtención de MIDI.
• No envíes dos veces: la separación es un endpoint síncrono, así que tras un timeout confirma primero con la consulta de canciones en lugar de reintentar de inmediato (eso duplica el pedido y vuelve a cobrar).
• Oculta las pistas que ya no necesites con la API de eliminación de stems.

Consultar los resultados de separación

Tras un envío correcto, consulta los resultados con clips[].song_id mediante POST /api/music/query.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

Ejemplo de consulta completada:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Descargar archivos de stems

Cuando un resultado de separación está completo, puedes descargar un archivo de stem suelto con el endpoint de descarga.

Endpoint: POST /api/music/download-file

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

kind admite:

Para empaquetar los recursos relacionados de un resultado de separación, llama a:

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": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Descripción de estados

Errores frecuentes

Notas de compatibilidad

La documentación antigua usaba ejemplos de objeto único como success/task_id/vocals_url/instrumental_url. La separación actual se basa en el array de canciones clips[]: cada resultado de separación tiene su propio song_id, y las consultas y descargas posteriores giran en torno a esos song_id.

Páginas relacionadas

• Si solo quieres separar voz y acompañamiento sin elegir modo, usa la API de eliminación de voz; es la forma rápida de dos pistas de este endpoint y actualmente es gratis.
• Oculta las pistas de separación que ya no necesites con la API de eliminación de stems (borrado lógico, sin cargo).
• Para el MIDI de un stem consulta la API de obtención de MIDI; para audio, portada y otros medios, la API de descarga y previsualización de medios de canciones.