API pertanyaan lagu dan sejarah

Dikemas kini 2026-09-18 · pasukan Suno-API

Halaman ini merangkumi tiga endpoint pertanyaan percuma:

Jika anda menggunakan mod resit penerimaan (accept_mode=async) pada endpoint penjanaan, yang anda pegang ialah nombor resit, bukan ID lagu. Jejaki kemajuan dengan GET /api/music/requests/{request_id} dan kembali ke endpoint di halaman ini sebaik sahaja mendapat song_id sebenar. Lihat "Mod resit penerimaan" dalam API penjanaan mod mudah.

Pengesahan dan skop data

Ketiga-tiga endpoint menggunakan kunci API yang sama:

Authorization: Bearer YOUR_API_KEY

Sejarah lagu diasingkan mengikut user_id pemilik kunci API. Beberapa kunci yang dicipta di bawah akaun utama yang sama boleh membaca sejarah akaun itu, tetapi tidak boleh membaca lagu pengguna lain atau akaun subsitus lain.

Endpoint sejarah hanya mengembalikan lagu yang benar-benar dijana. Tidak termasuk:

• rekod pemegang tempat penjanaan yang bermula dengan pending:;
• muat naik audio sumber dan rekod muat naik diperkukuh;
• hasil sampingan seperti pemisahan vokal/muzik dan stem;
• lagu milik pengguna lain atau akaun subsitus lain.

1. Pertanyaan status penjanaan

Mencari status semasa dan hasil akhir bagi satu atau beberapa ID lagu.

Endpoint: POST /api/music/query

Pengebilan: Percuma.

Headers

Parameter body

Contoh permintaan

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

Contoh respons

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

Nota keserasian

Dokumentasi lama mungkin menunjukkan song_ids sebagai tatasusunan. Kini disyorkan rentetan dipisahkan koma, sejajar dengan cara endpoint ini sebenarnya dipanggil.

song_ids mesti mengandungi ID lagu sebenar. ID pemegang tempat yang bermula dengan pending: bukan song_id akhir dan tidak boleh digunakan di sini; membuat pertanyaan hanya dengan ID pemegang tempat boleh mengembalikan tatasusunan kosong [].

model, model_version atau model_name platform dalam respons mungkin kekal nilai sejarah. Tugasan baharu sebaiknya menggunakan suno-v6, suno-v6-wild atau suno-v6-mini; dari suno-v2 hingga suno-v5-5 telah ditarik, dan melihat nama tersebut dalam sejarah bukan bermakna model itu masih boleh dihantar.

Selagi tugasan berada dalam keadaan pending, submitted atau processing, audio_url, video_url dan cover_url mungkin kosong — itu normal bagi tugasan yang belum selesai. Jangan simpulkan kegagalan hanya kerana alamat kosong; gunakan status dan pertanyaan semula apabila status selesai. Hanya apabila status selesai tetapi alamat masih kosong, anda digalakkan menghubungi sokongan dengan menyertakan song_id.

⚠️ Alamat audio hanya bertahan 7 hari — pindahkan fail anda tepat pada masanya

audio_url, video_url (dan alamat media lain seperti WAV) yang dikembalikan di sini disajikan daripada storan objek platform dan luput selepas 7 hari secara lalai: fail dikitar semula dan alamat lama mengembalikan 404.

• Dalam tempoh 7 hari itu, pindahkan fail ke storan anda sendiri; jangan anggap alamat ini sebagai pautan jangka panjang.
• Alamat yang telah luput tidak memerlukan penjanaan semula lagu dan tidak dicaj semula: panggil semula endpoint ini (POST /api/music/query) untuk mendapatkan alamat baharu yang masih sah bagi lagu tersebut.

2. Pertanyaan sejarah lagu akaun

Menyenaraikan lagu yang dijana oleh akaun utama pemilik kunci API semasa. Sesuai untuk membina senarai lagu, pemilih atau halaman sejarah anda sendiri.

Endpoint: GET /api/music/songs

Pengebilan: Percuma.

Parameter pertanyaan

Hasil disusun menurun mengikut created_at dan ID rekod dalaman, jadi susunan halaman kekal stabil.

Cara menemui penghantaran yang tamat masa: endpoint penjanaan tidak memberi respons pertengahan sebelum penerimaan. Jika klien anda tamat masa atau sambungan terputus semasa menghantar, pesanan itu mungkin sudah diterima dan sedang dijana. Lihat endpoint ini (terbaharu dahulu): lagu yang telah diterima akan muncul seperti biasa dalam senarai. Hantar semula hanya selepas anda mengesahkan ia benar-benar tiada, supaya tidak membayar dua kali. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Contoh permintaan

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

Contoh respons

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

Medan respons

Endpoint senarai tidak mengembalikan prompt, medan pengebilan, maklumat akaun atau respons mentah. Untuk prompt dan parameter penjanaan, panggil endpoint butiran lagu.

3. Pertanyaan parameter penjanaan

Mencari prompt, gaya, model dan lagu sumber yang disimpan platform semasa lagu dijana.

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

Pengebilan: Percuma.

Hanya lagu milik akaun utama pemilik kunci API semasa boleh dibaca. Lagu pengguna lain atau akaun subsitus lain sentiasa diperlakukan sebagai "lagu tidak ditemui".

Parameter path

Contoh permintaan

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

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Bandar pada malam hari",
    "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": "jalan bandar selepas hujan, lirik tentang pertemuan semula",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Bandar pada malam hari",
      "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"
      ]
    }
  }
}

Medan parameters

Medan prompt_view (lihat prompt, ditambah pada 2026-09-28)

prompt_view ialah struktur ternormalisasi khusus untuk "lihat prompt": ia menyusun data kepada bahagian tetap mengikut jenis penjanaan, jadi klien tidak perlu lagi menentukan medan mana untuk dipaparkan. Ia medan tambahan semata-mata — medan lama (parameters, parameter_retention) kekal nama dan makna, dan klien yang tidak menghurai medan baharu tidak terjejas sama sekali.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Mod tersuai",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Pukul empat pagi#701f37", "title_base": "Pukul empat pagi", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "elektronik guochao, sub bass dalam, synth retro",
    "style_tags": "elektronik guochao, sub bass dalam, synth retro",
    "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"]
  }
}

Medan yang mungkin muncul dalam extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, serta kumpulan kesan bunyi sound_type / sound_bpm / sound_key / sound_loop. Nilai kosong tidak pernah dikembalikan.

Tiga peraturan paparan (ikuti, jangan teka sendiri):

1. Bezakan asal gaya: apabila style_source=suno_derived, paparkan "gaya (disimpulkan Suno daripada penerangan anda)", jangan tulis "gaya yang anda isi";
2. Prompt dalaman tidak pernah muncul: jenis cover dengan suara hanya mengembalikan 【keperluan gaya】/【keperluan cover】 yang ditaip pengguna; rangka tetap yang kami susun untuk model tidak muncul dalam mana-mana medan (data sejarah juga telah dibersihkan);
3. Jangan teka parameter yang tidak disimpan: jika tiada dalam extended, ia tidak direkodkan ketika itu — jelaskan sebabnya melalui retention.

Nota penyimpanan parameter

parameter_retention memisahkan "nilai kosong dihantar secara jelas" daripada "medan tidak pernah disimpan secara sejarah":

• core_parameters_available: sama ada rekod tugasan utama wujud; biasanya true pada butiran yang sah;
• extended_parameters_available: sama ada rekod tugasan muzik lanjutan berkaitan ditemui;
• sources: daripada jadual data mana respons ini diambil;
• unavailable_fields: medan yang tidak boleh dipulihkan secara boleh dipercayai daripada sejarah; medan ini mengembalikan null dalam parameters.

Lagu sejarah biasa biasanya menyimpan prompt, gaya, tajuk semasa, model, jenis penjanaan dan lagu sumber, tetapi tidak menyimpan semua parameter lanjutan secara berasingan. Platform tidak pernah meneka nilai yang hilang daripada generation_type.

Sebahagian tugasan muzik lanjutan turut menyimpan prompt asal, gaya, tajuk, model, serta custom_mode, negative_tags, vocal_gender, style_weight dan weirdness_constraint. Walaupun rekod lanjutan wujud, instrumental, lyrics_mode dan wait_audio mungkin kekal tidak dapat dipulihkan.

Tajuk lagu boleh dinamakan semula oleh pengguna kemudian. Apabila tugasan sejarah biasa tidak menyimpan tajuk asal yang berasingan, parameters.title mungkin tajuk semasa; apabila rekod tugasan lanjutan wujud, tajuk penjanaan asal yang disimpan di sana diutamakan.

Tidak ditemui atau tiada kebenaran

Ralat perniagaan menggunakan sampul respons seragam. Apabila lagu tidak wujud atau bukan milik akaun semasa:

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

Ralat perniagaan ini kini dikembalikan dengan HTTP 200, jadi nilai hasil melalui medan success. Kunci API yang hilang, tidak sah, luput atau dilumpuhkan mengembalikan HTTP 401.

Nota keselamatan

Endpoint sejarah dan butiran tidak pernah mengembalikan:

• kunci API atau Token ID;
• medan kuota, pengebilan atau bayaran balik;
• maklumat akaun atau respons mentah;
• kunci dalaman storan objek;
• ralat pentadbir atau ralat sumber dalaman.