Suno Separar pistas de audio
Usa el endpoint de separación de pistas de audio para crear una tarea asíncrona.
Descripción general
Usa el endpoint de separación de pistas de audio con las entradas requeridas. Usa el ID de tarea devuelto para recuperar su estado, o proporciona callback_url para las entregas documentadas a continuación.
Inicio rápido
- Cree una Clave de API y establézcala como RUNAPI_API_KEY.
- Envíe una solicitud POST cuyo cuerpo coincida con el esquema de la solicitud.
- Almacena el ID de tarea devuelto, luego sondea hasta alcanzar un estado terminal o gestiona las devoluciones de llamada documentadas a continuación.
Endpoint
- URL base
https://runapi.ai- Versión de la API
v1- Autenticación
Authorization: Bearer YOUR_API_TOKEN
Modelos compatibles
Abra una página de modelo para conocer los precios actuales, los límites de velocidad y los detalles de uso comercial.
Esquema de solicitud
Envíe únicamente los campos documentados. Cuando se proporcione, callback_url recibirá las entregas de la Task indicadas a continuación.
Cuerpo de la solicitud5 campos
audio_idstringID de audio dentro de la tarea de origen.
callback_urlstringURL de webhook para notificaciones asíncronas.
stem_namestringStem objetivo para la separación avanzada. Obligatorio cuando type es split_stem_advanced.
Valores permitidos:Lead Vocal, Drum Kit, Kick, Snare, Risers, Bass, Backing Vocals, Piano, Electric Guitar, Percussion, String Section, Synth, Acoustic Guitar, Sound Effects, Synth Pad, Synth Bass, Guitar, Brass Section, Organ, Electronic Drum Kit, Lead Electric Guitar, Synth Keys, Rhythm Electric Guitar, Electric Piano, Upright Bass, Keyboards, Distorted Electric Guitar, Synth Strings, Synth Lead, Woodwinds, Rhythm Acoustic Guitar, Flute, Harp, Tambourine, Trumpet, Arpeggiator, Accordion, Fiddle, Pedal Steel Guitar, Synth Voice, Violin, Digital Piano, Synth Brass, Mandolin, Choir, Banjo, Bells, Clarinet, Tenor Saxophone, Trombone, Shaker, French Horn, Glockenspiel, Electric Bass, Cello, Timpani, Harmonica, Marimba, Vibraphone, Lap Steel Guitar, Saxophone, Orchestra, Horns, Cymbals, Hand Clap, Oboe, Celesta, Congas, Drone, Alto Saxophone, Double Bass, Ukulele, Harpsichord, Baritone Saxophone, Xylophone, Tuba, Bass Guitar, Whistle, Lead Guitar, Rhodes, 808, Bongos, Bassoon, Cowbell, Viola, Sitar, Steel Drums, Piccolo, Theremin, Bagpipes, Hi-Hat, Music Box, Melodica, Tabla, Koto, Djembe, Taiko, Didgeridoo
task_idstringID de Task fuente.
typestringModo de separación de pistas.
Valores permitidos:separate_vocal, split_stem, split_stem_advanced
Valor predeterminado: separate_vocal
Reglas condicionales
Estos requisitos se aplican cuando todas las condiciones enumeradas coinciden.
-
Cuando
type = split_stem_advanced- Obligatorio
stem_name- No aceptado
Crear aceptación
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta en proceso
GET /api/v1/suno/separate_audio_stems/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta completada
GET /api/v1/suno/separate_audio_stems/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"separated_audios",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"separated_audios": {
"instrumental_url": "https://file.runapi.ai/reference-instrumental.mp3",
"vocal_url": "https://file.runapi.ai/reference-vocals.mp3"
},
"status": "completed"
}
Consulta fallida
GET /api/v1/suno/separate_audio_stems/:id
Esquema de respuesta
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
Devolución de llamada del cliente: completado
POST callback_url
Esquema de respuesta
{
"properties": {
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"separated_audios"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"id": "tsk_reference_demo",
"separated_audios": {
"instrumental_url": "https://file.runapi.ai/reference-instrumental.mp3",
"vocal_url": "https://file.runapi.ai/reference-vocals.mp3"
},
"status": "completed"
}
Devolución de llamada del cliente: fallido
POST callback_url
Esquema de respuesta
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Authentication required"
}
Errores
GET /api/v1/suno/separate_audio_stems/:id
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Authentication required"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumen de validación legible por personas.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
Ejemplo de respuesta
{
"error": "Validation failed",
"errors": {
"task_id": [
"is required"
]
}
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Insufficient balance"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "API key credit limit exceeded"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "The request uses features that are not supported for the selected model"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Rate limit reached. Please retry later."
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Service under maintenance, please try again later"
}
Errores
POST /api/v1/suno/separate_audio_stems
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "The request timed out"
}
Errores
GET /api/v1/suno/separate_audio_stems/:id
Esquema de respuesta
{
"properties": {
"error": {
"description": "Mensaje de error legible por personas.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Ejemplo de respuesta
{
"error": "Task with id 'tsk_reference_demo' not found"
}
Ejemplos de código generados
Usa cURL directamente o instala un SDK para tu lenguaje. Cada muestra envía la solicitud validada que se muestra en esta referencia.
Instalar
pip install runapi-suno
import os
from runapi.suno import SunoClient
client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.separate_audio_stems.create(
task_id="tsk_source_music",
audio_id="audio_reference",
type="separate_vocal"
)