Developer PlatformAPI chỉ đọc để lấy danh sách nhạc, nghệ sĩ và thể loại từ kho XuniBOX. Mỗi chủ đề dưới đây là một trang riêng, có đường dẫn riêng để bạn chia sẻ cho đội kỹ thuật.
Ngoài bộ lọc cơ bản của /tracks, XuniBOX có bốn endpoint chuyên cho trải nghiệm khám phá nhạc: tìm kiếm bỏ dấu và chịu sai chính tả, autocomplete tức thời, gợi ý bài tương tự và bảng xếp hạng theo cửa sổ ngày.
/searchTìm kiếm thông minh, xếp theo độ liên quan.
qstringTừ khoá, tối đa 100 ký tự. Bỏ dấu tự động: 'hoa nang' khớp 'Hoà Nắng'.genrestringGiới hạn trong một thể loại.artist_iduuidGiới hạn trong một nghệ sĩ.sortenumrelevance (mặc định), newest, popular, title_asc, title_desc.pageintegerTrang cần lấy, mặc định 1.limitintegerSố bản ghi mỗi trang, mặc định 20, tối đa 100./search/suggestGợi ý tức thời cho ô tìm kiếm, gồm cả bài hát, nghệ sĩ và thể loại.
qstringChuỗi đang gõ, từ 1 ký tự.limitintegerSố gợi ý trả về, mặc định 8, tối đa 20./tracks/:id/similarBài tương tự dựa trên nghệ sĩ, thể loại và tên bài.
limitintegerSố bài gợi ý, mặc định 10, tối đa 50./trendingBảng xếp hạng theo lượt phát gần đây.
daysintegerCửa sổ tính điểm, 1 đến 90 ngày, mặc định 7.limitintegerSố bài trả về, mặc định 20, tối đa 100.Chuỗi tìm kiếm được chuẩn hoá trước khi so khớp: bỏ dấu tiếng Việt, hạ chữ thường, gộp khoảng trắng. Nhờ vậy người dùng gõ nhanh không dấu vẫn ra kết quả. Mỗi bản ghi kèm score từ 0 đến 1; kết quả dưới 0.2 bị loại để danh sách không bị nhiễu.
curl --request GET \
--url 'https://xunibox.vn/api/public/search?q=hoa%20nang&sort=relevance&limit=2' \
--header 'X-API-Key: xnb_live_your_key'HTTP/1.1 200 OK
X-Total-Count: 7
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Hoà Nắng",
"artist": "Hoàng Nam",
"genre": "Indie",
"score": 1,
"audio_url": "https://...signed-url...",
"media_expires_in": 3600
},
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"title": "Nắng Hạ",
"artist": "Minh Anh",
"genre": "Pop",
"score": 0.42,
"audio_url": "https://...signed-url...",
"media_expires_in": 3600
}
],
"meta": { "total": 7, "page": 1, "limit": 2 },
"query": { "q": "hoa nang", "genre": null, "artist_id": null, "sort": "relevance" }
}
// Gõ "hoa nang" vẫn khớp "Hoà Nắng": bỏ dấu và chịu được sai chính tả nhẹ.
// score từ 0 đến 1 — 1 là khớp đầu chuỗi, dưới 0.2 sẽ bị loại.| Mức score | Ý nghĩa | Gợi ý hiển thị |
|---|---|---|
| 1.0 | Khớp ngay từ đầu tên bài hoặc tên nghệ sĩ. | Đặt lên đầu, có thể gắn nhãn 'Kết quả khớp nhất'. |
| 0.5 – 0.99 | Khớp một phần hoặc khớp ở giữa chuỗi. | Hiển thị bình thường. |
| 0.2 – 0.49 | Khớp mờ, sai chính tả nhẹ hoặc trùng thể loại. | Đưa xuống mục 'Có thể bạn muốn tìm'. |
| < 0.2 | Bị hệ thống loại, không trả về. | Nếu data rỗng, hãy hiện gợi ý từ /trending. |
Phản hồi rất nhẹ, chỉ gồm nhãn để render dropdown. Trường kind nhận ba giá trị: track, artist, genre — dùng để chọn icon và quyết định hành động khi người dùng bấm chọn.
curl --request GET \
--url 'https://xunibox.vn/api/public/search/suggest?q=nha&limit=5' \
--header 'X-API-Key: xnb_live_your_key'HTTP/1.1 200 OK
{
"data": [
{ "kind": "track", "id": "550e8400-...", "label": "Nhà Là Nơi", "sublabel": "Hoàng Nam", "score": 1 },
{ "kind": "artist", "id": "b3f1c2d4-...", "label": "Nhật Minh", "sublabel": null, "score": 1 },
{ "kind": "genre", "id": null, "label": "Nhạc Trẻ", "sublabel": null, "score": 0.86 }
],
"meta": { "q": "nha", "total": 3 }
}
// Dùng cho ô tìm kiếm: debounce khoảng 150ms rồi gọi mỗi lần người dùng gõ.AbortController. Không debounce nghĩa là mỗi phím gõ tốn một request — một ô tìm kiếm có thể ăn hết hạn mức của cả hệ thống trong vài giây.Dùng ở màn hình chi tiết bài hát hoặc ngay sau khi người dùng chọn nhạc cho video. Trường reason cho biết vì sao bài được gợi ý — hiển thị nó lên giao diện giúp người dùng tin tưởng kết quả hơn.
curl --request GET \
--url 'https://xunibox.vn/api/public/tracks/550e8400-e29b-41d4-a716-446655440000/similar?limit=3' \
--header 'X-API-Key: xnb_live_your_key'HTTP/1.1 200 OK
{
"data": [
{ "id": "7c9e6679-...", "title": "Đêm Thành Phố", "reason": "same_artist", "score": 0.62, "audio_url": "https://...signed-url..." },
{ "id": "a1b2c3d4-...", "title": "Mưa Tháng Sáu", "reason": "same_genre", "score": 0.38, "audio_url": "https://...signed-url..." }
],
"meta": { "seed_track_id": "550e8400-e29b-41d4-a716-446655440000", "total": 2, "limit": 3 }
}
// reason: same_artist | same_genre | similar_title — tiện hiển thị lý do gợi ý.| reason | Cách sinh gợi ý | Nhãn tiếng Việt gợi ý |
|---|---|---|
| same_artist | Cùng nghệ sĩ với bài gốc. | Cùng nghệ sĩ |
| same_genre | Cùng thể loại, ưu tiên bài có lượt phát cao. | Cùng thể loại |
| similar_title | Tên bài gần giống sau khi chuẩn hoá không dấu. | Có thể bạn thích |
Điểm được tính từ lượt phát thật trong cửa sổ days ngày, cộng thêm một khoản ưu tiên nhẹ cho bài mới phát hành để kho nhạc không bị đóng băng ở vài bài cũ. Mỗi bản ghi có sẵn rank nên bạn không cần tự đánh số.
curl --request GET \
--url 'https://xunibox.vn/api/public/trending?days=7&limit=3' \
--header 'X-API-Key: xnb_live_your_key'HTTP/1.1 200 OK
{
"data": [
{ "rank": 1, "id": "550e8400-...", "title": "Hoà Nắng", "recent_plays": 1820, "score": 1824.5 },
{ "rank": 2, "id": "7c9e6679-...", "title": "Đêm Thành Phố", "recent_plays": 1290, "score": 1290 }
],
"meta": { "window_days": 7, "total": 2, "limit": 3 }
}
// days từ 1 đến 90 (mặc định 7). Bài mới phát hành được cộng điểm ưu tiên nhẹ./trending?days=7, người dùng gõ thì gọi /search/suggest, bấm Enter thì gọi /search, chọn xong một bài thì gợi ý tiếp bằng /tracks/:id/similar.Gửi thông tin sản phẩm để admin XuniBOX xét duyệt và cấp API key.