API-ul de cover dintr-un clip sursă

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

Descrierea endpoint-ului

Cover-ul dintr-un clip sursă reutilizează un clip sursă pe care l-ai încărcat deja, sau care există deja, și generează pe baza lui o nouă versiune de cover.

Endpoint: POST /api/music/generate-from-source

Facturare: Cu plată, momentan implicit 0,6 ¥ per apel. Încărcarea audio-ului sursă în sine este gratuită; plata se aplică atunci când generezi un cover din clipul sursă. 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.

Utilizare recomandată: este pasul 2 al «cover-ului în doi pași». La pasul 1 încarci cu API-ul de încărcare a audio-ului sursă (gratuit) și păstrezi clip_id; la pasul 2 apelezi acest endpoint pentru a porni cover-ul. Astfel audio-ul apare doar la pasul gratuit: dacă încărcarea iese prost, pur și simplu reîncerci și nu se debitează nimic, în timp ce corpul cererii pasului cu plată are doar câteva sute de octeți, deci aproape nu poate eșua pentru că transferul a fost întrerupt. API-ul de încărcare și cover într-un singur pas pune tot audio-ul în corpul cererii, așa că, odată ce audio-ul depășește aproximativ 8 MB, se trunchiază ușor pe drum și returnează unexpected end of JSON input (vezi „Fișiere mari și cereri trunchiate” pe acea pagină).

În plus, același clip_id poate fi reutilizat pentru Extend, Replace Section, separare și alte acțiuni ulterioare, fără a mai încărca audio-ul din nou.

Parametrii cererii

Headers

Parametri din body

weirdnessConstraint, styleWeight și audio_weight iau o zecimală de proporție între 0.0 și 1.0, nu un număr întreg de procente; de exemplu, 50% se scrie 0.5. 0 este o valoare validă; doar omiterea câmpului înseamnă „nespecificat”. audio_weight corespunde câmpului metadata.control_sliders.audio_weight din Suno și controlează cât de mult se sprijină rezultatul pe audio-ul de referință; poate fi inclus doar când cererea conține un sourceClipId valid sau un audio de referință, așa că nu îl trimite la o generare obișnuită doar din text. Cu customMode=true, scrie versurile noi în prompt și furnizează împreună style și title; cu customMode=false, scrie descrierea de creație în prompt. instrumental și waitAudio trebuie să folosească valorile booleene JSON true/false.

Acest endpoint răspunde implicit asincron. Cât timp status-ul returnat este pending, un audio_url gol este normal; așteaptă finalizarea înainte de a folosi adresa audio. sourceClipId trebuie să fie un ID real de piesă/clip sursă — nu folosi task_id, client_request_id sau un ID de rezervă cu pending:.

Ce fel de ID este sourceClipId

sourceClipId este identificatorul real de clip Suno folosit ca sursă a acestui cover. Obiectul de piesă pentru client al platformei numește de obicei acest identificator song_id, în timp ce parametrii cererii de cover păstrează numele sourceClipId; aici ambele înseamnă același ID real de piesă.

Dacă sursa este o încărcare întărită, interoghează mai întâi sarcina de încărcare întărită și așteaptă ca status să devină completed, apoi pune song_id-ul real returnat în sourceClipId. Se recomandă să pui și audio_url și title ale acelui rezultat în sourceAudioUrl și sourceTitle.

Nu pune task_id-ul, client_request_id-ul sau ID-ul de rezervă pending:enhanced-upload:* al încărcării întărite în sourceClipId.

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "Titlul audio-ului original",
    "prompt": "Versuri noi sau direcție de creație",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "Titlul cover-ului",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

Răspuns

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Titlul cover-ului",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

Note

Acest endpoint încearcă să rezolve problema contului căruia îi aparține clipul sursă. Dacă clipul sursă nu poate fi folosit direct, serverul îl poate încărca din nou pe baza informațiilor audio-ului sursă și abia apoi poate genera.