Ghid rapid

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

Acest ghid te duce în circa cinci minute de la crearea cheii API la prima piesă generată, la verificarea progresului și la descărcarea audio-ului. Exemplele pot fi copiate și rulate ca atare.

Modelul implicit actual este suno-v6. Modelele de generare de la suno-v2 la suno-v5-5 au fost dezactivate: pot apărea în sarcini vechi, dar nu mai acceptă cereri noi.

Descarcă, instalează și configurează suno-api agent kit de la această adresă  https://www.suno-api.io/suno-agent-kit.zip

Recomandat: lasă AI-ul să finalizeze integrarea

AI-ul citește 00_START_HERE.md și ajută la înregistrare, salvarea API Key, verificarea soldului, prezentarea funcțiilor și prima generare. Acțiunile cu cost sunt confirmate înainte, iar timeouturile nu sunt retrimise automat.

Pasul 1: obține o cheie API

1. Deschide https://www.suno-api.io.
2. Apasă Obține cheia API și înregistrează-te. Este nevoie doar de un e-mail, fără număr de telefon.
3. În consolă deschide gestionarea tokenurilor și creează o cheie.
4. Copiaz-o imediat — cheia este afișată o singură dată. Încarcă soldul cu un cod de activare înainte de primul apel plătit.

Pasul 2: configurează cererea

Toate apelurile folosesc aceeași adresă de bază și aceleași antete:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Pasul 3: trimite prima cerere

Exemplul 1 — generare dintr-o descriere

Descrie muzica, iar API-ul scrie versurile, melodia și aranjamentul:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "o piesă folk veselă despre prima zi de primăvară",
    "model": "suno-v6"
  }'

Răspuns:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Poveste de primăvară",
    "description": "o piesă folk veselă despre prima zi de primăvară",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Pași de primăvară",
    "description": "o piesă folk veselă despre prima zi de primăvară",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Fiecare rulare returnează două versiuni diferite din care poți alege. O generare costă 0,6 ¥.

Exemplul 2 — verificarea progresului

Trimite valorile song_id primite către endpointul de interogare:

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": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Cât timp sarcina rulează:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Poveste de primăvară",
    "progress": "60%"
  }
]

Când s-a terminat:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Poveste de primăvară",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

status trece prin pending, submitted, processing și ajunge la completed. Adresele pot rămâne goale cât timp rulează sarcina: evaluează după status, nu după prezența audio_url.

Pasul 4: descarcă fișierul

Când status este completed, cere pur și simplu audio_url. Descărcările în MP3 și WAV sunt nelimitate și nu costă suplimentar. Dacă ai nevoie de audio fără pierderi pentru montaj, folosește endpointul WAV.

Scenarii frecvente

Muzică de fundal pentru video

{
  "description": "fundal lo-fi calm pentru un videoclip de produs, fără voce, dinamică stabilă",
  "instrumental": true,
  "model": "suno-v6"
}

Când instrumental este true, rezultatul nu conține voce.

Versuri și stil proprii

{
  "lyrics": "[Verse 1]\nLuminile orașului se sting încet\n\n[Chorus]\nMergem mai departe",
  "style": "acoustic pop, voce feminină caldă, 92 BPM",
  "model": "suno-v6"
}

Interogare până la finalizare

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "o piesă folk veselă despre primăvară", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Tratarea erorilor

Coduri principale

Formatul erorii

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Timpii de așteptare și timeout-urile (important): endpointurile de generare sunt sincrone — comanda este acceptată și transmisă spre generare doar când sosește răspunsul. Din măsurători, majoritatea cererilor răspund în 1-3 secunde, circa 10% depășesc 30 de secunde, iar cea mai lungă este de aproximativ 230 de secunde. Setează timeout-ul clientului la 300 de secunde sau mai mult (--max-time 300 în exemplu); lipsa unui răspuns nu înseamnă că nu s-a generat nimic, iar reîncercarea imediat după un timeout dublează comanda și debitează din nou. Dacă conexiunea s-a întrerupt, verifică mai târziu cu GET /api/music/songs. Vezi „Timpii de așteptare și setarea timeout-ului” în Prezentarea noului API.

Bune practici

• Ține cheia pe server, niciodată în browser sau în aplicații distribuite.
• Interogează la 10–15 secunde, nu într-o buclă strânsă.
• Păstrează song_id: este singurul identificator pentru a regăsi audio-ul mai târziu.
• Reîncearcă la 429 și 500; remediază cauza înainte de a reîncerca la 400 și 401.
• Generările eșuate sunt rambursate automat, deci o sarcină nereușită nu costă nimic.
• Timeout-ul clientului: un endpoint de generare este considerat acceptat doar când răspunde; setează timeout-ul la 300 de secunde sau mai mult.
• Reîncercări: reîncearcă doar la erori explicite (4xx/5xx). După un timeout sau o întrerupere de conexiune, verifică mai întâi cu GET /api/music/songs dacă comanda a fost acceptată, ca să eviți dublarea comenzii și plata de două ori.

Pașii următori

• Autentificare — chei, erori și limite
• Modele acceptate — nume de modele, stemuri și modele dezactivate