Suno Separa tracce audio
Usa l'endpoint di separazione delle tracce audio per creare un Task asincrono.
Panoramica
Usa l'endpoint di separazione delle tracce audio con gli input richiesti. Utilizza il Task ID restituito per recuperarne lo stato, oppure fornisci callback_url per le consegne documentate di seguito.
Avvio rapido
- Crea una Chiave API e impostala come RUNAPI_API_KEY.
- Invia una richiesta POST il cui corpo corrisponde allo schema della richiesta.
- Conserva l'ID attività restituito, quindi esegui il polling fino a uno stato terminale o gestisci i callback documentati di seguito.
Endpoint
- URL di base
https://runapi.ai- Versione API
v1- Autenticazione
Authorization: Bearer YOUR_API_TOKEN
Modelli supportati
Apri la pagina di un modello per i prezzi correnti, i limiti di frequenza e i dettagli sull'uso commerciale.
Schema della richiesta
Invia solo i campi documentati. Se fornito, callback_url riceve le consegne Task documentate di seguito.
Corpo della richiesta5 campi
audio_idstringID audio all'interno del task sorgente.
callback_urlstringURL webhook per notifiche asincrone.
stem_namestringStem di destinazione per la separazione avanzata. Obbligatorio quando type è split_stem_advanced.
Valori consentiti: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 task sorgente.
typestringModalità di separazione degli stem.
Valori consentiti:separate_vocal, split_stem, split_stem_advanced
Predefinito: separate_vocal
Regole condizionali
Questi requisiti si applicano quando tutte le condizioni elencate corrispondono.
-
Quando
type = split_stem_advanced- Obbligatorio
stem_name- Non accettato
Crea accettazione
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"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
}
Esempio di risposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Polling in elaborazione
GET /api/v1/suno/separate_audio_stems/:id
Schema della risposta
{
"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
}
Esempio di risposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
Polling completato
GET /api/v1/suno/separate_audio_stems/:id
Schema della risposta
{
"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
}
Esempio di risposta
{
"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"
}
Polling non riuscito
GET /api/v1/suno/separate_audio_stems/:id
Schema della risposta
{
"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
}
Esempio di risposta
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
Callback cliente: completato
POST callback_url
Schema della risposta
{
"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
}
Esempio di risposta
{
"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 cliente: fallito
POST callback_url
Schema della risposta
{
"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
}
Esempio di risposta
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Authentication required"
}
Errori
GET /api/v1/suno/separate_audio_stems/:id
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Authentication required"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"oneOf": [
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Riepilogo di convalida leggibile dall'utente.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Messaggi di convalida con chiave per campo della richiesta pubblica, con un array di stringhe leggibili dall'utente per ogni campo.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
Esempio di risposta
{
"error": "Validation failed",
"errors": {
"task_id": [
"is required"
]
}
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Insufficient balance"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "API key credit limit exceeded"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "The request uses features that are not supported for the selected model"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Rate limit reached. Please retry later."
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Service under maintenance, please try again later"
}
Errori
POST /api/v1/suno/separate_audio_stems
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "The request timed out"
}
Errori
GET /api/v1/suno/separate_audio_stems/:id
Schema della risposta
{
"properties": {
"error": {
"description": "Messaggio di errore leggibile.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
Esempio di risposta
{
"error": "Task with id 'tsk_reference_demo' not found"
}
Esempi di Codice Generati
Usa cURL direttamente, oppure installa un SDK per il tuo linguaggio. Ogni esempio invia la richiesta validata mostrata in questo riferimento.
Installa
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"
)