API voor nummeropvraging en geschiedenis

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

Deze pagina behandelt drie gratis opvraag-endpoints:

Heb je op een generatie-endpoint de ontvangstbewijsmodus (accept_mode=async) gebruikt, dan heb je een bewijsnummer in handen, geen nummer-ID. Volg de voortgang met GET /api/music/requests/{request_id} en kom terug naar de endpoints op deze pagina zodra je het echte song_id hebt. Zie "Ontvangstbewijsmodus" in de Generatie-API in eenvoudige modus.

Authenticatie en gegevensbereik

Alle drie de endpoints authenticeren met dezelfde API-sleutel:

Authorization: Bearer YOUR_API_KEY

De nummergeschiedenis is geïsoleerd per user_id waartoe de API-sleutel behoort. Meerdere sleutels onder hetzelfde hoofdaccount kunnen de geschiedenis van dat account lezen, maar niet die van een andere gebruiker of een ander subsite-account.

De geschiedenis-endpoints geven alleen echt gegenereerde nummers terug. Uitgesloten zijn:

• plaatsvervanger-registraties van generatie die met pending: beginnen;
• uploads van bronaudio en registraties van verbeterde upload;
• deelresultaten zoals scheiding van zang/begeleiding en stems;
• nummers van andere gebruikers of subsite-accounts.

1. Generatiestatus opvragen

Vraagt de huidige status en het eindresultaat op van één of meer nummer-ID's.

Endpoint: POST /api/music/query

Facturering: Gratis.

Headers

Body-parameters

Voorbeeldverzoek

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Voorbeeldantwoord

[
  {
    "song_id": "clip_id_1",
    "song_title": "Titel van het nummer",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Songtekst",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Compatibiliteitsopmerkingen

Oudere documentatie toont song_ids mogelijk als array. Tegenwoordig wordt een kommagescheiden tekenreeks aanbevolen, wat overeenkomt met de daadwerkelijke aanroep van het endpoint.

song_ids moet echte nummer-ID's bevatten. Een plaatsvervanger-ID die met pending: begint is geen definitief song_id en kan hier niet worden gebruikt; alleen plaatsvervanger-ID's opvragen kan een lege array [] opleveren.

Het model, model_version of platform-model_name in een antwoord kan historische waarden bevatten. Nieuwe taken moeten suno-v6, suno-v6-wild of suno-v6-mini gebruiken; suno-v2 tot en met suno-v5-5 zijn uitgefaseerd, en die namen in de geschiedenis zien betekent niet dat het model nog kan worden ingediend.

Zolang een taak pending, submitted of processing is, kunnen audio_url, video_url en cover_url leeg zijn — dat is normaal voor een onvoltooide taak. Trek niet alleen uit een leeg adres de conclusie dat het mislukt is; gebruik status en vraag opnieuw op als de status voltooid is. Alleen als de status voltooid is en de adressen nog steeds leeg zijn, is het zinvol de support te contacteren met het song_id.

⚠️ Audio-adressen leven 7 dagen — verplaats uw bestanden op tijd

De hier teruggegeven audio_url, video_url (en andere media-adressen zoals WAV) worden geleverd vanuit de objectopslag van het platform en vervallen standaard na 7 dagen: de bestanden worden gerecycled en het oude adres geeft dan 404.

• Verplaats de bestanden binnen die 7 dagen naar uw eigen opslag; behandel het adres niet als een langdurige link.
• Een verlopen adres vereist geen nieuwe generatie en wordt niet opnieuw gefactureerd: roep dit endpoint (POST /api/music/query) opnieuw aan voor een vers, geldig adres van dat nummer.

2. Nummergeschiedenis van het account opvragen

Toont de nummers die het hoofdaccount van de huidige API-sleutel heeft gemaakt. Handig voor een eigen nummerlijst, kiezer of geschiedenispagina.

Endpoint: GET /api/music/songs

Facturering: Gratis.

Query-parameters

Resultaten zijn aflopend gesorteerd op created_at en interne record-ID, zodat de paginavolgorde stabiel blijft.

Een ingediende opdracht terugvinden die in timeout liep: generatie-endpoints geven geen tussenliggend antwoord voordat de opdracht is geaccepteerd. Als uw client in timeout liep of de verbinding wegviel tijdens het indienen, kan die opdracht al geaccepteerd zijn en worden gegenereerd. Kijk even op dit endpoint (nieuwste eerst): geaccepteerde nummers verschijnen gewoon in de lijst. Dien alleen opnieuw in als u hebt bevestigd dat het er echt niet is, om dubbele betaling te voorkomen. Zie "Wachttijden en timeout-instellingen" in het Overzicht van de nieuwe API.

Voorbeeldverzoek

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voorbeeldantwoord

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Stad in de nacht",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Antwoordvelden

Het lijst-endpoint geeft geen prompts, factureringsvelden, accountinformatie of ruwe antwoorden terug. Voor prompts en generatieparameters roept u het detail-endpoint van het nummer aan.

3. Generatieparameters opvragen

Vraagt de prompt, stijl, het model en het bronnummer op die het platform bij de generatie heeft bewaard.

Endpoint: GET /api/music/songs/:song_id

Facturering: Gratis.

Alleen nummers van het hoofdaccount van de huidige API-sleutel kunnen worden gelezen. Nummers van andere gebruikers of subsite-accounts worden uniform behandeld als "nummer niet gevonden".

Padparameter

Voorbeeldverzoek

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voorbeeldantwoord

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Stad in de nacht",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "stadsstraten na de regen, songtekst over een weerzien",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Stad in de nacht",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

De velden van parameters

Het veld prompt_view (prompt bekijken, toegevoegd op 2026-09-28)

prompt_view is een genormaliseerde structuur speciaal voor "prompt bekijken": het ordent de gegevens per generatietype in vaste secties, zodat de client niet meer hoeft te bepalen welk veld hij toont. Het is een puur additief veld — de oude velden (parameters, parameter_retention) behouden naam en betekenis, en clients die het nieuwe veld niet verwerken worden er helemaal niet door geraakt.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Aangepaste modus",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Vier uur 's ochtends#701f37", "title_base": "Vier uur 's ochtends", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "guochao-elektronica, diepe subbas, retro-synth",
    "style_tags": "guochao-elektronica, diepe subbas, retro-synth",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Velden die in extended kunnen voorkomen: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, plus de groep geluidseffecten sound_type / sound_bpm / sound_key / sound_loop. Lege waarden worden nooit teruggegeven.

Drie weergaveregels (volg ze in plaats van zelf af te leiden):

1. Onderscheid waar de stijl vandaan komt: bij style_source=suno_derived toont u "stijl (door Suno afgeleid uit uw beschrijving)" en nooit "uw stijl";
2. Interne prompts verschijnen nooit: stem-covertypes geven alleen de door de gebruiker ingevoerde 【stijlvereisten】/【coververeisten】 terug; het vaste raamwerk dat wij voor het model samenstellen verschijnt in geen enkel veld (historische gegevens zijn net zo opgeschoond);
3. Raad ontbrekende parameters niet: staat iets niet in extended, dan is het toen niet vastgelegd — leg dat uit met retention.

Opmerkingen over het bewaren van parameters

parameter_retention onderscheidt "er is expliciet een lege waarde doorgegeven" van "het veld is historisch nooit opgeslagen":

• core_parameters_available: of de hoofdrecord van de taak bestaat; bij een geldige detailopvraging meestal true;
• extended_parameters_available: of een gerelateerde uitgebreide muziektaak-record is gevonden;
• sources: uit welke gegevenstabellen dit antwoord komt;
• unavailable_fields: velden die niet betrouwbaar uit de geschiedenis kunnen worden hersteld; die geven null binnen parameters.

Gewone historische nummers bewaarden meestal de prompt, stijl, huidige titel, het model, het generatietype en het bronnummer, maar niet alle geavanceerde parameters apart. Het platform raadt ontbrekende waarden nooit uit het generation_type.

Sommige uitgebreide muziektaken bewaarden ook de oorspronkelijke prompt, stijl, titel, het model en daarnaast custom_mode, negative_tags, vocal_gender, style_weight en weirdness_constraint. Zelfs als er een uitgebreide record is, kunnen instrumental, lyrics_mode en wait_audio onherstelbaar blijven.

Titels kunnen later door de gebruiker worden hernoemd. Bewaarde een gewone historische taak geen aparte oorspronkelijke titel, dan kan parameters.title de huidige titel zijn; bestaat er een uitgebreide taakrecord, dan krijgt de daar bewaarde oorspronkelijke generatietitel voorrang.

Niet gevonden of geen rechten

Bedrijfsfouten gebruiken een uniforme antwoordenvelop. Als het nummer niet bestaat of niet bij het huidige account hoort:

{
  "success": false,
  "message": "song not found"
}

Deze bedrijfsfout wordt momenteel met HTTP 200 teruggegeven, dus beoordeel het resultaat aan het veld success. Een ontbrekende, ongeldige, verlopen of uitgeschakelde API-sleutel geeft HTTP 401.

Veiligheidsopmerkingen

De geschiedenis- en detail-endpoints geven nooit terug:

• API-sleutels of token-ID's;
• quota-, facturerings- of terugbetalingsvelden;
• accountinformatie of ruwe antwoorden;
• interne sleutels van de objectopslag;
• beheerdersfouten of fouten van interne bronnen.