API de generare în modul personalizat

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

Descrierea endpoint-ului

Modul personalizat se potrivește când versurile, stilul și titlul sunt deja pregătite și vrei să controlezi vocea care cântă, puterea influenței stilului și gradul de aleatoriu al generării.

Endpoint: POST /api/music/create/custom

Facturare: Cu plată, momentan implicit 0,6 ¥ per apel. Un apel returnează de obicei 2 piese; suma efectiv debitată urmează configurația actuală 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): 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 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; 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.

Parametrii cererii

Headers

Parametri din body

Note despre parametrii avansați

Genul vocii vocal_gender

• Trimite m sau male pentru voce masculină, f sau female pentru voce feminină.
• Serviciul normalizează male și female în m și, respectiv, f.
• Cu instrumental=true, niciun parametru de gen al vocii nu este trimis serviciului de generare.

Influența stilului style_weight

Controlează cât de puternic urmează rezultatul style_tags. Cu cât valoarea e mai mare, cu atât rezultatul tinde să urmeze etichetele de stil pe care le-ai trimis.

Aleatoriu weirdness_constraint

Controlează cât de variat și de experimental este rezultatul. Valorile mari dau de obicei mai multă variație; cele mici un rezultat mai sigur.

Ambii parametri numerici sunt între 0.0 și 1.0, iar 0 este o valoare explicită validă. Doar omiterea completă a câmpului înseamnă „nespecificat”.

Când le completezi, reține că sunt fracții zecimale, nu numere întregi procentuale. Reper sugerat: 0.0–0.3 este conservator, 0.4–0.6 echilibrat, 0.7–1.0 mai experimental; fără o preferință clară folosește 0.5 sau omite-le. Exemplu: weirdness_constraint: 0.5, niciodată 50 sau 50%.

Cu instrumental=true rezultatul este instrumental, deci versurile și genul vocii nu acționează ca la o piesă cântată; dacă ai nevoie de voce, trimite false sau omite câmpul. Câmpurile booleene trebuie să folosească true/false din JSON, nu șiruri.

Exemplu de cerere în Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nNoaptea coboară peste mare\no briză de seară trece pe lângă fereastră',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Briză de seară la mare',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Modul chitanță de acceptare (opțional)

Acest endpoint acceptă și modul chitanță de acceptare din API-ul de generare în modul simplu: cu "accept_mode": "async" în body (sau headerul X-Accept-Mode: async), endpoint-ul returnează imediat 202 și un număr de chitanță, generarea continuă în fundal, iar progresul îl urmărești cu GET /api/music/requests/{request_id}.

Se potrivește clienților care nu trebuie să țină conexiuni lungi sau care nu vor ca un timeout să fie citit ca „nu s-a generat nimic”. Fără acel parametru, comportamentul este exact cel de dinainte.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Briză de seară la mare",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Forma răspunsului și metoda de interogare sunt în secțiunea „Modul chitanță de acceptare” din API-ul de generare în modul simplu.

Validarea parametrilor

Aceste cazuri returnează HTTP 400, iar message-ul erorii indică câmpul invalid:

• style_weight sau weirdness_constraint nu este un număr.
• O valoare numerică este sub 0.0 sau peste 1.0.
• vocal_gender nu este unul dintre m, f, male, female.

Limitele câmpurilor de text

Aceste câmpuri returnează și ele HTTP 400 când sunt prea lungi, nu intră niciodată în generare și nu se fac pre-încasări. Numărarea este în caractere Unicode (un caracter han contează ca 1) și include spațiile de la început și sfârșit:

Mesajul de eroare arată astfel: style_tags must not exceed 1000 characters; received 2772. Primul cuvânt este câmpul care a depășit limita, iar la final este numărul măsurat, deci la un 400 tai după aceste două numere în loc să încerci câmp cu câmp. Regulile generale sunt în „Limitele câmpurilor de text” din Prezentarea noului API.

Răspuns

Endpoint-ul returnează de obicei un array cu 2 piese. O cerere asincronă începe de obicei în pending; salvează song_id și citește starea finală și adresa audio prin API-ul de interogare a pieselor. Câmpurile piesei sunt aceleași ca în API-ul de generare în modul simplu.

Câmpuri compatibile

Integrările noi ar trebui să folosească snake_case peste tot. Dacă o singură cerere conține și snake_case și camelCase, câștigă valoarea din snake_case.