API de interogare a pieselor și de istoric

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

Această pagină acoperă trei endpoint-uri gratuite de interogare:

Dacă ai folosit modul chitanță de acceptare (accept_mode=async) pe un endpoint de generare, ce ai în mână este un număr de chitanță, nu un ID de piesă. Urmărește progresul cu GET /api/music/requests/{request_id} și revino la endpoint-urile din această pagină când ai song_id-ul real. Vezi „Modul chitanță de acceptare” în API-ul de generare în mod simplu.

Autentificare și sfera datelor

Toate cele trei endpoint-uri se autentifică cu aceeași cheie API:

Authorization: Bearer YOUR_API_KEY

Istoricul pieselor este izolat pe user_id-ul căruia îi aparține cheia API. Mai multe chei create sub același cont principal pot citi istoricul acelui cont, dar nu piese ale altui utilizator sau ale unui cont de subsite.

Endpoint-urile de istoric returnează doar piese realmente generate. Sunt excluse:

• înregistrările substituent de generare care încep cu pending:;
• încărcările de audio sursă și înregistrările de încărcare îmbunătățită;
• subrezultate precum separarea vocii/acompaniamentului și stem-urile;
• piesele altor utilizatori sau ale conturilor de subsite.

1. Interogarea stării de generare

Interoghează starea curentă și rezultatul final pentru unul sau mai multe ID-uri de piesă.

Endpoint: POST /api/music/query

Facturare: Gratuit.

Headers

Parametri din body

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Exemplu de răspuns

[
  {
    "song_id": "clip_id_1",
    "song_title": "Titlul piesei",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Textul versurilor",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Note de compatibilitate

Documentația veche poate arăta song_ids ca un array. Astăzi se recomandă un șir separat prin virgule, exact cum este apelat endpoint-ul în realitate.

song_ids trebuie să conțină ID-uri reale de piesă. Un ID substituent care începe cu pending: nu este un song_id final și nu poate fi folosit aici; interogarea doar a ID-urilor substituent poate returna un array gol [].

model, model_version sau model_name-ul de platformă dintr-un răspuns pot păstra valori istorice. Sarcinile noi ar trebui să folosească suno-v6, suno-v6-wild sau suno-v6-mini; de la suno-v2 la suno-v5-5 sunt retrase, iar apariția acestor nume în istoric nu înseamnă că modelul mai poate fi trimis.

Cât timp o sarcină este pending, submitted sau processing, audio_url, video_url și cover_url pot fi goale — este normal pentru o sarcină nefinalizată. Nu trage concluzia unui eșec doar din adresa goală; folosește status și interoghează din nou când starea este completă. Doar când starea este completă și adresele rămân goale merită să contactezi suportul indicând song_id.

⚠️ Adresele audio trăiesc 7 zile — transferă fișierele la timp

audio_url, video_url (și alte adrese media, cum ar fi WAV) returnate aici sunt servite din stocarea obiect a platformei și expiră implicit după 7 zile: fișierele sunt reciclate, iar adresa veche returnează 404.

• Mută fișierele în stocarea ta în aceste 7 zile; nu trata adresa ca pe un link de durată lungă.
• O adresă expirată nu necesită regenerarea piesei și nu se facturează din nou: apelează din nou acest endpoint (POST /api/music/query) pentru a obține o adresă nouă și validă a piesei.

2. Interogarea istoricului de piese al contului

Listează piesele create de contul principal căruia îi aparține cheia API curentă. Util pentru o listă proprie de piese, un selector sau o pagină de istoric.

Endpoint: GET /api/music/songs

Facturare: Gratuit.

Parametri de query

Rezultatele sunt ordonate descrescător după created_at și ID-ul intern al înregistrării, astfel încât ordinea paginilor rămâne stabilă.

Cum recuperezi o trimitere care a expirat: endpoint-urile de generare nu dau niciun răspuns intermediar înainte de acceptare. Dacă clientul a expirat sau conexiunea s-a întrerupt la trimitere, comanda poate fi deja acceptată și în generare. Aruncă o privire pe acest endpoint (cele mai noi primele): piesele acceptate apar normal în listă. Retrimite doar după ce ai confirmat că într-adevăr nu există, ca să nu plătești de două ori. Vezi „Timpii de așteptare și setarea timeout-ului” în Prezentarea noului API.

Exemplu de cerere

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Orașul în noapte",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Câmpurile răspunsului

Endpoint-ul de listare nu returnează prompturi, câmpuri de facturare, informații de cont sau răspunsuri brute. Pentru prompturi și parametri de generare, apelează endpoint-ul de detaliu al piesei.

3. Interogarea parametrilor de generare

Interoghează promptul, stilul, modelul și piesa sursă pe care platforma le-a păstrat la generarea piesei.

Endpoint: GET /api/music/songs/:song_id

Facturare: Gratuit.

Pot fi citite doar piesele contului principal căruia îi aparține cheia API curentă. Piesele altor utilizatori sau ale conturilor de subsite sunt tratate uniform ca „piesă negăsită”.

Parametru de cale

Exemplu de cerere

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Orașul în noapte",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "străzi de oraș după ploaie, versuri despre o reîntâlnire",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Orașul în noapte",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Câmpurile parameters

Câmpul prompt_view (vizualizare prompt, adăugat la 2026-09-28)

prompt_view este o structură normalizată dedicată „vizualizării promptului”: organizează datele în secțiuni fixe după tipul generării, astfel încât clientul nu mai trebuie să decidă ce câmp să afișeze. Este un câmp pur aditiv — câmpurile vechi (parameters, parameter_retention) își păstrează numele și sensul, iar clienții care nu analizează noul câmp nu sunt deloc afectați.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Mod personalizat",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Patru dimineața#701f37", "title_base": "Patru dimineața", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "electronică guochao, sub bass profund, sintetizator retro",
    "style_tags": "electronică guochao, sub bass profund, sintetizator retro",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Câmpuri care pot apărea în extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, plus grupul de efecte sonore sound_type / sound_bpm / sound_key / sound_loop. Valorile goale nu sunt returnate niciodată.

Trei reguli de afișare (urmează-le în loc să deduci):

1. Distinge de unde vine stilul: la style_source=suno_derived afișează „stil (dedus de Suno din descrierea ta)” și niciodată „stilul tău”;
2. Prompturile interne nu apar niciodată: tipurile cover cu voce returnează doar 【cerințele de stil】/【cerințele de cover】 introduse de utilizator; structura fixă pe care o compunem pentru model nu apare în niciun câmp (datele istorice sunt curățate la fel);
3. Nu ghici parametrii lipsă: dacă nu este în extended, nu a fost înregistrat atunci — explică motivul prin retention.

Note despre păstrarea parametrilor

parameter_retention separă „s-a transmis explicit o valoare goală” de „câmpul nu a fost niciodată salvat istoric”:

• core_parameters_available: dacă există înregistrarea principală a sarcinii; normal true la un detaliu valid;
• extended_parameters_available: dacă s-a găsit o înregistrare de sarcină muzicală extinsă asociată;
• sources: din ce tabele de date provine acest răspuns;
• unavailable_fields: câmpuri care nu pot fi recuperate fiabil din istoric; returnează null în parameters.

Piesele istorice obișnuite păstrau de obicei promptul, stilul, titlul curent, modelul, tipul generării și piesa sursă, dar nu au salvat separat toți parametrii avansați. Platforma nu ghicește niciodată valorile lipsă din generation_type.

Unele sarcini muzicale extinse au păstrat și promptul original, stilul, titlul, modelul, plus custom_mode, negative_tags, vocal_gender, style_weight și weirdness_constraint. Chiar și când există înregistrarea extinsă, instrumental, lyrics_mode și wait_audio pot rămâne nerecuperabile.

Titlurile pot fi redenumite ulterior de utilizator. Când o sarcină istorică obișnuită nu a păstrat un titlu original separat, parameters.title poate fi titlul curent; când există o înregistrare de sarcină extinsă, se preferă titlul de generare original păstrat acolo.

Negăsit sau fără permisiune

Erorile de business folosesc un plic de răspuns uniform. Când piesa nu există sau nu aparține contului curent:

{
  "success": false,
  "message": "song not found"
}

Această eroare de business este returnată momentan cu HTTP 200, deci judecă rezultatul după câmpul success. O cheie API lipsă, invalidă, expirată sau dezactivată returnează HTTP 401.

Note de securitate

Endpoint-urile de istoric și detaliu nu returnează niciodată:

• chei API sau ID-uri de token;
• câmpuri de cotă, facturare sau rambursare;
• informații de cont sau răspunsuri brute;
• chei interne ale stocării obiect;
• erori de administrator sau erori de resurse interne.