API voor uploaden en coveren in één keer

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

Beschrijving van het endpoint

Uploaden en coveren in één keer verstuurt een audiobestand of een audio-URL en genereert daarmee een nieuwe coverversie van die bronaudio.

Endpoint: POST /api/music/upload-cover

Facturering: Betaald, momenteel standaard 0,6 ¥ per aanroep. Dit endpoint is "uploaden en coveren" — het gaat niet om het uploaden van een afbeeldingscover. Het werkelijk gefactureerde bedrag volgt de huidige prijsconfiguratie in de back-office.

Max Mode / Variety: dit endpoint ondersteunt de optionele parameters max_mode en variety (0-4). Met max_mode aan wordt deze aanroep tegen het dubbele tarief gefactureerd (0,6 → 1,2 ¥ per aanroep); variety kost niets extra. Wat ze betekenen en hoe u ze verstuurt, staat in de sectie "Geavanceerde parameters" van het Overzicht van de nieuwe API.

Wachttijden en timeouts (belangrijk): dit is een synchroon endpoint — de opdracht wordt pas geaccepteerd en aan generatie overgedragen wanneer het antwoord binnenkomt. Gemeten: de meeste verzoeken antwoorden in 1-3 seconden, ongeveer 10% duurt langer dan 30 seconden en de langste is ongeveer 230 seconden. Zet de client-timeout op 300 seconden of meer; geen antwoord betekent niet dat er niets is gegenereerd, en probeer niet direct na een timeout opnieuw (dat dupliceert de opdracht en rekent opnieuw af). Als de verbinding wegviel, controleer later met GET /api/music/songs. Zie "Wachttijden en timeout-instellingen" in het Overzicht van de nieuwe API.

Bij grote audio kunt u "uploaden" en "coveren" beter in twee stappen splitsen (aanbevolen)

Dit endpoint vereist dat de hele audio in de requestbody gaat: hoe groter de audio, hoe groter de body, en één netwerkhik of timeout breekt de overdracht halverwege af, waarna de server unexpected end of JSON input teruggeeft (HTTP 400, geen afrekening).

Wanneer de audio groter is dan ongeveer 8 MB, het netwerk onstabiel is of hetzelfde bronmateriaal hergebruikt wordt, stapt u over op de tweetrapsvorm:

1. POST /api/music/upload-source uploadt eerst de bronaudio — gratis, altijd opnieuw te proberen — en geeft een clip_id;
2. POST /api/music/generate-from-source start de cover met die clip_id — de requestbody van de betaalde stap is maar ongeveer 250 bytes.

Zie de API voor het uploaden van bronaudio, de API voor cover op basis van een bronclip en "Grote bestanden en afgekapte requests" onderaan deze pagina.

Verzoekparameters

Headers

Body-parameters

cover_start_s en cover_end_s zijn in seconden en mogen decimalen bevatten; de starttijd moet kleiner zijn dan de eindtijd en mag de duur van de bronaudio niet overschrijden. Worden beide velden weggelaten, dan wordt de hele audio gebruikt. audio_weight wordt toegewezen aan Suno's metadata.control_sliders.audio_weight en bepaalt hoe sterk het resultaat op de referentieaudio leunt; het neemt 0.0-1.0 en mag alleen worden meegestuurd wanneer het verzoek geldige referentieaudio via file_url of file_base64 bevat. 0 is een geldige waarde; het veld weglaten betekent "niet opgegeven" en houdt Suno's standaardgedrag aan. instrumental en waitAudio moeten JSON-booleans zijn, geen strings.

Het upload-endpoint antwoordt standaard asynchroon. Zolang clips[].status in het antwoord pending is, is een lege audio_url normaal en betekent dat niet dat de upload of de cover is mislukt; bewaar de teruggegeven echte song_id en vraag het nummer-query-endpoint op tot het klaar is voordat u het audioadres gebruikt.

Voorbeeldverzoek

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Nieuwe tekst of richting van de bewerking",
    "style": "Mandopop, acoustic guitar",
    "title": "Coverversie",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Antwoord

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Coverversie",
        "status": "pending"
      }
    ]
  }
}

Grote bestanden en afgekapte requests

Aanbevolen: uploaden en coveren in twee stappen splitsen

Het eenmalige endpoint (dit) voegt uploaden en genereren samen in één stap: de grote body zit in die ene stap, dus bij een breuk weet u niet of er iets is gegenereerd en ook niet of er is afgerekend.

Conclusie: audio boven ongeveer 8 MB, onstabiel netwerk of hetzelfde materiaal meerdere keren → gebruik de tweetrapsvorm; piepkleine audio op een stabiel netwerk → dit endpoint is eenvoudiger.

Wat 400 unexpected end of JSON input betekent

Het betekent dat de JSON die de server ontving onvolledig is (geen verkeerde parameter, geen rechten- of saldoprobleem). De gebruikelijke oorzaken, meest waarschijnlijke eerst:

1. Een grote body midden in de overdracht afgekapt: de ingangslaag registreert zowel "hoeveel bytes de client aankondigde" als "hoeveel er werkelijk aankwamen". Gemeten geval: de client kondigde 14,17 MB aan en er kwam slechts 11,8–12,4 MB aan, en alle drie de requests stopten rond 1,6–1,7 s; het aantal ontbrekende bytes verschilde elke keer, wat wijst op een overdrachtsbreuk en niet op een vaste limiet (de server begrenst de requestbody niet).
2. Content-Length die niet klopt met de werkelijk verzonden bytes: in Node.js rekent het gebruik van .length van een string (aantal UTF-16-tekens) als lengte verkeerd zodra de inhoud Chinees of andere multi-byte tekst bevat.
3. De body als string schrijven in plaats van als Buffer, waardoor de geschreven bytes niet overeenkomen met wat is aangekondigd.

Alle drie gebeuren vóór de afrekening, dus er ontstaan geen kosten.

Zelfcontrole aan de clientkant

• Content-Length komt uit Buffer.byteLength(json, 'utf8') (of Buffer.from(json).length) — nooit uit json.length;
• De requestbody wordt als Buffer geschreven, niet als string;
• De socket-/request-timeout is ≥ 300 seconden;
• Als de audio groter is dan ongeveer 8 MB: gebruik file_url (de body is maar een paar honderd bytes), of de multipart-upload van upload-source, of ga direct naar de tweetrapsvorm;
• Zet bij multipart-requests Content-Type niet handmatig (laat de client de boundary toevoegen);
• Print de "werkelijk verzonden bytes" en vergelijk ze met Content-Length;
• Controleer in de tweetrapsvorm of stap 1 een clip_id met een voltooide status teruggaf voordat u stap 2 verstuurt.

Veelvoorkomende fouten

Gerelateerde endpoints: API voor het uploaden van bronaudio (stap 1), API voor cover op basis van een bronclip (stap 2).