Prezentare generală a documentației Suno API

Actualizat pe 2026-09-18 · echipa Suno-API

Este suficient să te înregistrezi cu un e-mail pentru a crea o cheie API. O generare costă 0,6 ¥ și returnează 2 piese, cu descărcare MP3/WAV, cover-uri, Extend, separarea stemurilor și clonare vocală. URL de bază: https://www.suno-api.io.

Această pagină descrie modelele disponibile, toate endpointurile de generare și editare, facturarea și ordinea recomandată de citire. Dacă este prima integrare, citește de sus în jos; punctele de diagnostic pentru 401/403/429 sunt tot aici.

Răspunsuri rapide

Cum obțin o cheie API? Înregistrează-te cu un e-mail, deschide consola, mergi la gestionarea tokenurilor și creează un token. Nu e nevoie de număr de telefon sau card.

Cât costă un apel? O generare costă 0,6 ¥ și returnează 2 piese. Interogările de status, WAV, versurile cu marcaje de timp și sugestiile de prompt nu costă suplimentar.

Ce modele sunt acceptate? suno-v6 (implicit), suno-v6-wild și suno-v6-mini. Modelele standard de generare v5.5 și mai vechi au fost retrase; lucrările existente nu sunt afectate.

Care este URL-ul de bază? https://www.suno-api.io, cu antetul Authorization: Bearer YOUR_API_KEY.

Modele disponibile în prezent

La generarea standard a pieselor clientul poate indica doar suno-v6, suno-v6-wild și suno-v6-mini. Dacă model lipsește, se folosește suno-v6.

Modelele standard suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 și suno-v5-5 au fost retrase. În sarcinile istorice aceste nume pot apărea încă, dar sunt date istorice și nu înseamnă că modelul poate fi folosit pentru cereri noi. Excepția o reprezintă separarea pe stemuri — vezi API pentru stemuri (separarea vocii și a acompaniamentului).

Autentificare

Toate endpointurile publice cu cheie API folosesc aceleași antete:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL de bază:

https://www.suno-api.io

Reguli generale pentru parametri

• Un number din corpul cererii trebuie să fie un număr JSON, niciodată un procent scris ca text. O intensitate de 50% se scrie 0.5, niciodată 50 sau 50%.
• Un boolean trebuie să fie true sau false. Nu trimite true, false, 0 sau 1 ca înlocuitor.
• Câmpurile marcate „nu" pot fi omise complet. Dacă nu ești sigur ce face un parametru, omite-l și lasă serviciul să aplice comportamentul implicit; nu trimite text gol, null sau 0 în loc de „netrimis", fiindcă 0 este o valoare validă pentru unele câmpuri numerice.
• Numele câmpurilor țin cont de ortografie. Fiecare pagină indică câmpul recomandat și aliasurile compatibile; trimite-le exact ca în tabel. Acolo unde documentația spune că snake_case și camelCase sunt acceptate, nu le trimite pe amândouă.
• Toate câmpurile de durată care se termină cu _s sau Seconds sunt în secunde și acceptă zecimale. Marcajele de timp Unix sunt descrise separat, cu mențiunea secunde sau milisecunde.
• Un ID care începe cu pending: este un substituent al platformei, nu un ID real de piesă. Folosește-l doar acolo unde endpointul documentează explicit acest lucru; altfel așteaptă song_id-ul real.

Limitele câmpurilor de text

Depășirea limitei returnează direct HTTP 400: nu se generează nimic, nu se pre-debitează nimic și nu se creează nicio înregistrare de sarcină. Numărătoarea se face în caractere Unicode (un ideogramă contează ca 1), iar spațiile de la început și sfârșit contează și ele.

Mesajul de eroare (message) indică câmpul și lungimea măsurată; aceste două numere sunt suficiente pentru a scurta textul:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Se aplică pentru: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

O excepție: câmpul description de la POST /api/music/sounds este limitat la 100 de caractere, fiindcă traseul efectelor sonore folosește limita mai scurtă a platformei.

Generare asincronă și adrese audio

Endpointurile de generare muzicală funcționează implicit asincron. Când primul răspuns are status egal cu pending, submitted sau processing, un audio_url, video_url sau cover_url gol este normal și nu înseamnă că sarcina a eșuat. Salvează song_id-ul real (sau client_request_id-ul returnat) și interoghează endpointul corespunzător; citește și descarcă o adresă audio doar după ce statusul este finalizat.

⚠️ Adresele audio expiră după 7 zile — mută fișierele la timp

audio_url, wav_url, video_url și adresele returnate de endpointurile de descărcare sunt servite din stocarea obiect a platformei și expiră implicit după 7 zile (fișierele sunt reciclate; o adresă veche returnează 404 / nu se descarcă).

• În aceste 7 zile, mută fișierele în propria stocare (stocarea ta obiect, un CDN sau un disc de server). Nu trata adresele noastre ca linkuri de durată lungă.
• O adresă expirată nu necesită regenerarea piesei și nu costă nimic în plus: apelează din nou API-ul de interogare a pieselor (sau API-ul de descărcare media) pentru o adresă nouă și validă.

Timpi de așteptare și setarea timeout-ului

Endpointurile de generare sunt sincrone: comanda este acceptată și transmisă platformei doar când sosește răspunsul. Înainte de asta, serviciul trebuie să aloce un cont și să treacă verificarea de securitate necesară, iar un răspuns intermediar nu există — niciun alt endpoint nu vede comanda. Prin urmare, singura dovadă fiabilă că „s-a generat ceva" este răspunsul în sine, nu ceea ce observi în timpul așteptării.

Timpi măsurați (producție, familia /api/music/create, 18–20 septembrie 2026)

• Circa 10% dintre cereri depășesc 30 de secunde, iar circa 1% durează 1–2 minute. O cerere lentă înseamnă de obicei că de data aceasta a fost nevoie mai întâi de o verificare de securitate.
• Câmpurile, forma răspunsului, codurile de eroare și facturarea sunt neschimbate, deci integrările existente trebuie doar să mărească timeout-ul clientului — nicio altă modificare de cod.

Cerințe de integrare

1. Setează timeout-ul clientului la 300 de secunde sau mai mult. Clienții cu 30, 60 sau 120 de secunde întrerup conexiunea în timpul așteptării.
2. Lipsa răspunsului nu înseamnă că nu s-a generat nimic. La timeout sau conexiune întreruptă, comanda poate fi deja acceptată și în generare.
3. Nu reîncerca imediat după un timeout: o trimitere duplicată creează o a doua comandă și facturează din nou.
4. Dacă conexiunea s-a întrerupt, listează piesele cu GET /api/music/songs (cele mai noi primele) puțin mai târziu — comenzile acceptate apar normal. Retrimite doar după ce confirmi că comanda lipsește cu adevărat.
5. Când raportezi o problemă, include antetul de răspuns X-Oneapi-Request-Id, ca cererea exactă să poată fi găsită.

Nu vrei să ții o conexiune lungă? Folosește modul cu confirmare de primire. POST /api/music/create și POST /api/music/create/custom acceptă o confirmare opțională: adaugă "accept_mode": "async" în corp (sau antetul X-Accept-Mode: async) și endpointul răspunde imediat 202 cu un număr de confirmare, în timp ce generarea continuă în fundal; urmărește progresul cu GET /api/music/requests/{request_id}. Un client cu doar câteva zeci de secunde de timeout nu mai poate confunda „fără răspuns" cu „nimic generat" și nu mai poate plăti de două ori din cauza reîncercărilor. Vezi „Modul cu confirmare de primire" în API-ul de generare în modul simplu.

Pentru referință: python requests folosește timeout=300, urllib folosește urlopen(..., timeout=300), Node folosește req.setTimeout(300000), curl folosește --max-time 300.

Lista de endpointuri recomandate

Endpointurile /api/voice/clone/* și /api/music/generate-with-voice aparțin lanțului timpuriu de clonare vocală și nu sunt recomandate pentru integrări noi; folosește în schimb 【Recomandat】 API-ul de profil vocal.

Parametri avansați: Max Mode și Variety

Endpointurile de generare acceptă acești doi parametri opționali (dacă lipsesc, comportamentul și prețul rămân neschimbate):

Acceptat de: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Dublul preț în practică: un endpoint de 0,6 ¥ per apel devine 1,2 ¥ cu max_mode; generarea cu vocea aleasă costă 1,2 ¥ per apel și 2,4 ¥ cu Max Mode; cover-ul vocal din 【Recomandat】 API-ul de profil vocal costă tot 1,2 ¥ per apel (2,4 ¥ cu max_mode).
• variety se aplică doar familiei suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); trimis cu alte modele returnează 400.
• Efectele sonore, stemurile, concat, WAV și acțiunile de editare Studio (decupare, ștergere segment, fade, redare inversă, viteză etc.) nu au acești parametri — trimiși explicit returnează 400, ca un parametru să nu fie vreodată ignorat în tăcere.
• variety este întregul 0-4; style_weight și weirdness_constraint sunt zecimale 0-1, deci scalele diferă.

Câmpuri comune de răspuns pentru piese

Endpointurile de generare, cover, extend, separare și interogare returnează de obicei un tablou de piese cu aceste câmpuri:

Patru pași pentru integrare (exemplu minim)

Cu acești patru pași obții prima piesă; lista completă de câmpuri pentru fiecare pas este pe pagina corespunzătoare din lista de endpointuri recomandate.

# 1) Trimite o generare: 0,6 ¥, returnează 2 piese
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Romanian pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Interoghează până când status este completed (3-5 secunde e un interval bun)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id-ul returnat la pasul 1"}'

# 3) Obține o adresă media: endpointurile de citire sunt gratuite; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "același song_id", "kind": "song"}'

Dacă apare o problemă: 401 / 402 / 403 / 429 în lista de erori; timeout-uri și debitări duble în secțiunea de mai sus; detaliile fiecărui endpoint în lista de mai jos.

Recomandări

• Integrările noi ar trebui să folosească suno-v6 peste tot.
• La endpointurile cu preț implicit, suma efectivă urmează configurația de prețuri din back office și modelul cerut.
• Endpointurile de generare returnează mai întâi o sarcină; obține audio-ul final prin /api/music/query.
• wait_completion=true blochează până la final și este potrivit pentru teste cu volum mic; în producție e mai bine să interoghezi asincron.
• Generarea poate dura mult — setează timeout-ul clientului la 300 de secunde sau mai mult și reține că „fără răspuns" nu este același lucru cu „nimic generat".
• Încărcarea, cover-ul, înlocuirea și WAV depind de conturile platformei și de drepturile asupra clipului sursă; la eroare citește mai întâi message sau error_message.

Despre această documentație

Această pagină a fost reorganizată în jurul capacităților pe care Create UI le expune efectiv; integrările noi ar trebui să înceapă aici. Documentația API veche rămâne disponibilă în secțiunea „Documentația API veche (compatibil)" pentru cei care vor să păstreze metoda anterioară.