API de generare de voce vorbită (Speech)

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

Descrierea endpoint-ului

Speech transformă un text de discurs sau o descriere de o singură linie în audio de „vorbire/discurs”, opțional cu muzică de fundal. Se potrivește pentru discursuri, toasturi, narațiune, texte de voce off, conținut audio și scenarii similare.

Atenție: acest endpoint generează audio vorbit, nu o piesă cântată (fără melodie și fără voce cântată). Dacă ai nevoie de cântat, folosește API-ul de generare în modul simplu sau API-ul de generare în modul personalizat.

Endpoint: POST /api/music/speech

Facturare: Cu plată, momentan implicit 0,6 ¥ per apel. Un apel returnează de obicei 2 fișiere audio; suma efectiv debitată urmează configurația de prețuri din back-office.

Max Mode / Variety: acest endpoint acceptă parametrii opționali max_mode și variety (0-4). Cu max_mode activat, acest apel este facturat la dublu (0,6 → 1,2 ¥ per apel); variety nu costă nimic în plus. Ce înseamnă și cum se trimit este în secțiunea „Parametri avansați” din Prezentarea noului API.

Timpii de așteptare și timeout-urile (important): acesta este un endpoint sincron — comanda este acceptată și transmisă spre generare doar când sosește răspunsul. Din măsurători, majoritatea cererilor răspund în câteva secunde (1-10 s); însă, ca la celelalte endpoint-uri de generare sincrone, în cazuri extreme poate dura mai mult. Setează timeout-ul clientului la 300 de secunde sau mai mult; 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.

Conformitatea conținutului: platforma verifică textul pentru drepturi de autor și politica de conținut. Dacă este considerat material protejat (de exemplu citarea versurilor altcuiva sau textul literal al unei opere cunoscute), acest apel eșuează și suma se returnează integral automat. Treci la formularea ta sau transformă citatul în parafrază și încearcă din nou.

Parametrii cererii

Headers

Parametri din body

Acest endpoint nu acceptă duration: trimiterea lui returnează HTTP 400, nu este ignorată în silență. Durata discursului este determinată de lungimea conținutului din script.

Exemple de cerere

Cerere minimă (doar textul)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Bună dimineața tuturor! Astăzi vorbesc despre folosirea bună a timpului nostru și despre a merge înainte."
  }'

Cerere completă (cu ton, gen și muzică de fundal oprită)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Exemplu în Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Bună ziua, colegi. Vă raportez progresul din această săptămână.',
        'tone': 'calm și clar, raport de ședință',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # de obicei 2 intrări
for item in items:
    print(item['song_id'], item['status'])

Explicații privind parametrii

script (discursul, obligatoriu)

• Lipește conținutul pe care vrei să îl spui; poți scrie și o singură descriere și lăsa modelul să redacteze discursul (de exemplu „un discurs de încurajare la pauză pentru o echipă care pierde cu douăzeci de puncte, de la o șoaptă scăzută la un urlet în plină voce”).
• Liniile noi, paragrafele și indicațiile scenice precum [pauză] pot fi scrise direct, iar modelul le respectă pe cât posibil.
• Limita este de 3000 de caractere (numărate în caractere Unicode; un caracter chinez contează ca 1); peste limită se returnează 400 și nu se debitează.

tone (ton și scenă, opțional)

Descrie cum se vorbește, nu ce se spune. Este bine să incluzi patru tipuri de informații: ton, ritm/viteză, emoție și scenă.

Energic și puternic, ritm de la lent la rapid, pauze clare; sala de festivități, în fața tuturor elevilor și profesorilor
Cald și blând, ritm domol; recepție de nuntă
Calm și reținut, ritm constant și clar; raport către consiliul de administrație

Limita este de 1000 de caractere. Dacă nu îl trimiți, modelul decide pe baza conținutului din script.

gender / vocal_gender (genul vorbitorului, opțional)

• Pentru voce masculină trimite m sau male, pentru voce feminină f sau female; serverul le normalizează la m / f.
• Ambele nume de câmp funcționează, folosește doar unul: gender este forma recomandată la acest endpoint; dacă folosești deja modul personalizat, poți continua cu vocal_gender.
• Omiterea înseamnă „oricare”, iar modelul decide.

backing_music (muzică de fundal, opțional)

• Implicit true (cu muzică de fundal), la fel ca în versiunea web Suno.
• false dă un discurs doar cu voce, util dacă vrei să adaugi ulterior propria muzică sau voce off.
• Trebuie să fie o valoare booleană JSON true / false; șirurile "true" și "1" sunt acceptate, dar se recomandă valorile booleene.

model (model, opțional)

Toate cele trei modele pentru client sunt disponibile la același preț (0,6 ¥ per apel). Discursul este generat de familia Suno v6; fără valoare este tratat ca suno-v6. Dacă nu ai o preferință clară, de obicei nu este nevoie să trimiți acest câmp.

Validarea parametrilor și limitele de text

Cazurile de mai jos returnează HTTP 400 și toate sunt blocate înainte de debitare, deci nu se produce niciun cost:

Limitele câmpurilor de text

Depășirea limitei returnează și ea HTTP 400 și nu pornește generarea și nu face debitare în avans. Numărătoarea este în caractere Unicode (un caracter chinez contează ca 1) și include spațiile de la început și de la sfârșit:

Eroarea arată astfel: script must not exceed 3000 characters; received 4120: primul cuvânt este câmpul care a depășit limita, iar finalul este numărul real, așa că la un 400 poți scurta direct după aceste două numere.

Răspuns

Răspunsul este un tablou de piese exact ca la celelalte endpoint-uri de generare (de obicei 2 intrări); salvează song_id și folosește API-ul de interogare a pieselor și de istoric pentru a vedea starea finală și adresa audio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Folosirea bună a timpului",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Eșecul generării și rambursările

Dacă generarea eșuează, costul acelui apel este rambursat integral automat; nu e nevoie să contactezi suportul. Motivul se vede în răspuns sau în error_message al API-ului de interogare a pieselor și de istoric.

Cel mai frecvent motiv este încadrarea conținutului ca material protejat, de exemplu:

Your lyrics contain copyrighted material. Please change it and try again.

În acest caz, înlocuiește textul cu formularea ta (sau transformă citatul în parafrază) și trimite din nou.

Întrebări frecvente

Î: De ce rezultatul este „vorbire” și nu cântat? R: Acesta este endpoint-ul de discursuri, iar ieșirea este audio vorbit. Pentru cântat folosește endpoint-urile de generare sau modul personalizat.

Î: De ce primesc 2 intrări de fiecare dată? R: Ca la celelalte endpoint-uri de generare ale platformei, o generare produce 2 candidați; interoghează-i separat după song_id și păstrează-l pe cel care îți place.

Î: Cum controlez durata? R: Este determinată de lungimea lui script; acest endpoint nu acceptă parametrul duration.

Î: Pot specifica o voce (de exemplu vocea mea clonată)? R: Versiunea actuală nu acceptă. Discursul folosește un set fix de voci, iar gender alege masculin sau feminin; dacă ai nevoie de propria voce, folosește funcția corespunzătoare a API-ului de creare a profilului vocal (recomandat).

Î: Ce se întâmplă dacă nu trimit tone? R: Modelul deduce tonul și ritmul din conținutul lui script. Pentru a reproduce un stil în mod constant, scrie tonul, viteza și scena în tone.

Câmpuri compatibile

În integrările noi folosește consecvent snake_case. Celelalte câmpuri (script, tone, song_title, backing_music) nu au aliasuri camelCase.

Pașii următori

După ce ai song_id:

1. Folosește API-ul de interogare a pieselor și de istoric pentru a vedea starea generării și adresa audio;
2. După finalizare, folosește API-ul de descărcare și ascultare a conținutului media al pieselor pentru a descărca sau asculta;
3. Pentru descărcări în lot sau copiere în propriul spațiu de stocare, vezi endpoint-urile centrului de descărcare.