API voor stemklonen en genereren met een opgegeven stem (niet aanbevolen)

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

⛔ Oudere keten, niet aanbevolen voor nieuwe integraties. Deze pagina beschrijft de vroege persona-keten (voice_task_id / generate-with-voice). Die werkt nog steeds, maar wordt niet meer aan klanten aanbevolen; de navigatie links markeert hem als "niet aanbevolen".

Gebruik voor nieuwe integraties de 【Aanbevolen】 stemprofiel-API: maak een stemprofiel van één stemmonster (POST /api/music/voice-profile/create) en gebruik het om een gekozen nummer te coveren of een nieuw nummer te zingen. Een stemprofiel is een eersteklas resource: het kan worden opgesomd, opgehaald en verwijderd, en de bronaudio blijft permanent bewaard.

Als je product de volledige lus "stem aanmaken → langdurig hergebruiken → nummers coveren" nodig heeft, kies dan de nieuwe keten.

Belangrijk: een gekloonde stem kan verlopen.

De voice_id / voice_task_id die het stemklonen oplevert is geen eeuwig bruikbare resource: hij kan ophouden te werken door de geldigheidsduur, de accountstatus of een wijziging in de stemstatus. Integratoren mogen niet één keer klonen en daarna voor altijd een lokaal gecachte stem-ID hergebruiken.

Aanbevolen werkwijze:

• Bewaar voice_task_id, voice_id, is_available, updated_at en het tijdstip van de laatste geslaagde generatie.
• Roep vóór elke generatie met een gekloonde stem GET /api/voice/clone/tasks/{voice_task_id} of POST /api/voice/clone/tasks/{voice_task_id}/check aan en bevestig is_available=true.
• Geeft het endpoint terug dat de stem niet beschikbaar is, dat de taak niet bestaat of selected voice is not ready, vraag de gebruiker dan opnieuw te klonen of een andere beschikbare stem te kiezen.
• Beloof eindgebruikers niet dat een gekloonde stem een "permanent bezit" is; toon in de productinterface dat "een stem kan verlopen en opnieuw gevalideerd of gekloond moet worden".

Beschrijving van het endpoint

Deze groep endpoints maakt een herbruikbare stem en genereert daarmee nummers. De aanroeper heeft alleen de door het platform uitgegeven API-key nodig; de server regelt het indienen van taken, het synchroniseren van statussen, de facturering en de downloads.

Authenticatie: Authorization: Bearer YOUR_API_KEY

Facturering:

• Stemvalidatie, stemklonen, statusopvraging, verwijderen en downloads: gratis.
• De instap voor klonen in één stap in de werkruimte: vast 5 ¥ per aanroep; die rondt de validatie van de bronstem en de tweede verificatie-audio automatisch af en betaalt terug bij een fout.
• Automatisch doorgaan naar de verificatie-audio na een gewoon kloon: vast 5 ¥ per aanroep; bij een fout wordt volgens de bestaande flow terugbetaald.
• Een nummer genereren met een gekloonde stem: betaald, vast 1,2 ¥ per aanroep; elke aanroep levert meestal 2 plaatsaanduidingstaken op.
• Met Max Mode aan (max_mode: true bij POST /api/music/generate-with-voice) worden de 1,2 ¥ per aanroep tegen 2× gefactureerd, dus 2,4 ¥ per aanroep; stemgeneratie ondersteunt ook variety (0-4, zonder extra kosten); de regels staan in het onderdeel "Geavanceerde parameters" van het overzicht van de nieuwe API.

Volgorde van aanroepen

1. Roep POST /api/voice/clone/validate aan om de bronstem te uploaden en een voice_task_id te krijgen.
2. Wacht op of poll GET /api/voice/clone/tasks/{voice_task_id} tot je validate_info krijgt.
3. De gebruiker leest die tekst voor en neemt de verificatie-audio op.
4. Roep POST /api/voice/clone/tasks/{voice_task_id}/generate aan om de verificatie-audio in te dienen.
5. Roep POST /api/voice/clone/tasks/{voice_task_id}/check aan of blijf de taak opvragen tot is_available=true.
6. Roep POST /api/music/generate-with-voice aan om met die stem een nummer te genereren.
7. Het generatie-endpoint levert eerst plaatsaanduidingstaken; zodra de generatie klaar is en je de echte song_id hebt, kun je met de download-endpoints één bestand of een pakket ophalen.
8. (Optioneel) Als de stem niet meer nodig is, roep dan DELETE /api/voice/clone/voices/{voice_task_id} aan om hem te verwijderen; de semantiek staat in sectie 6.

Er is ook klonen in één stap: op de eerste opname-/uploadpagina van de werkruimte kun je in één keer afronden kiezen; het systeem doet dan validatie en stemaanmaak in één keer, zodat je geen tweede verificatie-audio hoeft op te nemen; het kost 5 ¥ per aanroep en wordt bij een fout terugbetaald.

Velden van de stemtaak

1. Bronstem ter validatie indienen

Endpoint: POST /api/voice/clone/validate

Body-parameters

vocal_end_s - vocal_start_s moet aan de minimumlengte voor een zangfragment voldoen. Upload een heldere zangopname zonder duidelijke begeleiding of ruis.

Voorbeeldverzoek

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": "Mijn Chinese vrouwenstem",
    "description": "Heldere, natuurlijke Chinese vrouwenstem",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Voorbeeldantwoord

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mijn Chinese vrouwenstem",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Een stemtaak opvragen

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Voorbeeldverzoek

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

Voorbeeldantwoord

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Mijn Chinese vrouwenstem",
      "validate_info": "Lees de verificatietekst die hier wordt teruggegeven voor",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. De verificatietekst opnieuw genereren

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Aanroepen wanneer de verificatietekst niet geschikt is om voor te lezen of wanneer de validatie opnieuw moet.

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. De verificatie-audio indienen en de stem aanmaken

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body-parameters

Voorbeeldverzoek

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": "Mijn Chinese vrouwenstem"
  }'

5. Controleren of de stem bruikbaar is

Endpoint: 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 '{}'

Als de taak bruikbaar is, staat is_available in het antwoord op true en wordt een voice_id teruggegeven.

6. Een stem verwijderen

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Facturering: gratis.

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

Voorbeeldantwoord

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

Wat er na het verwijderen gebeurt

• De stem kan geen nieuwe nummers meer genereren: POST /api/music/generate-with-voice met deze voice_task_id (of zijn voice_id) wordt geweigerd met de melding selected voice is not ready, zonder kosten.
• Nummers die er al mee zijn gemaakt blijven volledig onaangetast: afspelen, downloaden, verlengen, vervangen en stems splitsen werken zoals voorheen.
• Deze stemtaak verdwijnt uit opvragingen: GET /api/voice/clone/tasks/{voice_task_id} geeft record not found.
• De bronaudio blijft bewaard volgens het permanente bewaarbeleid van het platform (sinds 2026-09-23 wist verwijderen het geüploade stemmonster niet meer), maar dat betekent niet dat het herstelbaar is: die oude taak is afgelopen en om dezelfde stem te blijven gebruiken moet de kloonflow opnieuw worden doorlopen, wat een nieuwe voice_task_id oplevert.
• Dubbel verwijderen: dezelfde taak nogmaals verwijderen geeft record not found (hij staat al op verwijderd en is niet meer te vinden).

7. Een nummer genereren met een gekloonde stem

Endpoint: POST /api/music/generate-with-voice

Facturering: 1,2 ¥ per aanroep.

Body-parameters

suno-v6, suno-v6-wild en suno-v6-mini worden ondersteund; een leeg model wordt als suno-v6 behandeld. De oude modellen V5/V5.5 zijn uitgefaseerd, maar historische taken kunnen nog de oude modelnamen tonen.

De gedeelde verzoekstructuur verwerkt ook Create UI-compatibiliteitsvelden zoals task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId en voiceId, maar dat zijn geen geldige klantparameters voor dit endpoint: een stemtaak moet als voice_task_id worden gestuurd, een optionele stemverificatie als voice_id, en muziekgeneratie met een stem leest de sound-velden nooit.

Hoe je de generatieparameters invult

• Bij customMode=false bevat prompt de nummerbeschrijving; bij customMode=true bevat prompt de volledige songtekst, en moeten ook style en title worden ingevuld. Stuur de songtekst niet naar het beschrijvingsveld van de inspiratiemodus en behandel een nummerbeschrijving niet als songtekst van de geavanceerde modus.
• weirdnessConstraint en styleWeight zijn decimale verhoudingen van 0.0 tot 1.0; 50 of 50% is niet toegestaan. 0.5 is een evenwichtige waarde; weglaten betekent "niet opgegeven" en 0 is een geldige expliciete waarde.
• vocalGender accepteert alleen m, male, f of female. instrumental is hier alleen een compatibiliteitsveld: genereren met een gekloonde stem wordt altijd als gezongen nummer behandeld.
• waitAudio verandert hier niets; het endpoint levert altijd asynchroon plaatsaanduidingstaken. Een lege audio_url in het eerste resultaat is normaal: vraag op met client_request_id en lees het audioadres pas als het resultaat klaar is.

Header-parameters

Gedrag van Idempotency-Key:

• Het eerste verzoek schrijft vóór de facturering een blijvend idempotentierecord;
• Is dezelfde sleutel met hetzelfde verzoek al afgerond, dan wordt het eerste acceptatieantwoord herhaald, zonder tweede afschrijving of tweede taak;
• Dezelfde sleutel met een andere body wordt geweigerd;
• Dezelfde sleutel die nog in behandeling is geeft een stabiele "in behandeling"-fout en geeft alleen een veilige client_request_id terug zodra die is gegenereerd;
• Mislukt het eerste verzoek onder een sleutel, dan blijft de foutstatus staan; opnieuw proberen vereist een nieuwe sleutel.

Voorwaarden voor coveren met sourceClipId

Coveren vanaf een bron in de klant-API wordt volledig server-side afgehandeld: de toegang tot het bronnummer wordt op de server bepaald en de klant stuurt geen accountgegevens mee. Of het kan, blijkt uit het werkelijke antwoord van het endpoint.

De bron moet toebehoren aan de huidige API-gebruiker, een afgerond nummer in de werkruimte zijn dat niet pending: is, en bruikbare audio hebben. Ondersteund worden gewone generatie, bronnen uit een gewone upload en het eindnummer van een versterkte upload; tussenrecords van een versterkte upload worden vóór de facturering geweigerd. De server accepteert alleen de door de klant gestuurde bronnummer-ID en nooit een account-ID; een onbeschikbare of niet-afgeronde bron geeft een fout vóór de facturering.

Voorbeeldverzoek

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": "Schrijf een Chinees popnummer over de kust op een zomernacht",
    "style": "Mandopop, warm piano, emotional",
    "title": "Zeewind op een zomernacht",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Voorbeeldantwoord

{
  "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": "Zeewind op een zomernacht",
        "prompt": "Schrijf een Chinees popnummer over de kust op een zomernacht"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Zeewind op een zomernacht",
        "prompt": "Schrijf een Chinees popnummer over de kust op een zomernacht"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Over plaatsaanduidingstaken en de definitieve song_id

generate-with-voice is een asynchroon generatie-endpoint. Een geslaagd antwoord betekent alleen dat de generatietaak is ingediend, niet dat het nummer klaar is.

Betekenis van de belangrijkste velden in het antwoord:

Let op: een placeholder_id die met pending: begint kan niet als definitieve song_id dienen en ook niet aan /api/music/query of de download-endpoints worden doorgegeven. Alleen met pending:* /api/music/query aanroepen kan een lege array [] opleveren, omdat het echte nummer nog niet klaar is of de plaatsaanduidingstaak nog niet door de definitieve nummer-ID is vervangen.

Onjuist voorbeeld:

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

Juiste volgorde:

1. Roep POST /api/music/generate-with-voice aan om de stemgeneratietaak in te dienen.
2. Bewaar client_request_id, items[].placeholder_id en items[].client_request_index uit het antwoord.
3. Poll GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Zodra items[].song_id een waarde heeft die niet met pending: begint, roep je /api/music/query, /api/music/download-file of /api/music/download-all aan.

De huidige versie voegt een openbaar opvraag-endpoint toe:

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

Het geeft de taakresultaten voor dezelfde client_request_id onder de huidige gebruiker terug, zodat klanten de definitieve song_id zelf kunnen opzoeken. In de teruggegeven lijst:

• song_id is de echte nummer-ID;
• placeholder_id verschijnt alleen zolang de taak nog in de plaatsaanduidingsstatus staat;
• een waarde die met pending: begint kan niet met /api/music/query of de download-endpoints worden gebruikt.

Heb je alleen de client_request_id of een pending:*-plaatsaanduidings-ID bewaard, roep dan eerst dit resultaten-endpoint aan; is de echte song_id nog steeds niet te vinden, stuur de client_request_id dan naar de technische support om hem te lokaliseren.

De resultaten van stemgeneratie opvragen

Endpoint: GET /api/music/generate-with-voice/results

Facturering: gratis.

Query-parameters

Voorbeeldverzoek

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"

Voorbeeldantwoord tijdens verwerking

{
  "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": "Zeewind op een zomernacht"
      }
    ]
  }
}

Voorbeeldantwoord na afronding

{
  "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": "Zeewind op een zomernacht",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Betekenis van de bovenste status

8. Eén bestand downloaden

Endpoint: POST /api/music/download-file

Body-parameters

Voorbeeldverzoek

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

Het antwoord is een bestandsstream; Content-Type en bestandsnaam volgen wat de backend teruggeeft.

9. De bronnen van een nummer als pakket downloaden

Endpoint: POST /api/music/download-all

Body-parameters

Voorbeeldverzoek

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

Het pakket bevat meestal de audio, de hoes en metadata.json; is een soort bron nog niet gegenereerd, dan komt die niet in het archief.

Veelvoorkomende fouten

Fouten van deze groep geven altijd HTTP 200 terug: beoordeel het resultaat aan het veld success in de body (false betekent mislukking, met de reden in message) en kijk niet alleen naar de HTTP-statuscode. De volledige semantiek van het verwijderen van een stem (of die bruikbaar blijft, of die hersteld kan worden) staat in sectie 6.