API truy vấn bài hát và lịch sử

Cập nhật 2026-09-18 · nhóm Suno-API

Trang này gồm ba endpoint truy vấn miễn phí:

Nếu bạn dùng chế độ nhận biên nhận (accept_mode=async) ở endpoint tạo nhạc, thứ bạn có là số biên nhận chứ không phải ID bài hát. Hãy theo dõi tiến độ bằng GET /api/music/requests/{request_id} rồi quay lại các endpoint trên trang này khi đã có song_id thật. Xem "Chế độ nhận biên nhận" trong API tạo nhạc chế độ đơn giản.

Xác thực và phạm vi dữ liệu

Cả ba endpoint dùng chung một khóa API để xác thực:

Authorization: Bearer YOUR_API_KEY

Lịch sử bài hát được tách riêng theo user_id mà khóa API thuộc về. Nhiều khóa API tạo dưới cùng một tài khoản chính có thể đọc lịch sử của tài khoản đó, nhưng không đọc được bài hát của người dùng khác hay tài khoản sub-site khác.

Các endpoint lịch sử chỉ trả về bài hát đã tạo thật. Không bao gồm:

• bản ghi chỗ giữ chỗ của quá trình tạo, bắt đầu bằng pending:;
• bản ghi tải lên âm thanh nguồn và tải lên nâng cao;
• kết quả phụ như tách giọng hát/nhạc đệm và stem;
• bài hát của người dùng khác hoặc tài khoản sub-site khác.

1. Truy vấn trạng thái tạo nhạc

Dùng để tra trạng thái hiện tại và kết quả cuối cùng theo một hoặc nhiều ID bài hát.

Endpoint: POST /api/music/query

Tính phí: Miễn phí.

Headers

Tham số body

Ví dụ request

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

Ví dụ response

[
  {
    "song_id": "clip_id_1",
    "song_title": "Tiêu đề bài hát",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Nội dung lời bài hát",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Ghi chú tương thích

Tài liệu cũ có thể ghi song_ids dưới dạng mảng. Hiện nay nên dùng chuỗi cách nhau bằng dấu phẩy, đúng như cách endpoint thực sự được gọi.

song_ids phải là ID bài hát thật. ID chỗ giữ chỗ bắt đầu bằng pending: không phải song_id cuối cùng và không dùng được ở đây; chỉ truy vấn ID chỗ giữ chỗ có thể trả về mảng rỗng [].

model, model_version hoặc model_name của nền tảng trong response có thể giữ giá trị lịch sử. Tác vụ mới nên dùng suno-v6, suno-v6-wild hoặc suno-v6-mini; từ suno-v2 đến suno-v5-5 đã ngừng hỗ trợ, và việc thấy những tên này trong lịch sử không có nghĩa là vẫn gửi được mô hình đó.

Khi tác vụ đang ở trạng thái pending, submitted hoặc processing, audio_url, video_url và cover_url có thể rỗng — đó là bình thường với tác vụ chưa xong. Đừng chỉ dựa vào địa chỉ rỗng để kết luận thất bại; hãy dựa vào status và truy vấn lại khi trạng thái đã hoàn tất. Chỉ khi trạng thái hoàn tất mà địa chỉ vẫn rỗng mới nên liên hệ hỗ trợ kèm song_id.

⚠️ Địa chỉ âm thanh chỉ sống 7 ngày — hãy chuyển file kịp thời

audio_url, video_url (và các địa chỉ media khác như WAV) do endpoint này trả về được phục vụ từ lưu trữ đối tượng của nền tảng và mặc định hết hạn sau 7 ngày: file bị thu hồi và địa chỉ cũ trả 404.

• Trong 7 ngày đó, hãy chuyển file sang kho của bạn; đừng coi địa chỉ này là link dài hạn.
• Địa chỉ hết hạn không cần tạo lại bài hát và không bị tính phí lần nữa: gọi lại endpoint này (POST /api/music/query) để nhận địa chỉ mới còn hiệu lực của bài hát đó.

2. Truy vấn lịch sử bài hát của tài khoản

Liệt kê các bài hát do tài khoản chính của khóa API hiện tại tạo ra. Phù hợp để dựng danh sách bài hát, bộ chọn hoặc trang lịch sử của riêng bạn.

Endpoint: GET /api/music/songs

Tính phí: Miễn phí.

Tham số query

Kết quả sắp xếp giảm dần theo created_at và ID bản ghi nội bộ, nên thứ tự phân trang luôn ổn định.

Cách tìm lại một lượt gửi bị timeout: các endpoint tạo nhạc không trả về phản hồi trung gian trước khi tiếp nhận. Nếu client timeout hoặc mất kết nối lúc gửi, đơn đó có thể đã được tiếp nhận và đang tạo. Hãy xem endpoint này (mới nhất trước): bài hát đã được tiếp nhận sẽ xuất hiện bình thường trong danh sách. Chỉ gửi lại sau khi đã xác nhận thật sự không có, để tránh trả tiền hai lần. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Ví dụ request

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

Ví dụ response

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Thành phố trong đêm",
        "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
      }
    ]
  }
}

Các trường trả về

Endpoint danh sách không trả về prompt, trường tính phí, thông tin tài khoản hay phản hồi thô. Khi cần prompt và tham số tạo nhạc, hãy gọi endpoint chi tiết bài hát.

3. Truy vấn tham số tạo nhạc

Tra prompt, phong cách, mô hình và bài hát nguồn mà nền tảng đã lưu khi tạo bài hát đó.

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

Tính phí: Miễn phí.

Chỉ đọc được bài hát thuộc tài khoản chính của khóa API hiện tại. Bài hát của người dùng khác hoặc tài khoản sub-site khác đều được xử lý như "không tìm thấy bài hát".

Tham số đường dẫn

Ví dụ request

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

Ví dụ response

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Thành phố trong đêm",
    "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": "phố phường sau mưa, lời bài hát về cuộc gặp lại",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Thành phố trong đêm",
      "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"
      ]
    }
  }
}

Các trường parameters

Trường prompt_view (xem prompt, thêm ngày 2026-09-28)

prompt_view là cấu trúc đã chuẩn hóa dành riêng cho "xem prompt": nó tổ chức dữ liệu thành các phần cố định theo kiểu tạo nhạc, để client không phải tự quyết định hiển thị trường nào. Đây là trường thuần bổ sung — các trường cũ (parameters, parameter_retention) giữ nguyên tên và ý nghĩa, và client không phân tích trường mới hoàn toàn không bị ảnh hưởng.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Chế độ chuyên nghiệp",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Bốn giờ sáng#701f37", "title_base": "Bốn giờ sáng", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "……", "user_text_kind": "lyrics",
    "user_style": "điện tử guochao, sub bass sâu, synth retro",
    "style_tags": "điện tử guochao, sub bass sâu, 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"]
  }
}

Các trường có thể xuất hiện trong extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, cùng nhóm hiệu ứng âm thanh sound_type / sound_bpm / sound_key / sound_loop. Giá trị rỗng luôn không được trả về.

Ba quy tắc hiển thị (hãy làm theo, đừng tự suy đoán):

1. Phân biệt nguồn phong cách: khi style_source=suno_derived, hiển thị là "phong cách (Suno suy ra từ mô tả của bạn)", đừng viết "phong cách bạn nhập";
2. Prompt nội bộ không xuất hiện: kiểu cover bằng giọng chỉ trả về 【yêu cầu phong cách】/【yêu cầu cover】 do người dùng nhập; đoạn cấu trúc cố định chúng tôi ghép cho mô hình không xuất hiện ở bất kỳ trường nào (dữ liệu lịch sử cũng đã được làm sạch tương tự);
3. Không đoán tham số không được lưu: nếu không có trong extended thì lúc đó không ghi lại — dùng retention để giải thích cho người dùng.

Ghi chú về lưu tham số

parameter_retention dùng để phân biệt "truyền rõ ràng giá trị rỗng" với "trường chưa từng được lưu trong lịch sử":

• core_parameters_available: bản ghi tác vụ chính có tồn tại không; chi tiết hợp lệ thường là true;
• extended_parameters_available: có tìm thấy bản ghi tác vụ nhạc mở rộng liên quan không;
• sources: response này lấy từ những bảng dữ liệu nào;
• unavailable_fields: các trường không thể khôi phục tin cậy từ dữ liệu lịch sử; chúng trả null trong parameters.

Bài hát lịch sử thông thường thường lưu prompt, phong cách, tiêu đề hiện tại, mô hình, kiểu tạo nhạc và bài hát nguồn, nhưng không lưu riêng toàn bộ tham số nâng cao. Nền tảng không bao giờ đoán giá trị thiếu từ generation_type.

Một số tác vụ nhạc mở rộng còn lưu prompt gốc, phong cách, tiêu đề, mô hình, cùng custom_mode, negative_tags, vocal_gender, style_weight và weirdness_constraint. Dù có bản ghi mở rộng, instrumental, lyrics_mode và wait_audio vẫn có thể không khôi phục được.

Tiêu đề bài hát có thể bị người dùng đổi sau đó. Khi tác vụ lịch sử thông thường không lưu riêng tiêu đề gốc, parameters.title có thể là tiêu đề hiện tại; khi có bản ghi tác vụ mở rộng, hệ thống ưu tiên tiêu đề tạo nhạc gốc được lưu ở đó.

Không tồn tại hoặc không có quyền

Lỗi nghiệp vụ dùng phong bì phản hồi thống nhất. Khi bài hát không tồn tại hoặc không thuộc tài khoản hiện tại:

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

Lỗi nghiệp vụ này hiện trả về HTTP 200, nên hãy đánh giá kết quả qua trường success. Khóa API thiếu, không hợp lệ, hết hạn hoặc bị vô hiệu hóa sẽ trả về HTTP 401.

Ghi chú bảo mật

Các endpoint lịch sử và chi tiết không bao giờ trả về:

• khóa API hay Token ID;
• trường hạn mức, tính phí hay hoàn tiền;
• thông tin tài khoản và phản hồi thô;
• khóa nội bộ của lưu trữ đối tượng;
• lỗi quản trị và lỗi tài nguyên nội bộ.