API voor versterkte upload

Bijgewerkt op 2026-09-18 · Suno-API-team

Beschrijving van het endpoint

De versterkte upload stuurt een lokaal audiobestand; het systeem voert de versterking op de achtergrond uit en produceert een compleet, afspeelbaar nummer. De aanroep geeft direct de taakinformatie terug en de client vraagt de voortgang op via het query-endpoint.

Upload-endpoint: POST /api/music/enhanced-upload

Eén taak opvragen: GET /api/music/enhanced-upload/:id

Taak annuleren: POST /api/music/enhanced-upload/:id/cancel

Lijst opvragen: GET /api/music/enhanced-upload

Facturering: 10 ¥ per aanroep, vooraf afgerekend tegen de vaste prijs van suno-enhanced-upload. Mislukt de taak, of wordt die in de toegestane fase geannuleerd, dan wordt het vooraf afgerekende bedrag automatisch terugbetaald. Het werkelijk gefactureerde bedrag volgt de huidige prijsconfiguratie in de back-office.

Aanroepflow

1. Roep POST /api/music/enhanced-upload aan om het audiobestand te uploaden.
2. Bewaar de teruggegeven task_id.
3. Roep GET /api/music/enhanced-upload/:id aan om voortgang en resultaat op te vragen.
4. Zodra Suno klaar is met de definitieve rendering, gebruikt de service de aan die taak gekoppelde Suno-account om het geautoriseerde download-endpoint van Studio aan te roepen en schrijft de MP3 naar de CN2-mediaservice.
5. De taak wordt pas completed als het CN2-asset klaar is; dan leest u het CDN-audioadres uit audio_url in het antwoord.

/api/forbidden is een plaatshouderadres dat in de metadata van Suno Studio kan voorkomen; het is geen afspeelbare of downloadbare resource. Het wordt nooit aan klanten teruggegeven en niet gebruikt als bewijs van voltooiing. Is de rendering klaar maar is CN2 nog aan het voorbereiden, dan blijft het endpoint processing teruggeven en geeft het geen audio_url; de client moet blijven opvragen en het lege adres niet als fout zien.

Een versterkte upload insturen

Headers

Formulierparameters

Voorbeeldverzoek

Het onderstaande voorbeeld gebruikt dezelfde aanroepvorm als bij de productievalidatie, maar de API-sleutel is vervangen door een plaatshouder.

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"

Antwoord

{
  "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"
  }
}

Een taak opvragen

Voorbeeldverzoek

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

Voorbeeldantwoord tijdens verwerking

{
  "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
    }
  }
}

Voorbeeldantwoord na voltooiing

{
  "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
    }
  }
}

Een taak annuleren

Annuleren kan alleen zolang zowel de taak als de backend-workflow zich in de fase queued bevinden. Zodra de taak in leasing, running, processing komt of is voltooid, kan die niet meer worden geannuleerd.

Voorbeeldverzoek

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"

Antwoord

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

Als de taak al met verwerken is begonnen, geeft het endpoint terug:

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

De takenlijst opvragen

Het lijst-endpoint geeft alleen de versterkte uploads terug van de gebruiker bij wie de huidige API-sleutel hoort; gewone generatie-, cover- en extend-taken worden er niet doorheen gemengd.

Query-parameters

Voorbeeldverzoek

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"

Antwoord

{
  "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
      }
    ]
  }
}

Referentie van antwoordvelden

Opmerkingen

• Dit endpoint ondersteunt momenteel alleen multipart-bestandsuploads; JSON file_url en file_base64 worden niet ondersteund.
• Het geüploade bestand is maximaal 80 MB.
• Het upload-endpoint is asynchroon: een antwoord queued betekent dat de taak in de wachtrij staat, niet dat de audio klaar is.
• Annuleren geldt alleen voor taken die nog niet met verwerken zijn begonnen; zodra de verwerking begint wordt de workflow van het platformaccount niet onderbroken.
• Stel geen echte API-sleutels beschikbaar in clientcode.

Een cover starten nadat de versterkte upload klaar is

Als de versterkte upload klaar is, kunt u het resultaat als bronclip gebruiken en POST /api/music/generate-from-source aanroepen om een cover te starten.

Let op: een cover is een synchroon endpoint — de opdracht wordt pas geaccepteerd wanneer het antwoord binnenkomt, en in gemeten gevallen kan dat tot ongeveer 230 seconden duren. Zet de client-timeout op 300 seconden of meer en probeer niet direct na een timeout opnieuw. Zie "Wachttijden en timeout-instellingen" in het Overzicht van de nieuwe API.

Vraag eerst GET /api/music/enhanced-upload/:id op tot task.status completed is. Dan geldt:

• task.song_id is het echte nummer-ID en is de sourceClipId die het cover-endpoint nodig heeft;
• het is aan te raden task.audio_url als sourceAudioUrl mee te geven, zodat de server het geval kan afhandelen waarin de bronclip en het uitvoerende account verschillen;
• task.task_id is alleen het ID van de versterkte uploadtaak en kan niet als sourceClipId worden gebruikt;
• pending:enhanced-upload:* is een plaatshouder-ID van de verwerkingsfase en kan niet voor een cover worden gebruikt.

Gebruik bij het starten van de cover dezelfde API-sleutel als bij de versterkte upload en bouw het verzoek volgens de onderstaande veldkoppeling op:

Vul de overige parameters (tekst, stijl, titel, model) in volgens de API voor cover op basis van een bronclip. Zodra het cover-endpoint de nieuwe clips[].song_id teruggeeft, vraagt u met POST /api/music/query de generatiestatus en de definitieve audio op.