API för röstkloning och generering med angiven röst (rekommenderas inte)

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

⛔ Äldre kedja, rekommenderas inte för nya integrationer. Den här sidan beskriver den tidiga persona-kedjan (voice_task_id / generate-with-voice). Den fungerar fortfarande, men rekommenderas inte längre till kunder; navigeringen till vänster märker den som "rekommenderas inte".

Använd 【Rekommenderas】 röstprofil-API:t för nya integrationer: skapa en röstprofil från ett röstprov (POST /api/music/voice-profile/create) och använd den för att göra en cover på en vald låt eller sjunga en ny låt. En röstprofil är en förstklassig resurs: den kan listas, hämtas och tas bort, och källljudet bevaras permanent.

Om din produkt behöver hela slingan "skapa en röst → återanvända länge → göra covers" bör du välja den nya kedjan.

Viktigt: en klonad röst kan upphöra att gälla.

voice_id / voice_task_id som röstkloningen skapar är inte en resurs som fungerar för evigt: den kan sluta fungera på grund av giltighetstiden, kontots status eller en ändring i röstens status. Den som integrerar får inte klona en gång och sedan återanvända ett lokalt cachelagrat röst-ID för alltid.

Rekommenderat arbetssätt:

• Spara voice_task_id, voice_id, is_available, updated_at och tiden för den senaste lyckade genereringen.
• Anropa GET /api/voice/clone/tasks/{voice_task_id} eller POST /api/voice/clone/tasks/{voice_task_id}/check före varje generering med en klonad röst och bekräfta is_available=true.
• Om ändpunkten svarar att rösten inte är tillgänglig, att uppgiften inte finns eller returnerar selected voice is not ready, be användaren klona igen eller välja en annan tillgänglig röst.
• Lova inte slutanvändare att en klonad röst är en "permanent tillgång"; visa i produktgränssnittet att "en röst kan upphöra att gälla och behöva valideras om eller klonas om".

Beskrivning av ändpunkten

Den här gruppen ändpunkter skapar en återanvändbar röst och genererar låtar med den. Anroparen behöver bara API-nyckeln som plattformen utfärdar; servern sköter uppgiftsinlämning, statussynkronisering, fakturering och nedladdningar.

Autentisering: Authorization: Bearer YOUR_API_KEY

Fakturering:

• Röstvalidering, röstkloning, statusfrågor, borttagning och nedladdningar: gratis.
• Ingången för kloning i ett steg i arbetsytan: fast 5 ¥ per anrop; den gör klart valideringen av källrösten och det andra verifieringsljudet automatiskt och återbetalar vid fel.
• Fortsätta automatiskt till verifieringsljudet efter en vanlig kloning: fast 5 ¥ per anrop; vid fel återbetalas enligt det befintliga flödet.
• Generera en låt med en klonad röst: avgiftsbelagt, fast 1,2 ¥ per anrop; varje anrop returnerar oftast 2 platshållaruppgifter.
• Med Max Mode påslaget (max_mode: true i POST /api/music/generate-with-voice) faktureras 1,2 ¥ per anrop med 2×, alltså 2,4 ¥ per anrop; röstgenerering stöder också variety (0-4, ingen extra kostnad); reglerna finns i avsnittet "Avancerade parametrar" i översikten över det nya API:t.

Anropsflöde

1. Anropa POST /api/voice/clone/validate för att ladda upp källrösten och få ett voice_task_id.
2. Vänta på eller polla GET /api/voice/clone/tasks/{voice_task_id} tills du får validate_info.
3. Användaren läser texten högt och spelar in verifieringsljudet.
4. Anropa POST /api/voice/clone/tasks/{voice_task_id}/generate för att skicka in verifieringsljudet.
5. Anropa POST /api/voice/clone/tasks/{voice_task_id}/check eller fortsätt fråga uppgiften tills is_available=true.
6. Anropa POST /api/music/generate-with-voice för att generera en låt med rösten.
7. Genereringsändpunkten returnerar först platshållaruppgifter; när genereringen är klar och du har det riktiga song_id kan du hämta en enskild fil eller ett paket via nedladdningsändpunkterna.
8. (Valfritt) När rösten inte behövs längre, anropa DELETE /api/voice/clone/voices/{voice_task_id} för att ta bort den; semantiken finns i avsnitt 6.

Det finns också kloning i ett steg: på arbetsytans första inspelnings-/uppladdningssida kan du välja att bli klar i ett svep; systemet gör då validering och röstskapande tillsammans, så du behöver inte spela in ett andra verifieringsljud; det kostar 5 ¥ per anrop och återbetalas vid fel.

Fält för röstuppgiften

1. Skicka in källrösten för validering

Ändpunkt: POST /api/voice/clone/validate

Brödtextparametrar

vocal_end_s - vocal_start_s måste uppfylla minimikravet för sångsegmentet. Ladda upp en tydlig sånginspelning utan tydligt ackompanjemang eller brus.

Exempelbegäran

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Min kinesiska kvinnoröst",
    "description": "Klar och naturlig kinesisk kvinnoröst",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Min kinesiska kvinnoröst",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Fråga en röstuppgift

Ändpunkt: GET /api/voice/clone/tasks/{voice_task_id}

Exempelbegäran

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Min kinesiska kvinnoröst",
      "validate_info": "Läs högt verifieringstexten som returneras här",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Skapa verifieringstexten igen

Ändpunkt: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Anropa när verifieringstexten inte lämpar sig för högläsning eller när valideringen måste göras om.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Skicka in verifieringsljudet och skapa rösten

Ändpunkt: POST /api/voice/clone/tasks/{voice_task_id}/generate

Brödtextparametrar

Exempelbegäran

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Min kinesiska kvinnoröst"
  }'

5. Kontrollera om rösten är användbar

Ändpunkt: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

När uppgiften är användbar är is_available i svaret true och ett voice_id returneras.

6. Ta bort en röst

Ändpunkt: DELETE /api/voice/clone/voices/{voice_task_id}

Fakturering: gratis.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Vad som händer efter borttagningen

• Rösten kan inte längre generera nya låtar: att anropa POST /api/music/generate-with-voice med detta voice_task_id (eller dess voice_id) avvisas med meddelandet selected voice is not ready, utan avgift.
• Låtar som redan skapats med den påverkas inte alls: uppspelning, nedladdning, förlängning, ersättning och stem-separering fungerar som förut.
• Röstuppgiften försvinner ur frågor: GET /api/voice/clone/tasks/{voice_task_id} returnerar record not found.
• Källljudet bevaras enligt plattformens policy för permanent lagring (sedan 2026-09-23 rensar borttagning inte längre det uppladdade röstprovet), men det betyder inte att det kan återställas: den gamla uppgiften är avslutad och för att fortsätta med samma röst måste kloningsflödet köras igen, vilket ger ett nytt voice_task_id.
• Dubbel borttagning: att ta bort samma uppgift igen returnerar record not found (den är redan borttagen och går inte att hitta).

7. Generera en låt med en klonad röst

Ändpunkt: POST /api/music/generate-with-voice

Fakturering: 1,2 ¥ per anrop.

Brödtextparametrar

suno-v6, suno-v6-wild och suno-v6-mini stöds; en tom modell behandlas som suno-v6. De gamla modellerna V5/V5.5 är avvecklade, men historiska uppgifter kan fortfarande visa de gamla modellnamnen.

Den delade begäransstrukturen tolkar också Create UI-kompatibilitetsfält som task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId och voiceId, men de är inte giltiga kundparametrar för denna ändpunkt: en röstuppgift måste skickas som voice_task_id, en valfri röstverifiering som voice_id, och musikgenerering med röst läser aldrig sound-fälten.

Så fyller du i genereringsparametrarna

• Med customMode=false innehåller prompt låtens beskrivning; med customMode=true innehåller prompt hela låttexten, och även style och title måste fyllas i. Skicka inte låttexten till inspirationslägets beskrivningsfält och behandla inte en låtbeskrivning som låttext i avancerat läge.
• weirdnessConstraint och styleWeight är decimala förhållanden från 0.0 till 1.0; 50 eller 50% går inte att skicka. 0.5 är ett balanserat värde; att utelämna dem betyder "inte angivet" och 0 är ett giltigt explicit värde.
• vocalGender accepterar bara m, male, f eller female. instrumental är här enbart ett kompatibilitetsfält: generering med klonad röst behandlas alltid som en sånglåt.
• waitAudio ändrar inget här; ändpunkten returnerar alltid platshållaruppgifter asynkront. Ett tomt audio_url i första resultatet är normalt: fråga med client_request_id och läs ljudadressen först när resultatet är klart.

Rubrikparametrar

Idempotency-Key-beteende:

• Den första begäran skriver en beständig idempotenspost före faktureringen;
• Om samma nyckel med samma begäran redan är klar spelas det första mottagningssvaret upp igen, utan ny avgift och utan ny uppgift;
• Samma nyckel med en annan brödtext avvisas;
• Samma nyckel som fortfarande bearbetas returnerar ett stabilt "bearbetas"-fel och visar ett säkert client_request_id först när ett har skapats;
• Om den första begäran med en nyckel misslyckas behålls felstatusen; ett nytt försök kräver en ny nyckel.

Villkor för cover med sourceClipId

Cover från en källa i kundens API hanteras helt på serversidan: åtkomsten till käll-låten löses av servern och kunden skickar ingen kontoinformation. Om det är möjligt avgörs av ändpunktens faktiska svar.

Källan måste tillhöra den aktuella API-användaren, vara en avslutad låt i arbetsytan som inte är pending: och ha användbart ljud. Vanlig generering, källor från vanlig uppladdning och slutet av en förstärkt uppladdning stöds; mellanposter från förstärkt uppladdning avvisas före faktureringen. Servern accepterar bara det käll-låt-ID som kunden skickar och aldrig ett konto-ID; en otillgänglig eller oavslutad källa ger fel före faktureringen.

Exempelbegäran

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Skriv en kinesisk poplåt om en havskant en sommarnatt",
    "style": "Mandopop, warm piano, emotional",
    "title": "Havsbris en sommarnatt",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Havsbris en sommarnatt",
        "prompt": "Skriv en kinesisk poplåt om en havskant en sommarnatt"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Havsbris en sommarnatt",
        "prompt": "Skriv en kinesisk poplåt om en havskant en sommarnatt"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Om platshållaruppgifter och det slutliga song_id

generate-with-voice är en asynkron genereringsändpunkt. Ett lyckat svar betyder bara att genereringsuppgiften har skickats in, inte att låten är klar.

Betydelsen av svarets viktigaste fält:

Obs: ett placeholder_id som börjar med pending: kan inte användas som slutligt song_id och inte heller skickas till /api/music/query eller nedladdningsändpunkterna. Att anropa /api/music/query enbart med pending:* kan ge en tom array [], eftersom den riktiga låten inte är klar än eller platshållaruppgiften ännu inte ersatts av det slutliga låt-ID:t.

Felaktigt exempel:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Rätt flöde:

1. Anropa POST /api/music/generate-with-voice för att skicka in röstgenereringsuppgiften.
2. Spara client_request_id, items[].placeholder_id och items[].client_request_index från svaret.
3. Polla GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. När items[].song_id har ett värde som inte börjar med pending:, anropa /api/music/query, /api/music/download-file eller /api/music/download-all.

Den aktuella versionen lägger till en publik frågeändpunkt:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Den returnerar uppgiftsresultaten för samma client_request_id under den aktuella användaren, så att kunden själv kan slå upp det slutliga song_id. I den returnerade listan:

• song_id är det riktiga låt-ID:t;
• placeholder_id visas bara medan uppgiften fortfarande är en platshållare;
• ett värde som börjar med pending: kan inte användas med /api/music/query eller nedladdningsändpunkterna.

Om du bara sparade client_request_id eller ett pending:*-platshållar-ID, anropa först denna resultatändpunkt; om det riktiga song_id fortfarande inte hittas, skicka client_request_id till teknisk support för lokalisering.

Fråga resultaten av röstgenereringen

Ändpunkt: GET /api/music/generate-with-voice/results

Fakturering: gratis.

Frågeparametrar

Exempelbegäran

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exempelsvar medan genereringen pågår

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Havsbris en sommarnatt"
      }
    ]
  }
}

Exempelsvar när genereringen är klar

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Havsbris en sommarnatt",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Betydelsen av status på översta nivån

8. Ladda ner en enskild fil

Ändpunkt: POST /api/music/download-file

Brödtextparametrar

Exempelbegäran

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Svaret är en filström; Content-Type och filnamn följer vad backend returnerar.

9. Ladda ner låtens resurser som ett paket

Ändpunkt: POST /api/music/download-all

Brödtextparametrar

Exempelbegäran

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Paketet innehåller oftast ljudet, omslaget och metadata.json; om en resurstyp ännu inte skapats tas den inte med i arkivet.

Vanliga fel

Fel i den här gruppen returnerar alltid HTTP 200: bedöm resultatet med fältet success i svaret (false betyder misslyckande, orsaken finns i message) och titta inte bara på HTTP-statuskoden. Den fullständiga semantiken för att ta bort en röst (om den fortfarande är användbar, om den kan återställas) finns i avsnitt 6.