【Rekommenderas】 röstprofil-API

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

✅ Den här kedjan rekommenderar vi för nya integrationer. Enligt många användares verkliga utvärderingar behåller låtar som skapats den här vägen originalrösten väl: sången i den färdiga mixen ligger närmare personen i det prov du laddade upp, så det är den väg vi för närvarande rekommenderar till kunder.

Jämförelse: den tidigare API för röstkloning och generering med angiven röst fungerar fortfarande, men navigeringen märker den som "rekommenderas inte" och den rekommenderas inte för nya integrationer.

• Dokumentdatum: 2026-09-26
• Omfattning: skapa din egen röst → använd den för att göra en cover på en vald låt / sjunga en ny låt → följ förloppet → ladda ner resultatet
• Alla ändpunkter, fält och svar har verifierats med riktiga anrop (det som står som "uppmätt" verifierades i detalj)

Not: detta dokument beskriver bara de ändpunkter du anropar. Mediehantering, uppgiftsplanering och innehållsvalidering gör servern automatiskt; klienten implementerar dem inte.

0. Kom igång på fem minuter

Fyra steg räcker för att göra två färdiga låtar av ett röstprov.

① Skapa rösten  POST /api/music/voice-profile/create      → hämta voice_id (status=ready)
② Gör en cover  POST /api/music/voice-profile/cover       → få 2 song_id direkt
③ Följ          POST /api/music/query                     → polla tills status=completed
④ Ladda ner     GET  /api/music/download?song_id=…&kind=mp3

Minsta fungerande exempel (curl):

API_KEY="sk-din-nyckel"
BASE="https://www.suno-api.io"

# ① Skapa rösten (ladda upp ett röstprov; 10 s eller mer, under 10 MB rekommenderas)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Min röst" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Gör en cover på en låt med rösten (song_clip_id = clip-id för låten som ska coveras)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\ntext…",
        "style_requirements": "långsam folk, akustisk gitarr",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Polla (flera id samtidigt, kommaseparerade)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Ladda ner mp3 när den är klar (filen kommer bara vid status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Gemensamma konventioner

1.1 Domän och miljö

Alla sökvägar nedan är relativa till Base URL; till exempel är hela adressen för POST /api/music/voice-profile/create https://www.suno-api.io/api/music/voice-profile/create.

1.2 Autentisering

Alla ändpunkter använder samma begärandehuvud, vars värde är API-nyckeln du skapade i konsolen:

Authorization: Bearer sk-xxxxxxxx

• Prefixet Bearer är valfritt; prefixet sk- är också valfritt (Authorization: sk-xxx fungerar lika bra).
• Nyckel saknas eller är ogiltig → HTTP 401, med en body som {"success":false,"message":"…"} (texten följer begärans språk).
• Varje nyckel ser och ändrar bara låtarna och rösterna för sitt eget konto.

1.3 Format för begärans body

• Skapa en röst: multipart/form-data (ladda upp en fil) rekommenderas; application/json (en URL eller base64) stöds också.
• Alla andra ändpunkter: application/json.

1.4 Två svarskuvert (kunden behöver bara känna till dessa två)

Ändpunkterna för "rösthantering" (create / create-from-clip / list / detail / delete) använder affärskuvertet:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

"Cover med röst" går via genereringskanalen och använder genereringskuvertet: framgång är code/message/data, fel är ett error-objekt:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Så avgör du: titta först på HTTP-statuskoden, sedan på success === false och sist på code !== 200 eller om error finns. Ett affärsfel garanterar inte en annan HTTP-status än 200 (ändpunkterna för rösthantering svarar fortfarande HTTP 200 vid fel), så du kan inte gå enbart på statuskoden.

1.5 Idempotens

Att skapa en röst (inklusive "skapa från befintligt ljud") är verkligen idempotent: under samma nyckel skapar en ny sändning av samma client_request_id bara en röst och det andra försöket returnerar direkt det första resultatet (success=true, samma voice_id). Tanken är att klienten själv skapar ett id (ett UUID till exempel) och återanvänder samma värde vid ett nytt försök efter timeout.

Att skicka in en cover dedupliserar inte på begärandenivå (det är en fakturerad generering), så observera två saker:

1. Sändningsidentifieraren ligger i huvudet X-Create-Ui-Client-Request-Id: <ditt sändnings-id>. Den skrivs in i serverns uppgiftspost och underlättar senare utredning; den förhindrar inte en dubbel debitering.
2. Timeout ≠ misslyckande: begäran kan redan ha accepterats och generera. Kontrollera före ett nytt försök med GET /api/music/songs?p=1&page_size=20 (pagineringens parametrar är p / page_size; den kompatibla stavningen ps fungerar också) om en ny låt med generation_type=voice_profile_cover redan har dykt upp, och skicka bara om samma begäran om den inte har det.

Body för create och create-from-clip tar också emot fältet client_request_id (se §3 och §4).

1.6 Översikt över fakturering

Priser kan läsas när som helst från en publik ändpunkt, så hårdkoda dem inte (se §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← baspris för cover med röst
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← pris för förstärkt klon
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Cover använder förskottsdebitering + återbetalning vid fel:

• En avvisad begäran (fel parametrar, plattformens 4xx/5xx, otillräckligt saldo i sig) debiteras inte — vid sändning med en obefintlig röst ändrades saldot inte alls i våra mätningar (delta = 0);
• En accepterad uppgift som till slut misslyckas (inklusive ett tjänstefel hos plattformen) går via serverns återbetalningsväg och ger tillbaka det förskottsdebiterade beloppet.

1.7 Statusordlista

Röstens status:

Låtens status (värdet som frågeändpunkterna returnerar):

2. Översikt över ändpunkter

3. Skapa en röst

POST /api/music/voice-profile/create

Registrera ett stycke vokalljud som en "röst" och få ett voice_id. För plattformen är en röst helt enkelt "ett ljud + dess clip i katalogen", så efter ett lyckat skapande bevaras källjudet permanent (för senare covers).

3.1 Tre indataformer (välj en)

Form A: uppladdning av multipartfil (rekommenderas)

Content-Type: multipart/form-data

file=<ljudets binärdata>     # obligatoriskt
title=<röstens namn>         # valfritt; tomt ger filnamnet utan filändelse
file_name=<ursprungligt filnamn>
source_file_name=<ursprungligt filnamn>
source_kind=upload|record    # valfritt, ursprungsmarkering (uppladdning / inspelning); standard upload
enhanced=false|true          # valfritt, true = förstärkt klon (se §3.5)
client_request_id=<idempotensnyckel>   # valfritt
voice_id=<eget ID>           # valfritt, används sällan

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Min röst" \
  -F "source_kind=upload"

Form B: JSON + en offentlig ljud-URL

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Min röst"
      }'

• URL:en måste vara en offentligt nåbar direktlänk över HTTPS; servern laddar ner den en gång och lägger den i vår objektlagring.
• Du kan också lägga adressen i fältet audio_url, effekten är densamma (skickas båda vinner file_url).
• Om adressen redan ligger i den här plattformens objektlagring (*.myqcloud.com/create-ui/voice-source/...) laddas inget ner igen: den registreras direkt.

Form C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Min röst"
}

• Både prefixet data:audio/xxx;base64, och ren base64 accepteras.
• Storleken är begränsad (base64 blåser upp med 1,33×), använd form A för stora filer.

3.2 Krav på ljudet

3.3 Svar

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Min röst",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Fältbeskrivning (create / list / detail delar samma fältuppsättning):

created_at / updated_at är tidsstämplar i sekunder (10 siffror), inte millisekunder.

3.4 Vanliga fel

3.5 Förstärkt klon (enhanced=true)

För fall där "röstprovet självt innehåller skyddad text / en förstärkt uppladdning behövs". Priset är det för förstärkt uppladdning (10 ¥ per anrop som standard, återbetalas automatiskt vid fel):

• Svaret är omedelbart status=processing + task_id (ännu inget clip_id) och körs asynkront;
• Medan den körs följer du förloppet med GET /api/music/voice-profile/{voice_id}, som returnerar progress_percent / progress_stage / progress_message;
• När den är klar blir status ready och clip_id, audio_url, image_url fylls i;
• Vid fel blir status=failed och error_message lyder ungefär "den förstärkta uppladdningen misslyckades; beloppet har återbetalats automatiskt, försök igen senare";
• En förstärkt klon tar klart längre tid än ett standard-skapande (minuter), så vänta inte med en synkron timeout.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Min röst" -F "enhanced=true"

4. Skapa en röst från befintligt ljud

Om du inte vill ladda upp igen: kopiera ljud som du redan laddat upp eller redan genererat direkt till en röst. Gratis och idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip-id för färdigt ljud i ditt konto (samma som låtens song_id).
• Att skicka samma clip igen skapar ingen ny post: den befintliga rösten returneras direkt med reused: true (uppmätt).

Svaret är alla fält från §3.3 plus två skrivskyddade fält:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Fel (message som det returneras; det rekommenderas att visa eller lokalisera det):

5. Röstlista / detalj / borttagning

5.1 Lista

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Min röst", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Fälten är exakt desamma som i §3.3. Borttagna röster returneras inte som standard.

5.2 Detalj

GET /api/music/voice-profile/{voice_id}

Returnerar ett enskilt röstobjekt (data är objektet självt, inte en array). Medan en förstärkt klon körs tillkommer:

5.3 Ta bort

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Efter borttagning försvinner rösten ur listan och kan inte längre användas för nya covers: att skicka med det voice_id:t ger 400 (se §6.4).
• Låtar som redan skapats med den påverkas inte alls; uppspelning, nedladdning, förlängning, ersättning och separering fungerar som förut.
• Att ta bort en obefintlig röst, eller en som inte tillhör det här kontot, ger {"success":false,"message":"voice not found"}.

6. Gör en cover med en röst (kärnändpunkten)

POST /api/music/voice-profile/cover
Content-Type: application/json

En sändning genererar 2 låtar (som vid vanlig generering).

6.1 Två scenarier

resolved_scene i svaret ekar cover eller sing, så du kan bekräfta vilken väg som användes.

6.2 Begärans fält

Skicka gärna också huvudet X-Create-Ui-Client-Request-Id: <samma sändnings-id>: bara det skrivs in i serverns uppgiftspost och fungerar som nyckel för senare utredning (se §1.5).

Enheter att se upp med: audio_weight / style_weight / weirdness_constraint är decimaltal från 0 till 1, variety är ett heltal från 0 till 4 och duration är i sekunder. Att blanda dem leder till avvisande eller konstiga resultat.

Texten är valfri i scenario B (modellen klarar det själv), men skicka alltid lyrics när ett visst innehåll ska sjungas.

6.3 Svar

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Uppgift] Det här är en cover. … (serverns fasta strukturdel + dina cover- / stilönskemål)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Viktigast:

1. Identifiera de färdiga låtarna med clips[].song_id (den här ändpunkten returnerar inget id-fält).
2. Du får 2 song_id direkt, medan status fortfarande är processing (betyder bara att de accepterats) och audio_url är tom; du måste polla till completed innan du laddar ner. play_url är plattformens förhandslyssningsström, kan redan dyka upp vid sändning och löper ut.
3. description är prompten servern slutligen skickar (den fasta strukturdelen + de cover_requirements / style_requirements du fyllde i); den är mycket användbar när ett resultat ska utredas.
4. source_updates är serverns resultat av mediehanteringen och kan ignoreras av klienten.
5. Den title du skickar skrivs in i serverns uppgiftspost och visas som song_title i senare frågor; att clips[].song_title är tomt i sändningssvaret är normalt.

6.4 Fel

{ "error": { "message": "den här rösten finns inte eller har tagits bort (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Otillräckligt saldo ger ett faktureringsfel redan vid sändning och lämnar aldrig en halvfärdig uppgift.

6.5 Tillgängliga modeller (kundnamn)

Använd modellnamnen för kund (de ovan). chirp-* är interna plattformsnamn och bör inte användas direkt.

7. Följ förloppet

7.1 Bulkgråga (rekommenderas)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids är en kommaseparerad sträng (inte en array).
• Svaret är en naken array (direkt [...], utan success / data-kuvert):

[
  {
    "song_id": "0f2a…",
    "song_title": "Två tigrar",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Uppgift] Det här är en cover. … (serverns slutliga prompt)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Råd för pollning: var 5–10 sekund, med total timeout 10–15 minuter (det långsammaste uppmätta kalla kontot tog cirka 4,5 minuter; mycket få tar längre). Bedöm inte att det är klart efter om audio_url är tomt — använd status.

Kompatibilitetsnot: den här ändpunkten identifierar låtar med song_id; i några tidiga svar förekom ett id-fält, så row.song_id || row.id är det säkra sättet att läsa det.

7.2 Detaljer för en låt

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Två tigrar",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Två tigrar",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Här är created_at / completed_at Unix-sekunder (till skillnad från bulkfrågans ISO-strängar, så klienter bör skilja dem åt).
• wav_url / video_url är den här plattformens nedladdningsingångar (relativa till aktuell domän) och en GET hämtar filen; de är tomma strängar när plattformen inte har producerat det materialet.
• parameter_retention säger vilka sändningsparametrar låten kan spåras till: core_parameters_available=true betyder att kärnparametrarna (text / stil / källa) går att fråga, och med extended_parameters_available=false har de utökade parametrarna ovan inte bevarats (covers med röst ligger för närvarande i den kategorin).

7.3 Mina verk

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=nyckelord

Pagineringens parametrar: p (sidnummer från 1) / page_size (poster per sida; ps är en kompatibel stavning). Valfria status och q (ett nyckelord i titeln). Standard är fallande skapandetid.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Två tigrar",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Med generation_type=voice_profile_cover skiljer du "låtar från en cover med röst" från andra genereringsresultat.

8. Ladda ner de färdiga låtarna

8.1 Ta mp3 direkt (rekommenderas, gratis)

Alla tre fungerar; välj en:

1. Använd audio_url från frågeresultatet (en direktlänk till objektlagringen, enklast).
2. GET /api/music/download?song_id=<id>&kind=mp3 → ger direkt ljudets byteflöde (filnamnet finns redan i Content-Disposition).
3. POST /api/music/download-url (för en signerad tillfällig adress).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind-värden: mp3 (samma som song) / playback (strömmande uppspelning) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) finns för närvarande bara för vissa låtar; misslyckas det skapar du filen själv med API för tidsstämplad text. Svaret är filens råa byteflöde, med Content-Type och Content-Disposition (filnamn) redan satta; wav_url / video_url från GET /api/music/songs/{song_id} är samma ingång med kind=wav|video.

8.2 Konvertera till wav / hämta text / metadata (avgiftsbelagt)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files tar emot: mp3 / wav / lyrics / metadata, upp till 10 låtar åt gången.
• Debiteras per lyckad låt (0,2 ¥ styck); en låt som misslyckas helt debiteras inte, och ett format som misslyckas syns bara i songs[].errors.
• För att hämta filer du redan tagit tidigare: använd först den gratis POST /api/music/free2/cached (samma song_ids + files) för arkiverade adresser; dess songs[].missing_files listar de format som inte är cachade och måste förberedas igen.

9. Fråga om priser

GET /api/pricing/catalog

En publik ändpunkt utan autentisering. Alla styckepriser kunden behöver visa finns i data.catalog.meta (strängar):

Priserna justeras i backoffice, så läs dem live i stället för att hårdkoda dem i klienten. Den faktiska debiteringen för en cover = voice_generation_price × (vid sant max_mode dessutom max_mode_factor).

10. Gränser och varningar

1. Uppladdningsstorlek: ≤ 10 MB (servern tar emot mer, men ingångsgatewayen klipper av för stora bodies vid 10 MiB, vilket ser ut som "avvisad av Suno"; blockera det först på din sida).
2. Provets längd: minst 6 s, 10–60 s rekommenderas; för kort och plattformen avvisar.
3. Provets innehåll: ren sång; undvik allt som liknar en befintlig inspelning (katalogjämförelsen avvisar det).
4. Textgränser: lyrics ≤ 3000 tecken; för style_requirements / negative_tags / title rekommenderas 1000 / 1000 / 100 tecken (stil- och coverönskemål läggs till prompten, håll summan under 3000 tecken).
5. Texten skrivs inte om: det du skickar är det som sjungs (tecken för tecken), utan lokal avkortning.
6. Varje låt ger 2 spår; utgå inte från ett enda resultat.
7. Källjudet bevaras permanent: att ta bort en röst rensar inte dess källjud; det håller senare covers möjliga och efterlevnaden spårbar.
8. Rösten måste vara redo: en röst i processing kan inte användas för covers.
9. Begärans timeout: på ett kallt konto tog den första sändningen upp till cirka 4,5 minuter i mätningarna, så sätt klientens timeout till ≥ 6 minuter. Covers dedupliserar inte på begärandenivå, så kontrollera efter en timeout om en ny låt redan dykt upp (§1.5) innan du bestämmer dig för att skicka igen.
10. Ägarskap av rösten: röster tillhör den som skapade dem; en cover tar bara emot reda och icke borttagna röster. En röst som inte finns, tagits bort eller tillhör ett annat konto ger 400: den här rösten finns inte eller har tagits bort (voice_id=…).

11. Vanliga frågor (FAQ)

F1. Kostar det att skapa en röst? Standard-skapande och "skapa från befintligt ljud" är gratis; bara covers (1,2 ¥ / MAX 2,4 ¥) och förstärkta kloner (10 ¥ som standard) debiteras.

F2. Kan jag använda en färdig låt med komp som röstprov? Rekommenderas inte. Allt med musik, eller med stark likhet med en befintlig inspelning i katalogen, avvisas av plattformen (This audio matches an existing recording in our catalog.). Använd en rent vokal, torr inspelning.

F3. Varför är audio_url tomt efter att jag skickat in en cover? Sändningen betyder bara att den accepterats och status är fortfarande processing. En spelbar/nedladdningsbar adress kommer först när du pollat /api/music/query till status=completed.

F4. Måste jag skicka text i scenario B (utan song_clip_id)? Valfritt. Skicka lyrics för att sjunga ett visst innehåll; utan det klarar modellen det själv, men med mindre kontroll.

F5. Kan ljud som kunden laddat upp användas direkt som röst? Ja: via file_url-formen av create, eller genom att först ladda upp det som en låt och sedan anropa create-from-clip.

F6. Återbetalas pengarna vid misslyckande? En begäran som avvisas direkt (fel parametrar / plattformsfel) debiteras inte, enligt mätningarna; en accepterad uppgift som till slut misslyckas ger tillbaka det förskottsdebiterade beloppet. Vid slutligt misslyckande rapporterar uppgiften status=failed plus error_message.

F7. Kan jag fortfarande lyssna på låtar som skapats med en röst efter att jag tagit bort den? Ja. Borttagningen påverkar bara om rösten kan användas för nya covers.

F8. Hur lång låt kan jag covera åt gången? duration tar emot 1–480 sekunder; utelämnar du det bestämmer plattformen utifrån originalet / materialet. Observera: plattformens färdiga spår är minst cirka 30 sekunder; med ett mindre värde gav mätningarna ändå 29,96 / 29,76 sekunder.

Bilaga A: komplett exempel (Node.js, med pollning och nedladdning)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Skapa rösten (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Gör en cover
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "långsam folk, akustisk gitarr",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Polla till klart (var 5:e sekund, högst 15 minuter)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // naken array
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Ladda ner
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Min röst");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\ntext…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Bilaga B: ändringslogg