API för låtfrågor och historik

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

Den här sidan täcker tre kostnadsfria frågeändpunkter:

Om du använde kvittoläge för mottagande (accept_mode=async) på en genereringsändpunkt har du ett kvittonummer i handen, inte ett låt-ID. Följ framstegen med GET /api/music/requests/{request_id} och kom tillbaka till ändpunkterna på den här sidan när du har det riktiga song_id. Se "Kvittoläge för mottagande" i Genererings-API i enkelt läge.

Autentisering och dataomfattning

Alla tre ändpunkter autentiserar med samma API-nyckel:

Authorization: Bearer YOUR_API_KEY

Låthistoriken är isolerad per det user_id som API-nyckeln tillhör. Flera nycklar skapade under samma huvudkonto kan läsa det kontots historik, men inte en annan användares eller ett undersajtkontos låtar.

Historikändpunkterna returnerar bara verkligt genererade låtar. Uteslutna är:

• platshållarposter för generering som börjar med pending:;
• uppladdningar av källjud och poster för förstärkt uppladdning;
• delresultat som separering av sång/ackompanjemang och stems;
• låtar som tillhör andra användare eller undersajtkonton.

1. Fråga efter genereringsstatus

Slår upp aktuell status och slutresultat för ett eller flera låt-ID:n.

Ändpunkt: POST /api/music/query

Fakturering: Gratis.

Headers

Brödtextparametrar

Exempelbegäran

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"
  }'

Exempelsvar

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

Kompatibilitetsnoter

Äldre dokumentation kan visa song_ids som en array. Numera rekommenderas en kommaseparerad sträng, vilket motsvarar hur ändpunkten faktiskt anropas.

song_ids måste innehålla riktiga låt-ID:n. Ett platshållar-ID som börjar med pending: är inte ett slutligt song_id och kan inte användas här; att bara fråga efter platshållar-ID:n kan ge en tom array [].

model, model_version eller plattformens model_name i ett svar kan behålla historiska värden. Nya uppgifter bör använda suno-v6, suno-v6-wild eller suno-v6-mini; från suno-v2 till suno-v5-5 är avvecklade, och att se de namnen i historiken betyder inte att modellen fortfarande kan skickas in.

Så länge en uppgift är pending, submitted eller processing kan audio_url, video_url och cover_url vara tomma — det är normalt för en oavslutad uppgift. Dra inte slutsatsen att något misslyckats bara för att adressen är tom; använd status och fråga igen när statusen är klar. Först när statusen är klar och adresserna fortfarande är tomma bör du kontakta supporten med song_id.

⚠️ Ljudadresser lever i 7 dagar — flytta dina filer i tid

audio_url, video_url (och andra mediaadresser som WAV) som returneras här serveras från plattformens objektlagring och upphör som standard efter 7 dagar: filerna återvinns och den gamla adressen ger 404.

• Flytta filerna till din egen lagring inom dessa 7 dagar; behandla inte adressen som en långvarig länk.
• En utgången adress kräver inte att låten genereras om och debiteras inte igen: anropa den här ändpunkten (POST /api/music/query) igen för att få en färsk giltig adress för låten.

2. Fråga efter kontots låthistorik

Listar de låtar som huvudkontot bakom den aktuella API-nyckeln har skapat. Användbart för en egen låtlista, väljare eller historiksida.

Ändpunkt: GET /api/music/songs

Fakturering: Gratis.

Frågeparametrar

Resultaten sorteras fallande efter created_at och internt post-ID, så sidordningen förblir stabil.

Hitta en inskickning som fick timeout: genereringsändpunkter ger inget mellansvar före mottagandet. Om din klient fick timeout eller anslutningen bröts vid inskickningen kan ordern redan vara mottagen och genereras. Titta på den här ändpunkten (nyaste först): mottagna låtar dyker upp normalt i listan. Skicka bara in igen efter att du bekräftat att den verkligen saknas, så att du inte betalar två gånger. Se "Väntetider och timeout-inställningar" i Översikt över det nya API:t.

Exempelbegäran

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

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Staden i natten",
        "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
      }
    ]
  }
}

Svarfält

Liständpunkten returnerar inte prompts, faktureringsfält, kontoinformation eller råa svar. För prompts och genereringsparametrar, anropa låtens detaljändpunkt.

3. Fråga efter genereringsparametrar

Slår upp den prompt, stil, modell och källåt som plattformen sparade när låten skapades.

Ändpunkt: GET /api/music/songs/:song_id

Fakturering: Gratis.

Endast låtar som tillhör huvudkontot bakom den aktuella API-nyckeln kan läsas. Låtar från andra användare eller undersajtkonton behandlas enhetligt som "låten hittades inte".

Sökvägsparameter

Exempelbegäran

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

Exempelsvar

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Staden i natten",
    "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": "stadsgator efter regn, text om ett återseende",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Staden i natten",
      "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"
      ]
    }
  }
}

Fälten i parameters

Fältet prompt_view (visa prompt, tillagt 2026-09-28)

prompt_view är en normaliserad struktur särskilt för "visa prompt": den ordnar data i fasta avsnitt per genereringstyp, så klienten inte längre behöver avgöra vilket fält som ska visas. Det är ett rent additivt fält — de gamla fälten (parameters, parameter_retention) behåller namn och betydelse, och klienter som inte tolkar det nya fältet påverkas inte alls.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Anpassat läge",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Klockan fyra på morgonen#701f37", "title_base": "Klockan fyra på morgonen", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "guochao-elektronik, djup subbas, retrosynth",
    "style_tags": "guochao-elektronik, djup subbas, retrosynth",
    "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"]
  }
}

Fält som kan förekomma i extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode samt gruppen för ljudeffekter sound_type / sound_bpm / sound_key / sound_loop. Tomma värden returneras aldrig.

Tre visningsregler (följ dem i stället för att gissa):

1. Skilj på var stilen kommer från: vid style_source=suno_derived, visa "stil (härledd av Suno från din beskrivning)" och aldrig "din stil";
2. Interna prompts visas aldrig: röstcover-typer returnerar bara de 【stilkrav】/【coverkrav】 användaren skrev; den fasta stomme vi sätter ihop för modellen visas inte i något fält (historiska data är rensade på samma sätt);
3. Gissa inte saknade parametrar: finns det inte i extended registrerades det inte då — förklara varför med retention.

Noter om parametersparande

parameter_retention skiljer på "ett tomt värde skickades uttryckligen" och "fältet sparades aldrig historiskt":

• core_parameters_available: om uppgiftens huvudpost finns; normalt true vid en giltig detaljfråga;
• extended_parameters_available: om en kopplad utökad musikuppgift hittades;
• sources: vilka datatabeller svaret bygger på;
• unavailable_fields: fält som inte kan återställas tillförlitligt ur historiken; de returnerar null i parameters.

Vanliga historiska låtar sparade oftast prompt, stil, aktuell titel, modell, genereringstyp och källåt, men sparade inte alla avancerade parametrar separat. Plattformen gissar aldrig saknade värden utifrån generation_type.

Vissa utökade musikuppgifter sparade också den ursprungliga prompten, stilen, titeln, modellen samt custom_mode, negative_tags, vocal_gender, style_weight och weirdness_constraint. Även när en utökad post finns kan instrumental, lyrics_mode och wait_audio förbli omöjliga att återskapa.

Titlar kan bytas av användaren i efterhand. När en vanlig historisk uppgift inte sparade en separat ursprunglig titel kan parameters.title vara den aktuella titeln; finns en utökad uppgiftspost prioriteras den ursprungliga genereringstiteln som sparades där.

Hittades inte eller ingen behörighet

Affärsfel använder ett enhetligt svarskuvert. När låten inte finns eller inte tillhör det aktuella kontot:

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

Detta affärsfel returneras för närvarande med HTTP 200, så bedöm resultatet utifrån fältet success. En saknad, ogiltig, utgången eller inaktiverad API-nyckel returnerar HTTP 401.

Säkerhetsnoter

Historik- och detaljändpunkterna returnerar aldrig:

• API-nycklar eller token-ID:n;
• fält för kvot, fakturering eller återbetalning;
• kontoinformation eller råa svar;
• interna nycklar i objektlagringen;
• administratörsfel eller fel i interna resurser.