API de încărcare întărită

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

Descrierea endpoint-ului

Încărcarea întărită trimite un fișier audio local; sistemul face întărirea în fundal și produce o piesă completă, redabilă. Apelul de trimitere returnează imediat informațiile sarcinii, iar clientul interoghează endpoint-ul de consultare pentru progres.

Endpoint de trimitere: POST /api/music/enhanced-upload

Consultarea unei sarcini: GET /api/music/enhanced-upload/:id

Anularea unei sarcini: POST /api/music/enhanced-upload/:id/cancel

Consultarea listei: GET /api/music/enhanced-upload

Facturare: 10 ¥ per apel, debitat în avans la prețul fix al suno-enhanced-upload. Dacă sarcina eșuează sau este anulată în etapa permisă, suma debitată în avans este returnată automat. Suma efectiv debitată urmează configurația actuală de prețuri din back-office.

Fluxul apelurilor

1. Apelează POST /api/music/enhanced-upload pentru a încărca fișierul audio.
2. Salvează task_id-ul returnat.
3. Apelează GET /api/music/enhanced-upload/:id pentru a vedea progresul și rezultatul.
4. Când Suno termină redarea finală, serviciul folosește contul Suno asociat acelei sarcini ca să apeleze endpoint-ul de descărcare autorizată din Studio și scrie MP3-ul în serviciul media CN2.
5. Sarcina devine completed doar când activul CN2 este pregătit; atunci adresa audio CDN se citește din audio_url în răspuns.

/api/forbidden este o adresă de rezervă care poate apărea în metadatele Suno Studio; nu este o resursă redabilă sau descărcabilă. Nu este niciodată returnată clientului și nu este folosită ca dovadă a finalizării. Dacă redarea s-a terminat, dar CN2 încă se pregătește, endpoint-ul continuă să returneze processing și nu returnează audio_url; clientul trebuie să continue interogarea și să nu considere adresa goală un eșec.

Trimiterea unei încărcări întărite

Headers

Parametri de formular

Exemplu de cerere

Exemplul de mai jos folosește aceeași formă de apel ca la validarea în producție, dar cheia API a fost înlocuită cu un substituent.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Răspuns

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Consultarea unei sarcini

Exemplu de cerere

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Exemplu de răspuns în timpul procesării

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Exemplu de răspuns finalizat

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Anularea unei sarcini

Anularea este posibilă doar cât timp sarcina și fluxul din backend sunt încă în etapa queued. După ce sarcina intră în leasing, running, processing sau s-a încheiat, nu mai poate fi anulată.

Exemplu de cerere

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Răspuns

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Dacă sarcina a început deja procesarea, endpoint-ul returnează:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Consultarea listei de sarcini

Endpoint-ul de listă returnează doar sarcinile de încărcare întărită ale utilizatorului căruia îi aparține cheia API curentă; sarcinile de generare obișnuită, cover și extindere nu se amestecă.

Parametri de query

Exemplu de cerere

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Răspuns

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Descrierea câmpurilor din răspuns

Note

• Momentan endpoint-ul acceptă doar încărcare de fișiere multipart; file_url și file_base64 în JSON nu sunt acceptate.
• Fișierul încărcat are maximum 80 MB.
• Endpoint-ul de trimitere este asincron: un răspuns queued înseamnă că sarcina a intrat în coadă, nu că audio-ul este gata.
• Anularea se aplică doar sarcinilor care nu au început procesarea; după începerea procesării, fluxul contului de platformă nu este întrerupt.
• Nu expune chei API reale în codul clientului.

Pornirea unui cover după finalizarea încărcării întărite

După ce încărcarea întărită se încheie, poți folosi rezultatul ca clip sursă și apela POST /api/music/generate-from-source pentru a porni un cover.

Atenție: cover-ul este un endpoint sincron — comanda este acceptată doar la sosirea răspunsului, iar în cazurile măsurate așteptarea poate ajunge la aproximativ 230 de secunde. Setează timeout-ul clientului la 300 de secunde sau mai mult și nu reîncerca imediat după un timeout. Vezi „Timpii de așteptare și setarea timeout-ului” în Prezentarea noului API.

Mai întâi interoghează GET /api/music/enhanced-upload/:id până când task.status este completed. Atunci:

• task.song_id este ID-ul real al piesei și este sourceClipId-ul de care are nevoie endpoint-ul de cover;
• se recomandă să trimiți task.audio_url ca sourceAudioUrl, ca serverul să poată trata cazul în care clipul sursă și contul de execuție diferă;
• task.task_id este doar ID-ul sarcinii de încărcare întărită și nu poate fi folosit ca sourceClipId;
• pending:enhanced-upload:* este un ID de rezervă din etapa de procesare și nu poate fi folosit pentru cover.

Când pornești cover-ul, folosește aceeași cheie API ca la încărcarea întărită și construiește cererea după corespondența de mai jos.

Completează restul parametrilor (versuri, stil, titlu, model) conform API-ului de cover dintr-un clip sursă. Când endpoint-ul de cover returnează noul clips[].song_id, folosește POST /api/music/query pentru a verifica starea generării și audio-ul final.