API-ul de clonare vocală și generare cu voce indicată (nerecomandat)

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

⛔ Lanț vechi, nerecomandat pentru integrări noi. Această pagină descrie lanțul persona de la început (voice_task_id / generate-with-voice). Funcționează în continuare, dar nu mai este recomandat clienților; navigarea din stânga îl marchează drept „nerecomandat".

Pentru integrări noi folosește 【Recomandat】 API-ul de profil vocal: creează un profil vocal dintr-o singură mostră vocală (POST /api/music/voice-profile/create) și folosește-l ca să faci un cover la o piesă anume sau ca să cânte o piesă nouă. Profilul vocal este o resursă de prim rang: poate fi listat, interogat și șters, iar audio-ul sursă este păstrat permanent.

Dacă produsul tău are nevoie de ciclul complet „creează o voce → reutilizeaz-o pe termen lung → fă cover-uri", alege lanțul nou.

Atenție importantă: o voce clonată poate expira.

voice_id / voice_task_id generate de clonarea vocală nu sunt o resursă utilizabilă pentru totdeauna: pot înceta să funcționeze din cauza perioadei de valabilitate, a stării contului sau a schimbării stării vocii. Cine integrează nu trebuie să cloneze o dată și apoi să refolosească la nesfârșit un ID de voce salvat local în cache.

Practica recomandată:

• Salvează voice_task_id, voice_id, is_available, updated_at și momentul ultimei generări reușite.
• Înainte de fiecare generare cu o voce clonată, apelează GET /api/voice/clone/tasks/{voice_task_id} sau POST /api/voice/clone/tasks/{voice_task_id}/check și confirmă is_available=true.
• Dacă endpointul răspunde că vocea nu este disponibilă, că sarcina nu există sau returnează selected voice is not ready, cere utilizatorului să cloneze din nou sau să aleagă altă voce disponibilă.
• Nu promite utilizatorilor finali că o voce clonată este un „activ permanent"; afișează în interfața produsului că „vocea poate expira și poate necesita o nouă validare sau o nouă clonare".

Descrierea endpoint-ului

Acest grup de endpointuri creează o voce reutilizabilă și generează piese cu ea. Cine apelează are nevoie doar de cheia API emisă de platformă; serverul se ocupă de trimiterea sarcinilor, sincronizarea stării, facturare și descărcări.

Autentificare: Authorization: Bearer YOUR_API_KEY

Facturare:

• Validarea vocii, clonarea vocală, interogarea stării, ștergerea și descărcările: gratuit.
• Intarea de clonare într-un pas din spațiul de lucru: 5 ¥ fixe per apel; finalizează automat validarea vocii sursă și al doilea audio de verificare și returnează banii la eșec.
• Continuarea automată către audio-ul de verificare după o clonare obișnuită: 5 ¥ fixe per apel; la eșec se returnează conform fluxului existent.
• Generarea unei piese cu o voce clonată: cu plată, 1,2 ¥ fixe per apel; fiecare apel returnează de obicei 2 sarcini substituent.
• Cu Max Mode activat (max_mode: true în POST /api/music/generate-with-voice), cei 1,2 ¥ per apel se facturează la 2×, adică 2,4 ¥ per apel; generarea vocală acceptă și variety (0-4, fără cost suplimentar); regulile de valori sunt în secțiunea „Parametri avansați" din prezentarea noului API.

Fluxul apelurilor

1. Apelează POST /api/voice/clone/validate pentru a încărca vocea sursă și a obține un voice_task_id.
2. Așteaptă sau interoghează GET /api/voice/clone/tasks/{voice_task_id} până primești validate_info.
3. Utilizatorul citește textul cu voce tare și înregistrează audio-ul de verificare.
4. Apelează POST /api/voice/clone/tasks/{voice_task_id}/generate pentru a trimite audio-ul de verificare.
5. Apelează POST /api/voice/clone/tasks/{voice_task_id}/check sau continuă să interoghezi sarcina până când is_available=true.
6. Apelează POST /api/music/generate-with-voice pentru a genera o piesă cu acea voce.
7. Endpointul de generare returnează mai întâi sarcini substituent; când generarea s-a terminat și ai song_id-ul real, poți folosi endpointurile de descărcare pentru un fișier unic sau o arhivă.
8. (Opțional) Când vocea nu mai este necesară, apelează DELETE /api/voice/clone/voices/{voice_task_id} ca să o ștergi; semantica este în secțiunea 6.

Există și clonarea într-un pas: pe prima pagină de înregistrare/încărcare a vocii sursă din spațiul de lucru poți alege finalizarea într-un singur pas; sistemul face validarea și crearea vocii împreună, astfel încât nu mai trebuie să înregistrezi un al doilea audio de verificare; costă 5 ¥ per apel și se returnează la eșec.

Câmpurile sarcinii de voce

1. Trimite vocea sursă la validare

Endpoint: POST /api/voice/clone/validate

Parametri din body

vocal_end_s - vocal_start_s trebuie să respecte cerința minimă pentru fragmentul vocal. Încarcă o înregistrare vocală curată, fără acompaniament sau zgomot evidente.

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Vocea mea feminină în chineză",
    "description": "Voce feminină în chineză, clară și naturală",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Vocea mea feminină în chineză",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Interoghează o sarcină de voce

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Exemplu de cerere

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Vocea mea feminină în chineză",
      "validate_info": "Citește cu voce tare textul de verificare returnat aici",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Regenerează textul de verificare

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Se apelează când textul de verificare nu este potrivit pentru citire cu voce tare sau când validarea trebuie refăcută.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Trimite audio-ul de verificare și creează vocea

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Parametri din body

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Vocea mea feminină în chineză"
  }'

5. Verifică dacă vocea este utilizabilă

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Când sarcina este utilizabilă, is_available din răspuns este true și se returnează un voice_id.

6. Șterge o voce

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Facturare: gratuit.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Ce se întâmplă după ștergere

• Vocea nu mai poate genera piese noi: apelarea POST /api/music/generate-with-voice cu acest voice_task_id (sau cu voice_id-ul lui) este respinsă cu mesajul selected voice is not ready, fără nicio taxă.
• Piesele deja generate cu ea nu sunt afectate deloc: redarea, descărcarea, continuarea, înlocuirea și separarea pe piste funcționează ca înainte.
• Această sarcină de voce dispare din interogări: GET /api/voice/clone/tasks/{voice_task_id} returnează record not found.
• Audio-ul sursă este păstrat conform politicii de păstrare permanentă a platformei (din 2026-09-23, ștergerea nu mai curăță mostra vocală încărcată), dar asta nu înseamnă că poate fi recuperat: sarcina veche s-a încheiat, iar pentru a continua cu aceeași voce trebuie parcurs din nou fluxul de clonare, care dă un voice_task_id nou.
• Ștergere repetată: ștergerea din nou a aceleiași sarcini returnează record not found (este deja în starea ștearsă și nu mai poate fi găsită).

7. Generează o piesă cu o voce clonată

Endpoint: POST /api/music/generate-with-voice

Facturare: 1,2 ¥ per apel.

Parametri din body

suno-v6, suno-v6-wild și suno-v6-mini sunt acceptate; un model gol este tratat ca suno-v6. Modelele vechi V5/V5.5 au fost retrase, dar sarcinile istorice pot afișa în continuare numele vechi.

Structura comună de cerere interpretează și câmpuri de compatibilitate Create UI precum task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId și voiceId, dar acestea nu sunt parametri valizi de client pentru acest endpoint: sarcina de voce trebuie trimisă ca voice_task_id, verificarea opțională a vocii ca voice_id, iar generarea muzicală cu voce nu citește niciodată câmpurile sound.

Cum se completează parametrii de generare

• Cu customMode=false, prompt conține descrierea piesei; cu customMode=true, prompt conține versurile complete, iar style și title trebuie completate și ele. Nu trimite versurile în câmpul de descriere al modului inspirație și nu trata o descriere de piesă ca versuri în modul avansat.
• weirdnessConstraint și styleWeight sunt proporții zecimale de la 0.0 la 1.0; nu se pot trimite 50 sau 50%. 0.5 este o valoare echilibrată; omiterea înseamnă „nespecificat", iar 0 este o valoare explicită validă.
• vocalGender acceptă doar m, male, f sau female. instrumental este aici doar un câmp de compatibilitate: generarea cu voce clonată este tratată mereu ca piesă vocală.
• waitAudio nu schimbă comportamentul aici; endpointul returnează mereu sarcinile substituent asincron. Un audio_url gol în rezultatul inițial este normal: interoghează cu client_request_id și citește adresa audio doar după ce rezultatul s-a terminat.

Parametri de header

Comportamentul Idempotency-Key:

• Prima cerere scrie o înregistrare de idempotență persistentă înainte de facturare;
• Dacă aceeași cheie cu aceeași cerere este deja finalizată, se redă primul răspuns de acceptare, fără a doua taxă și fără a doua sarcină;
• Aceeași cheie cu un corp diferit este respinsă;
• Aceeași cheie încă în procesare returnează o eroare stabilă de procesare și expune un client_request_id sigur doar când a fost deja generat;
• Dacă prima cerere cu o cheie eșuează, starea de eroare se păstrează; reîncercarea necesită o cheie nouă.

Condiții pentru cover cu sourceClipId

Cover-ul dintr-o sursă în API-ul clientului este gestionat integral pe server: accesul la piesa sursă este rezolvat de server, iar clientul nu trimite nicio informație de cont. Dacă este posibil decide răspunsul real al endpointului.

Sursa trebuie să aparțină utilizatorului API curent, să fie o piesă finalizată din spațiul de lucru care nu este pending: și să aibă audio utilizabil. Sunt acceptate generarea obișnuită, sursele din încărcarea obișnuită și piesa finală a unei încărcări consolidate; înregistrările intermediare ale încărcării consolidate sunt respinse înainte de facturare. Serverul acceptă doar ID-ul piesei sursă trimis de client și niciodată un ID de cont; o sursă indisponibilă sau nefinalizată returnează eroare înainte de facturare.

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Scrie o piesă pop chinezească despre malul mării într-o noapte de vară",
    "style": "Mandopop, warm piano, emotional",
    "title": "Briză de mare într-o noapte de vară",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Exemplu de răspuns

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Briză de mare într-o noapte de vară",
        "prompt": "Scrie o piesă pop chinezească despre malul mării într-o noapte de vară"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Briză de mare într-o noapte de vară",
        "prompt": "Scrie o piesă pop chinezească despre malul mării într-o noapte de vară"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Despre sarcinile substituent și song_id-ul final

generate-with-voice este un endpoint de generare asincronă. Un răspuns reușit înseamnă doar că sarcina de generare a fost trimisă, nu că piesa este gata.

Semnificația câmpurilor principale din răspuns:

Atenție: un placeholder_id care începe cu pending: nu poate fi folosit ca song_id final și nu poate fi trimis la /api/music/query sau la endpointurile de descărcare. Apelarea /api/music/query doar cu valori pending:* poate returna o matrice goală [], pentru că piesa reală nu este încă gata sau sarcina substituent nu a fost încă înlocuită cu ID-ul final.

Exemplu greșit:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Flux corect:

1. Apelează POST /api/music/generate-with-voice pentru a trimite sarcina de generare vocală.
2. Salvează client_request_id, items[].placeholder_id și items[].client_request_index din răspuns.
3. Interoghează în buclă GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Când items[].song_id are o valoare care nu începe cu pending:, apelează /api/music/query, /api/music/download-file sau /api/music/download-all.

Versiunea actuală adaugă un endpoint public de interogare:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Returnează rezultatele sarcinilor pentru același client_request_id la utilizatorul curent, astfel încât clientul să poată găsi singur song_id-ul final. În lista returnată:

• song_id este ID-ul real al piesei;
• placeholder_id apare doar cât timp sarcina este în stare substituent;
• o valoare care începe cu pending: nu poate fi folosită cu /api/music/query sau cu endpointurile de descărcare.

Dacă ai salvat doar client_request_id sau un ID substituent pending:*, apelează mai întâi acest endpoint de rezultate; dacă song_id-ul real tot nu apare, trimite client_request_id la suportul tehnic pentru localizare.

Interogarea rezultatelor generării vocale

Endpoint: GET /api/music/generate-with-voice/results

Facturare: gratuit.

Parametri de query

Exemplu de cerere

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplu de răspuns în timpul procesării

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Briză de mare într-o noapte de vară"
      }
    ]
  }
}

Exemplu de răspuns după finalizare

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Briză de mare într-o noapte de vară",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Semnificația status-ului de nivel superior

8. Descarcă un singur fișier

Endpoint: POST /api/music/download-file

Parametri din body

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Răspunsul este un flux de fișier; Content-Type și numele fișierului urmează ce returnează backendul.

9. Descarcă resursele piesei ca arhivă

Endpoint: POST /api/music/download-all

Parametri din body

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Arhiva conține de obicei audio-ul, coperta și metadata.json; dacă un tip de resursă nu a fost încă generat, nu intră în arhivă.

Erori frecvente

Erorile acestui grup returnează întotdeauna HTTP 200: judecă rezultatul după câmpul success din corp (false înseamnă eșec, motivul este în message) și nu te uita doar la codul de stare HTTP. Semantica completă a ștergerii unei voci (dacă rămâne utilizabilă, dacă poate fi recuperată) este în secțiunea 6.