API för uppladdning och cover i ett steg

Uppdaterad 2026-09-18 · Suno-API-teamet

Beskrivning av ändpunkten

Uppladdning och cover i ett steg skickar en ljudfil eller en ljud-URL och skapar en ny coverversion utifrån det källjudet.

Ändpunkt: POST /api/music/upload-cover

Fakturering: Betalt, för närvarande som standard 0,6 ¥ per anrop. Den här ändpunkten är "ladda upp och gör cover" — det handlar inte om att ladda upp ett bildomslag. Det faktiskt debiterade beloppet följer den aktuella prisinställningen i backoffice.

Max Mode / Variety: den här ändpunkten stöder de valfria parametrarna max_mode och variety (0-4). Med max_mode på debiteras anropet till dubbelt pris (0,6 → 1,2 ¥ per anrop); variety kostar inget extra. Vad de betyder och hur de skickas står i avsnittet "Avancerade parametrar" i Översikt över det nya API:t.

Väntetider och timeouts (viktigt): detta är en synkron ändpunkt — beställningen accepteras och lämnas till generering först när svaret kommer. Mätt: de flesta anrop svarar på 1-3 sekunder, omkring 10% tar längre än 30 sekunder och det längsta är cirka 230 sekunder. Ställ in klientens timeout på 300 sekunder eller mer; inget svar betyder inte att inget genererades, och försök inte igen direkt efter en timeout (det duplicerar beställningen och debiterar igen). Om anslutningen bröts, kontrollera senare med GET /api/music/songs. Se "Väntetider och timeout-inställningar" i Översikt över det nya API:t.

När ljudet är stort bör du dela upp "uppladdning" och "cover" i två steg (rekommenderas)

Den här ändpunkten kräver att hela ljudet ligger i begärans body: ju större ljud, desto större body, och en enda nätverksstörning eller timeout bryter överföringen på mitten, varefter servern returnerar unexpected end of JSON input (HTTP 400, ingen debitering).

När ljudet passerar ungefär 8 MB, nätet är instabilt eller samma källmaterial ska återanvändas, byt till tvåstegsformen:

1. POST /api/music/upload-source laddar först upp källjudet — gratis, kan försökas igen när som helst — och ger ett clip_id;
2. POST /api/music/generate-from-source startar covern med det clip_id:t — body i det debiterade steget är bara omkring 250 byte.

Se API för att ladda upp källjud, API för cover från ett källklipp och "Stora filer och trunkerade begäranden" i slutet av den här sidan.

Begäransparametrar

Headers

Brödtextparametrar

cover_start_s och cover_end_s anges i sekunder och får vara decimaltal; starttiden måste vara mindre än sluttiden och får inte överstiga källjudets längd. Om båda fälten utelämnas används hela ljudet. audio_weight mappas till Sunos metadata.control_sliders.audio_weight och styr hur mycket resultatet lutar mot referensljudet; det tar 0.0-1.0 och får bara skickas med när begäran innehåller ett giltigt referensljud via file_url eller file_base64. 0 är ett giltigt värde; att utelämna fältet betyder "ej angivet" och behåller Sunos standardbeteende. instrumental och waitAudio måste vara JSON-booleska värden, inte strängar.

Uppladdningsändpunkten svarar som standard asynkront. Så länge clips[].status i svaret är pending är en tom audio_url normalt och betyder inte att uppladdningen eller covern misslyckades; spara det returnerade riktiga song_id och fråga låtfrågeändpunkten tills det är klart innan du läser ljudadressen.

Exempelbegäran

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": "Ny text eller inriktning för bearbetningen",
    "style": "Mandopop, acoustic guitar",
    "title": "Coverversion",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Svar

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

Stora filer och trunkerade begäranden

Rekommenderat: dela upp uppladdning och cover i två steg

Engångsändpunkten (den här) slår ihop uppladdning och generering i ett steg: den stora bodyn ligger i det enda steget, så när det brister vet du varken om något genererades eller om du debiterades.

Slutsats: ljud över ungefär 8 MB, instabilt nät eller samma material flera gånger → använd tvåstegsformen; pyttelitet ljud på ett stabilt nät → den här ändpunkten är enklare.

Vad 400 unexpected end of JSON input betyder

Det betyder att JSON:en servern tog emot är ofullständig (det är inte en felaktig parameter, inte ett behörighets- eller saldoproblem). De vanliga orsakerna, mest sannolik först:

1. En stor body trunkerad mitt i överföringen: ingresslagret registrerar både "hur många byte klienten deklarerade" och "hur många som faktiskt kom fram". Uppmätt fall: klienten deklarerade 14,17 MB men bara 11,8–12,4 MB kom fram, och alla tre begäranden stannade vid omkring 1,6–1,7 s; antalet saknade byte skilde sig varje gång, vilket pekar på ett avbrott i överföringen och inte på en fast gräns (servern begränsar inte body-storleken).
2. Content-Length som inte stämmer med de byte som faktiskt skickades: i Node.js blir det fel att använda en strängs .length (antal UTF-16-tecken) som längd så snart innehållet har kinesiska eller annan flerbytes-text.
3. Att skriva bodyn som en sträng i stället för en Buffer, så att de skrivna byten inte matchar det som deklarerades.

Alla tre inträffar före debiteringen, så ingen kostnad uppstår.

Egenkontroll på klientsidan

• Content-Length kommer från Buffer.byteLength(json, 'utf8') (eller Buffer.from(json).length) — aldrig från json.length;
• Begärans body skrivs som en Buffer, inte som en sträng;
• Socket-/begärans timeout är ≥ 300 sekunder;
• När ljudet passerar ungefär 8 MB: använd file_url (bodyn är bara några hundra byte), eller multipart-uppladdningen i upload-source, eller gå direkt på tvåstegsformen;
• I multipart-begäranden, sätt inte Content-Type manuellt (låt klienten lägga till boundary);
• Skriv ut "byte som faktiskt skickades" och jämför med Content-Length;
• I tvåstegsformen, bekräfta att steg 1 returnerade ett clip_id med slutförd status innan du skickar steg 2.

Vanliga fel

Relaterade ändpunkter: API för att ladda upp källjud (steg 1), API för cover från ett källklipp (steg 2).