Suno Separar stems de áudio
Use o endpoint de separação de trilhas de áudio para criar uma Task assíncrona.
Visão geral
Use o endpoint de separação de trilhas de áudio com as entradas necessárias. Use o Task ID retornado para recuperar seu estado, ou forneça callback_url para as entregas documentadas abaixo.
Início rápido
- Crie uma Chave de API e defina-a como RUNAPI_API_KEY.
- Envie uma requisição POST cujo corpo corresponda ao schema da requisição.
- Armazene o ID da tarefa retornado e, em seguida, faça polling até atingir um estado terminal ou trate os callbacks documentados abaixo.
Endpoint
- URL base
https://runapi.ai- Versão da API
v1- Autenticação
Authorization: Bearer YOUR_API_TOKEN
Modelos suportados
Abra uma página de modelo para ver preços atuais, limites de taxa e detalhes de uso comercial.
Esquema de solicitação
Envie apenas os campos documentados. Quando fornecido, callback_url recebe as entregas de Task documentadas abaixo.
Corpo da solicitação5 campos
audio_idstringID do áudio dentro da tarefa de origem.
callback_urlstringURL de webhook para notificações assíncronas.
stem_namestringStem alvo para separação avançada. Obrigatório quando o tipo é 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 de origem.
typestringModo de separação de stems.
Valores permitidos:separate_vocal, split_stem, split_stem_advanced
Padrão: separate_vocal
Regras condicionais
Esses requisitos se aplicam quando todas as condições listadas corresponderem.
-
Quando
type = split_stem_advanced- Obrigatório
stem_name- Não aceito
Criar aceitação
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta em processamento
GET /api/v1/suno/separate_audio_stems/:id
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Consulta concluída
GET /api/v1/suno/separate_audio_stems/:id
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"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 falhou
GET /api/v1/suno/separate_audio_stems/:id
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
Callback do cliente: concluído
POST callback_url
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"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"
}
Callback do cliente: falhou
POST callback_url
Esquema de resposta
{
"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
}
Exemplo de resposta
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Authentication required"
}
Erros
GET /api/v1/suno/separate_audio_stems/:id
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Authentication required"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"oneOf": [
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Resumo de validação legível por humanos.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Mensagens de validação com chaves por campo de requisição público, com um array de strings legíveis por humanos para cada campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
Exemplo de resposta
{
"error": "Validation failed",
"errors": {
"task_id": [
"is required"
]
}
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Insufficient balance"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "API key credit limit exceeded"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "The request uses features that are not supported for the selected model"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Rate limit reached. Please retry later."
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Service under maintenance, please try again later"
}
Erros
POST /api/v1/suno/separate_audio_stems
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "The request timed out"
}
Erros
GET /api/v1/suno/separate_audio_stems/:id
Esquema de resposta
{
"properties": {
"error": {
"description": "Mensagem de erro legível por humanos.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Exemplo de resposta
{
"error": "Task with id 'tsk_reference_demo' not found"
}
Exemplos de Código Gerados
Use cURL diretamente ou instale um SDK para a sua linguagem. Cada exemplo submete a requisição validada mostrada nesta referência.
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"
)