API Replace Section (înlocuire de secțiune)

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

Descrierea endpoint-ului

Replace Section regenerează pe loc un interval de timp dintr-o piesă existentă. Se potrivește pentru a corecta un vers sau a înlocui un pasaj.

Endpoint: POST /api/music/replace-section

Facturare: Cu plată, momentan implicit 0,6 ¥ per apel. 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

startSeconds și endSeconds sunt în secunde și acceptă zecimale; startSeconds trebuie să fie mai mic decât endSeconds, iar intervalul trebuie să fie în durata piesei originale. requestedAt se folosește doar când trebuie transmis momentul cererii, ca marcaj de timp Unix în secunde (nu milisecunde); de obicei poate fi omis.

Înlocuirea este și ea o sarcină asincronă. Clipul returnat poate începe în pending, iar o adresă audio goală atunci este normală; folosește song_id-ul real returnat pentru a interoga rezultatul final.

Lungimea secțiunii: cel puțin 2 secunde (important)

Intervalul de înlocuit nu poate fi mai scurt de 2 secunde. Măsurat: intervalele de 1,0 / 1,2 / 1,5 secunde au eșuat toate, iar 2,0 secunde și peste au funcționat.

Când intervalul este prea scurt, platforma nu răspunde cu „eroare de parametru”, ci cu un mesaj ușor de interpretat greșit:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

Acea frază nu este o problemă de cont sau de abonament — secțiunea este prea scurtă. Lungește intervalul peste 2 secunde și trimite din nou.

Exemplu de cerere

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "versuri complete de context",
    "contextWindowLyrics": "versuri de context ale ferestrei",
    "infillLyrics": "versurile înlocuirii",
    "style": "Mandopop, acoustic",
    "title": "Versiune înlocuită",
    "negativeTags": "noise"
  }'

Răspuns

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Versiune înlocuită",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Câmpuri compatibile

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags