【Recomandat】 API-ul de profil vocal

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

✅ Recomandăm acest lanț pentru integrări noi. Conform evaluărilor reale ale multor utilizatori, piesele generate prin acest lanț păstrează foarte bine vocea originală: vocalul din mixajul final seamănă mai mult cu persoana din mostra pe care ai încărcat-o, așa că este calea pe care o recomandăm momentan clienților.

Comparație: API-ul de clonare vocală și generare cu voce indicată de dinainte funcționează în continuare, dar meniul îl marchează „nerecomandat" și nu mai este recomandat pentru integrări noi.

• Data documentului: 2026-09-26
• Acoperire: creează-ți propria voce → folosește-o pentru a face un cover la o piesă aleasă / a cânta o piesă nouă → urmărește progresul → descarcă rezultatul
• Toate endpointurile, câmpurile și răspunsurile au fost verificate cu apeluri reale (ce e marcat „măsurat" a fost verificat în detaliu)

Notă: acest document descrie doar endpointurile pe care le apelezi. Procesarea materialelor, planificarea sarcinilor și validarea conținutului sunt făcute automat de server; clientul nu le implementează.

0. Pornire în cinci minute

Patru pași sunt de ajuns ca dintr-o mostră vocală să obții două piese gata.

① Creează vocea   POST /api/music/voice-profile/create      → obții voice_id (status=ready)
② Fă cover        POST /api/music/voice-profile/cover       → obții imediat 2 song_id
③ Urmărește       POST /api/music/query                     → interoghează până status=completed
④ Descarcă        GET  /api/music/download?song_id=…&kind=mp3

Exemplu minim funcțional (curl):

API_KEY="sk-cheia-ta"
BASE="https://www.suno-api.io"

# ① Creează vocea (încarcă o mostră vocală; se recomandă 10 s sau mai mult, sub 10 MB)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Vocea mea" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Fă un cover la o piesă cu această voce (song_clip_id = clip id-ul piesei de coverat)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntextul piesei…",
        "style_requirements": "folk lent, chitară acustică",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Interoghează (mai multe id-uri deodată, separate prin virgule)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Descarcă mp3 după finalizare (fișierul vine doar la status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Convenții comune

1.1 Domeniu și mediu

Toate căile de mai jos sunt relative la Base URL; de exemplu adresa completă a POST /api/music/voice-profile/create este https://www.suno-api.io/api/music/voice-profile/create.

1.2 Autentificare

Toate endpointurile folosesc același antet de cerere, a cărui valoare este cheia API creată în consolă:

Authorization: Bearer sk-xxxxxxxx

• Prefixul Bearer este opțional; prefixul sk- la fel (Authorization: sk-xxx funcționează la fel).
• Cheie lipsă sau nevalidă → HTTP 401, cu un corp de forma {"success":false,"message":"…"} (textul depinde de limba cererii).
• Fiecare cheie vede și poate modifica doar piesele și vocile propriului cont.

1.3 Formatele corpului cererii

• Crearea unei voci: se recomandă multipart/form-data (încărcarea unui fișier); application/json (un URL sau base64) este și el acceptat.
• Restul endpointurilor: application/json.

1.4 Două învelișuri de răspuns (clientul trebuie să cunoască doar acestea)

Endpointurile de „administrare a vocilor" (create / create-from-clip / list / detail / delete) folosesc învelișul de business:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

„Coverul cu voce" trece prin canalul de generare și folosește învelișul de generare: succesul este code/message/data, eșecul este un obiect error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Cum decizi: uită-te mai întâi la codul de stare HTTP, apoi la success === false, apoi la code !== 200 sau la prezența lui error. Un eșec de business nu garantează un HTTP diferit de 200 (endpointurile de administrare a vocilor răspund tot HTTP 200 la eroare), așa că nu te poți baza doar pe codul de stare.

1.5 Idempotență

Crearea unei voci (inclusiv „creează din audio existent") este cu adevărat idempotentă: sub aceeași cheie, retrimiterea aceluiași client_request_id creează o singură voce, iar a doua încercare întoarce direct primul rezultat (success=true, același voice_id). Ideea este ca clientul să genereze singur un id (un UUID, de exemplu) și să folosească aceeași valoare la reîncercarea după un timeout.

Trimiterea unui cover nu deduplică la nivel de cerere (este o generare taxată), așa că reține două lucruri:

1. Identificatorul de trimitere stă în antetul X-Create-Ui-Client-Request-Id: <id-ul tău de trimitere>. Este scris în înregistrarea de sarcină de pe server pentru a ușura investigația ulterioară; nu împiedică o taxare dublă.
2. Timeout ≠ eșec: cererea poate fi deja acceptată și în generare. Înainte de reîncercare, verifică prin GET /api/music/songs?p=1&page_size=20 (parametrii de paginare sunt p / page_size; scrierea compatibilă ps funcționează și ea) dacă a apărut deja o piesă nouă cu generation_type=voice_profile_cover și retrimite aceeași cerere doar dacă nu a apărut.

Corpurile pentru create și create-from-clip acceptă și un câmp client_request_id (vezi §3 și §4).

1.6 Privire generală asupra facturării

Prețurile pot fi citite oricând dintr-un endpoint public, așa că nu le fixa în cod (vezi §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← prețul de bază al unui cover cu voce
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← prețul clonării întărite
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Coverul folosește debitare în avans + returnare la eșec:

• O cerere respinsă (parametri greșiți, un 4xx/5xx al platformei, sold insuficient în sine) nu se taxează — la trimiterea cu o voce inexistentă soldul nu s-a schimbat deloc în măsurătorile noastre (delta = 0);
• O sarcină acceptată care eșuează în final (inclusiv o eroare de serviciu a platformei) trece prin calea de returnare a serverului și dă înapoi suma debitată în avans.

1.7 Dicționar de stări

status-ul vocii:

status-ul piesei (valoarea returnată de endpointurile de interogare):

2. Privire generală asupra endpointurilor

3. Creează o voce

POST /api/music/voice-profile/create

Înregistrează un fragment de audio vocal ca „voce" și obține un voice_id. Pentru platformă, o voce este pur și simplu „un audio + clipul lui din catalog", așa că după o creare reușită acel audio sursă este păstrat permanent (pentru coverurile viitoare).

3.1 Trei forme de intrare (alege una)

Forma A: încărcare de fișier multipart (recomandată)

Content-Type: multipart/form-data

file=<date binare audio>     # obligatoriu
title=<numele vocii>         # opțional; dacă e gol, numele fișierului fără extensie
file_name=<numele original al fișierului>
source_file_name=<numele original al fișierului>
source_kind=upload|record    # opțional, marcă de origine (încărcare / înregistrare); implicit upload
enhanced=false|true          # opțional, true = clonare întărită (vezi §3.5)
client_request_id=<cheie de idempotență>   # opțional
voice_id=<ID propriu>        # opțional, rar folosit

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Vocea mea" \
  -F "source_kind=upload"

Forma B: JSON + un URL audio public

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Vocea mea"
      }'

• URL-ul trebuie să fie un link direct HTTPS accesibil public; serverul îl descarcă o dată și îl mută în stocarea noastră de obiecte.
• Poți pune adresa și în câmpul audio_url, efectul este echivalent (dacă trimiți ambele, câștigă file_url).
• Dacă adresa este deja în stocarea de obiecte a acestei platforme (*.myqcloud.com/create-ui/voice-source/...), nu se descarcă din nou: se înregistrează direct.

Forma C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Vocea mea"
}

• Se acceptă atât prefixul data:audio/xxx;base64,, cât și base64 pur.
• Dimensiunea este limitată (base64 umflă cu 1,33×), așa că folosește forma A pentru fișiere mari.

3.2 Cerințe pentru audio

3.3 Răspuns

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Vocea mea",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Descrierea câmpurilor (create / list / detail împart același set):

created_at / updated_at sunt marcaje de timp în secunde (10 cifre), nu în milisecunde.

3.4 Erori frecvente

3.5 Clonare întărită (enhanced=true)

Pentru cazurile în care „mostra vocală în sine conține versuri protejate / este nevoie de o încărcare întărită". Prețul este cel de încărcare întărită (implicit 10 ¥ per apel, returnat automat la eșec):

• Răspunsul este imediat status=processing + task_id (încă fără clip_id) și rulează asincron;
• În timpul procesării urmărești progresul cu GET /api/music/voice-profile/{voice_id}, care returnează progress_percent / progress_stage / progress_message;
• La final status devine ready, iar clip_id, audio_url, image_url se completează;
• La eșec status=failed, iar error_message sună ca „încărcarea întărită a eșuat; suma a fost returnată automat, încearcă mai târziu";
• O clonare întărită durează clar mai mult decât o creare standard (minute), așa că nu o aștepta cu un timeout sincron.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Vocea mea" -F "enhanced=true"

4. Creează o voce din audio existent

Dacă nu vrei să încarci din nou: copiază direct în voce un audio pe care l-ai încărcat deja sau l-ai generat deja. Gratuit și idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id-ul unui audio finalizat din contul tău (identic cu song_id al piesei).
• Retrimiterea aceluiași clip nu creează o înregistrare nouă: vocea existentă vine direct, cu reused: true (măsurat).

Răspunsul este format din toate câmpurile din §3.3 plus două câmpuri doar-citire:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Erori (message ca atare; se recomandă afișarea sau localizarea):

5. Listă / detalii / ștergerea vocilor

5.1 Listă

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Vocea mea", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Câmpurile sunt exact cele din §3.3. Vocile șterse nu sunt returnate implicit.

5.2 Detalii

GET /api/music/voice-profile/{voice_id}

Returnează un singur obiect de voce (data este obiectul în sine, nu un tablou). Cât timp o clonare întărită rulează, se adaugă:

5.3 Ștergere

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• După ștergere vocea dispare din listă și nu mai poate fi folosită pentru coveruri noi: trimiterea cu acel voice_id dă 400 (vezi §6.4).
• Piesele deja generate cu ea nu sunt afectate deloc; redare, descărcare, continuare, înlocuire și separare funcționează ca înainte.
• Ștergerea unei voci inexistente, sau care nu aparține acestui cont, întoarce {"success":false,"message":"voice not found"}.

6. Cover cu o voce (endpointul central)

POST /api/music/voice-profile/cover
Content-Type: application/json

O trimitere generează 2 piese (ca la generarea obișnuită).

6.1 Două scenarii

resolved_scene din răspuns ecouă cover sau sing, ca să poți confirma ce cale a fost folosită.

6.2 Câmpurile cererii

Se recomandă să trimiți și antetul X-Create-Ui-Client-Request-Id: <același id de trimitere>: doar acela este scris în înregistrarea de sarcină de pe server și servește drept cheie pentru investigația ulterioară (vezi §1.5).

Unități de urmărit: audio_weight / style_weight / weirdness_constraint sunt zecimale de la 0 la 1, variety este un întreg de la 0 la 4, iar duration este în secunde. Amestecarea lor duce la respingeri sau rezultate ciudate.

Versurile sunt opționale în scenariul B (modelul se descurcă singur), dar trimite mereu lyrics când trebuie cântat un conținut anume.

6.3 Răspuns

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Sarcină] Acesta este un cover. … (partea structurală fixă a serverului + cerințele tale de cover / stil)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Puncte cheie:

1. Identifică piesele finale prin clips[].song_id (acest endpoint nu returnează un câmp id).
2. Primești imediat 2 valori song_id, în timp ce status este încă processing (însemnând doar că au fost acceptate), iar audio_url este gol; trebuie să interoghezi până la completed înainte de descărcare. play_url este fluxul de previzualizare al platformei, poate apărea deja la trimitere și expiră.
3. description este promptul pe care serverul îl trimite în final (partea structurală fixă + cover_requirements / style_requirements completate de tine); este foarte util când investighezi un rezultat.
4. source_updates este rezultatul procesării materialelor pe server și clientul îl poate ignora.
5. title-ul trimis este scris în înregistrarea de sarcină de pe server și apare ca song_title în interogările ulterioare; faptul că clips[].song_title este gol în răspunsul de trimitere este normal.

6.4 Erori

{ "error": { "message": "această voce nu există sau a fost ștearsă (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Soldul insuficient dă o eroare de facturare direct la trimitere și nu lasă niciodată o sarcină pe jumătate.

6.5 Modele disponibile (nume pentru client)

Folosește numele de model pentru client (cele de mai sus). chirp-* sunt nume interne ale platformei și nu trebuie folosite direct.

7. Urmărirea progresului

7.1 Interogare în bloc (recomandată)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids este un șir separat prin virgule (nu un tablou).
• Răspunsul este un tablou gol (direct [...], fără învelișul success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Doi tigri",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Sarcină] Acesta este un cover. … (promptul final al serverului)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Sfat de interogare: la fiecare 5–10 secunde, cu un timeout total de 10–15 minute (cel mai lent cont rece măsurat a durat circa 4 minute și jumătate; foarte puține mai mult). Nu judeca finalizarea după faptul că audio_url este gol: folosește status.

Notă de compatibilitate: acest endpoint identifică piesele prin song_id; în câteva răspunsuri timpurii a apărut un câmp id, așa că row.song_id || row.id este citirea sigură.

7.2 Detaliile unei piese

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Doi tigri",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Doi tigri",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Aici created_at / completed_at sunt secunde Unix (spre deosebire de șirurile ISO din interogarea în bloc, deci clienții trebuie să le distingă).
• wav_url / video_url sunt intrările de descărcare ale acestei platforme (relative la domeniul curent), iar un GET ia fișierul; sunt șiruri goale când platforma nu a produs acel material.
• parameter_retention spune la ce parametri de trimitere poate fi urmărită piesa: core_parameters_available=true înseamnă că parametrii de bază (versuri / stil / sursă) pot fi interogați, iar cu extended_parameters_available=false parametrii extinși de mai sus nu au fost păstrați (coverurile cu voce sunt momentan în această categorie).

7.3 Piesele mele

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=cuvant cheie

Parametrii de paginare: p (numărul paginii, de la 1) / page_size (elemente pe pagină; ps este o scriere compatibilă). Opțional status și q (un cuvânt cheie din titlu). Implicit sortare descrescătoare după momentul creării.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Doi tigri",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Cu generation_type=voice_profile_cover distingi „piesele din coverul cu voce" de alte rezultate de generare.

8. Descărcarea pieselor finale

8.1 Ia mp3-ul direct (recomandat, gratuit)

Toate trei funcționează; alege una:

1. Folosește audio_url din rezultatul interogării (un link direct către stocarea de obiecte, cel mai simplu).
2. GET /api/music/download?song_id=<id>&kind=mp3 → întoarce direct fluxul de octeți audio (cu numele fișierului deja în Content-Disposition).
3. POST /api/music/download-url (pentru o adresă temporară semnată).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Valori pentru kind: mp3 (echivalent cu song) / playback (redare în streaming) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) este momentan disponibil doar pentru unele piese; dacă eșuează, generează fișierul singur cu API-ul de versuri cu marcaje de timp. Răspunsul este fluxul brut de octeți ai fișierului, cu Content-Type și Content-Disposition (nume de fișier) deja setate; wav_url / video_url returnate de GET /api/music/songs/{song_id} sunt aceeași intrare cu kind=wav|video.

8.2 Convertire în wav / versuri / metadate (cu plată)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files acceptă: mp3 / wav / lyrics / metadata, până la 10 piese odată.
• Se taxează per piesă reușită (0,2 ¥ fiecare); o piesă care eșuează în totalitate nu se taxează, iar un format care eșuează apare doar în songs[].errors.
• Ca să reiei fișiere deja obținute, folosește mai întâi gratuitul POST /api/music/free2/cached (aceleași song_ids + files) pentru adrese arhivate; songs[].missing_files din răspuns listează formatele care nu sunt în cache și trebuie pregătite din nou.

9. Interogarea prețurilor

GET /api/pricing/catalog

Un endpoint public care nu necesită autentificare. Toate prețurile unitare pe care clientul trebuie să le afișeze sunt în data.catalog.meta (șiruri):

Prețurile sunt ajustate în back-office, așa că citește-le în timp real în loc să le fixezi în client. Taxa reală pentru un cover = voice_generation_price × (la max_mode adevărat încă × max_mode_factor).

10. Limite și avertismente

1. Dimensiunea încărcării: ≤ 10 MB (serverul acceptă mai mult, dar gateway-ul de intrare trunchiază corpurile supradimensionate la 10 MiB, ceea ce arată ca „respins de Suno"; blochează mai întâi de partea ta).
2. Durata mostrei: minimum 6 s, se recomandă 10–60 s; prea scurtă și platforma respinge.
3. Conținutul mostrei: vocal curat; evită orice seamănă foarte mult cu o înregistrare existentă (comparația cu catalogul o respinge).
4. Limite de text: lyrics ≤ 3000 de caractere; pentru style_requirements / negative_tags / title se recomandă 1000 / 1000 / 100 de caractere (cerințele de stil și de cover se concatenează la prompt, ține totalul sub 3000 de caractere).
5. Versurile nu sunt rescrise: se cântă ce trimiți (caracter cu caracter), fără trunchiere locală.
6. Fiecare piesă produce 2 variante; nu presupune un singur rezultat.
7. Audio-ul sursă este păstrat permanent: ștergerea unei voci nu curăță audio-ul sursă; astfel coverurile ulterioare rămân posibile și conformitatea rămâne trasabilă.
8. Vocea trebuie să fie gata: o voce în processing nu poate fi folosită pentru coveruri.
9. Timeout-ul cererii: pe un cont rece prima trimitere a durat până la circa 4 minute și jumătate în măsurători, așa că setează timeout-ul clientului la ≥ 6 minute. Coverurile nu deduplică la nivel de cerere, așa că după un timeout verifică dacă a apărut deja o piesă nouă (§1.5) înainte de a decide retrimiterea.
10. Proprietatea vocii: vocile aparțin creatorului; un cover acceptă doar voci gata și neșterse. O voce inexistentă, ștearsă sau din alt cont dă 400: această voce nu există sau a fost ștearsă (voice_id=…).

11. Întrebări frecvente (FAQ)

Î1. Crearea unei voci costă? Crearea standard și „creează din audio existent" sunt gratuite; se taxează doar coverurile (1,2 ¥ / MAX 2,4 ¥) și clonările întărite (implicit 10 ¥).

Î2. Pot folosi ca mostră o piesă finală cu acompaniament? Nu se recomandă. Orice conține muzică, sau seamănă foarte mult cu o înregistrare existentă din catalog, este respins de platformă (This audio matches an existing recording in our catalog.). Folosește o înregistrare pur vocală, secă.

Î3. De ce audio_url este gol după ce trimit un cover? Trimiterea înseamnă doar că a fost acceptată și status este încă processing. O adresă redabilă/descărcabilă apare doar după ce interoghezi /api/music/query până la status=completed.

Î4. Trebuie să trimit versuri în scenariul B (fără song_clip_id)? Opțional. Trimite lyrics pentru a cânta un conținut anume; fără el modelul se descurcă, dar cu mai puțin control.

Î5. Audio încărcat de client poate fi folosit direct ca voce? Da: prin forma file_url a create, sau încărcându-l mai întâi ca piesă și apoi apelând create-from-clip.

Î6. Se returnează banii dacă eșuează? O cerere respinsă de la început (parametri greșiți / eroare a platformei) nu se taxează, conform măsurătorilor; o sarcină acceptată care eșuează în final dă înapoi suma debitată în avans. La eșec definitiv sarcina raportează status=failed plus error_message.

Î7. După ce șterg o voce, mai pot asculta piesele generate cu ea? Da. Ștergerea afectează doar dacă vocea poate fi folosită pentru coveruri noi.

Î8. Cât de lungă poate fi o piesă coverată o dată? duration acceptă de la 1 la 480 de secunde; dacă îl omiți decide platforma pe baza originalului / materialului. Atenție: variantele finale ale platformei au cel puțin circa 30 de secunde; la o valoare mai mică măsurătorile dădeau tot 29,96 / 29,76 secunde.

Anexa A: exemplu complet (Node.js, cu interogare și descărcare)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Creează vocea (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Fă cover
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "folk lent, chitară acustică",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Interoghează până la final (la fiecare 5 secunde, maximum 15 minute)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // tablou gol
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Descarcă
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Vocea mea");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nversuri…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Anexa B: jurnal de modificări