Tài liệu API XuniBOX

API 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.

Bắt đầu nhanh Xem endpoints Tra cứu yêu cầu

Danh sách endpoint

Tất cả endpoint dưới đây nằm dưới tiền tố https://xunibox.vn/api/public. Mọi endpoint dữ liệu đều cần header X-API-Key; chỉ nhóm hạ tầng (health, readyz, status, metrics, openapi, cover) là mở — xem chi tiết ở trang Xác thực.

Method & path	Trả về	Cần key
GET /healthz	Trạng thái API, phiên bản, thời gian phản hồi và kết nối DB.	Không
GET /readyz	Readiness: hệ thống đã sẵn sàng nhận traffic chưa, kèm timestamp, từng check và lý do lỗi.	Không
GET /health	Bản tổng hợp health + thông tin endpoint và chính sách.	Không
GET /status	Chỉ số vận hành (quy mô kho nhạc, DB) + cấu hình hạn mức và chính sách hiện hành.	Không
GET /metrics	Số liệu định dạng Prometheus (text/plain) để hệ thống giám sát scrape.	Không
GET /tracks	Danh sách bài hát có lọc, tìm kiếm, sắp xếp, phân trang.	Có
GET /tracks/:id	Một bài hát. Không tăng play_count.	Có
GET /tracks/by-slug/:slug	Một bài hát theo slug thân thiện (phần cuối URL xunibox.vn/track/...).	Có
GET /tracks/by-ids	Tối đa 50 bài trong một lượt, giữ thứ tự ID đầu vào.	Có
GET /tracks/:id/audio-url	Link nghe thử đã ký còn hạn cho một bài — gọi ngay trước khi phát.	Có
GET /tracks/:id/license	Thông tin bản quyền của một bài: license_code, phạm vi dùng, ISRC, ngày phát hành.	Có
GET /tracks/:id/similar	Danh sách bài tương tự kèm score và reason.	Có
GET /tracks/:id/waveform	Mảng peaks của bài (và của đoạn preview) kèm phân tích bpm/key/energy/loudness.	Có
GET /tracks/waveforms	Lấy peaks hàng loạt cho tối đa 50 bài.	Có
GET /search	Tìm kiếm thông minh có chấm điểm liên quan.	Có
GET /search/suggest	Gợi ý autocomplete cho ô tìm kiếm (bài hát, nghệ sĩ, thể loại).	Có
GET /trending	Bảng xếp hạng theo lượt phát gần đây.	Có
GET /licenses	Danh mục các loại giấy phép XuniBOX đang áp dụng.	Có
GET /genres	Danh sách thể loại đang được dùng, A→Z.	Có
GET /artists	Danh sách nghệ sĩ kèm số bài nhạc.	Có
GET /artists/:id/tracks	Thông tin nghệ sĩ + danh sách bài của họ.	Có
GET /me/usage	Báo cáo mức dùng của chính API key đang gọi.	Có
GET · POST · DELETE /webhooks	Quản lý webhook của đối tác (tối đa 5 mỗi đối tác).	Có
GET /tracks/:id/watermarked	File audio preview có nhúng watermark ẩn để truy vết.	Có

GET/healthz

Kiểm tra nhanh khi tích hợp. Không cần API key, không tốn hạn mức rate limit.

GET/readyz

Readiness probe: trả 200 khi sẵn sàng nhận traffic, 503 kèm reason khi chưa. Hỗ trợ cả HEAD, không cần API key.

GET/metrics

Số liệu theo chuẩn Prometheus text exposition 0.0.4: xunibox_up, xunibox_database_up, xunibox_database_response_seconds, xunibox_tracks_total, xunibox_artists_total, xunibox_track_plays_total, xunibox_rate_limit_requests_per_minute, xunibox_scrape_duration_seconds. Không cần API key, không tốn hạn mức, không cache.

GET/status

Bản tin vận hành chi tiết: trạng thái hệ thống, số bài nhạc/nghệ sĩ, hạn mức mặc định của API key, chính sách cache, phân trang, CORS và danh sách phiên bản đặc tả. Không cần API key.

GET/tracks

Danh sách bài hát, hỗ trợ tìm kiếm, lọc, sắp xếp và phân trang. Bắt buộc header X-API-Key.

titlestringTìm một phần tên bài hát, tối đa 160 ký tự.

genrestringTìm một phần thể loại, tối đa 80 ký tự.

artiststringTìm một phần tên nghệ sĩ, tối đa 120 ký tự.

artist_iduuidLọc chính xác theo ID nghệ sĩ lấy từ /artists.

slugstringTra cứu chính xác theo slug bài hát; trả tối đa 1 kết quả và bỏ qua bộ lọc khác.

qstringTìm đồng thời trong tên bài hát, nghệ sĩ và thể loại, tối đa 100 ký tự.

bpm_min / bpm_maxnumberKhoảng nhịp độ, từ 0 đến 300.

energy_min / energy_maxnumberKhoảng độ sôi động, từ 0 đến 1.

keystringTông nhạc, ví dụ A minor hoặc F# major.

licenseenumxunibox-standard, xunibox-commercial hoặc xunibox-restricted.

commercialbooleantrue để chỉ lấy bài được dùng thương mại.

explicitbooleanfalse để loại bài có nội dung nhạy cảm.

sortenumnewest (mặc định), oldest, popular, most_liked, title_asc, title_desc.

pageintegerTrang cần lấy, từ 1 đến 5000, mặc định 1.

limitintegerSố bản ghi mỗi trang, mặc định 20, tối đa 100.

GET/tracks/:id

Một bài hát theo UUID. 400 nếu ID sai định dạng, 404 nếu không tồn tại.

GET/tracks/by-slug/:slug

Một bài hát theo slug (chữ thường không dấu, số và dấu gạch ngang) — chính là phần cuối URL https://xunibox.vn/track/ten-bai-hat. Cấu trúc phản hồi giống /tracks/:id và không tăng play_count. 400 nếu slug sai định dạng, 404 nếu không tồn tại. Có thể dùng thay thế bằng GET /tracks?slug=ten-bai-hat nếu muốn giữ cấu trúc phân trang.

GET/tracks/:id/audio-url

Làm mới link nghe thử đã ký cho một bài. Trả audio_url, cover_url, preview_duration_seconds, media_expires_in (giây) và expires_at (ISO 8601). Luôn Cache-Control: no-store. 400 nếu ID sai định dạng, 404 nếu bài không tồn tại hoặc chưa có đoạn nghe thử.

expires_inintegerThời hạn link tính bằng giây, từ 60 đến 86400, mặc định 3600.

downloadbooleanĐặt true để link trả về kèm Content-Disposition tải xuống.

GET/tracks/:id/license

Điều kiện sử dụng của một bài: license_code, attribution_required, commercial_use_allowed, territory, is_explicit, isrc, release_date. 404 nếu bài không tồn tại.

GET/tracks/:id/similar

Gợi ý bài tương tự dựa trên nghệ sĩ, thể loại và đặc trưng âm thanh. Mỗi kết quả kèm score (0–1) và reason.

limitintegerSố bài trả về, từ 1 đến 50, mặc định 10.

GET/tracks/:id/waveform

Peaks của bản đầy đủ và của đoạn preview, kèm khối analysis gồm bpm, musical_key, energy và loudness_db.

pointsintegerSố cột sóng âm mong muốn, từ 16 đến 512, mặc định 120.

GET/tracks/waveforms

Lấy peaks hàng loạt, dùng khi render danh sách nhiều bài cùng lúc.

idsstringDanh sách UUID cách nhau bởi dấu phẩy, tối đa 50.

pointsintegerSố cột sóng âm mỗi bài, từ 16 đến 512, mặc định 120.

GET/tracks/by-ids

Lấy nhiều bài cùng lúc, dùng khi khôi phục playlist đã lưu.

idsstringDanh sách UUID cách nhau bởi dấu phẩy, tối đa 50. ID trùng được gộp, ID không tồn tại bị bỏ qua.

GET/search

Tìm kiếm thông minh (có chuẩn hoá tiếng Việt không dấu) kèm điểm liên quan score.

qstringTừ khoá tìm kiếm, tối đa 100 ký tự.

genrestringGiới hạn theo thể loại, tối đa 80 ký tự.

artist_iduuidGiới hạn theo nghệ sĩ.

sortenumrelevance (mặc định), newest, oldest, popular, title_asc, title_desc.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố kết quả mỗi trang, mặc định 20, tối đa 100.

GET/search/suggest

Gợi ý autocomplete trong lúc người dùng gõ. Mỗi mục có kind (track | artist | genre), id, label, sublabel và score.

qstringBắt buộc. Từ khoá đang gõ, tối đa 100 ký tự.

limitintegerSố gợi ý, từ 1 đến 20, mặc định 8.

GET/trending

Bảng xếp hạng theo lượt phát trong N ngày gần nhất, kèm recent_plays và score.

daysintegerSố ngày tính xếp hạng, từ 1 đến 90, mặc định 7.

limitintegerSố bài trả về, từ 1 đến 50, mặc định 20.

GET/licenses

Danh mục giấy phép: mã, tên, mô tả, có bắt buộc ghi công không, có cho dùng thương mại không và phạm vi lãnh thổ.

GET/genres

Các thể loại đang thực sự có bài nhạc, sắp xếp A→Z.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố thể loại mỗi trang, mặc định 20, tối đa 100.

GET/artists

Nghệ sĩ kèm tiểu sử, ảnh đại diện và tổng số bài nhạc.

qstringTìm theo tên nghệ sĩ, tối đa 100 ký tự.

sortenumname_asc (mặc định), name_desc, newest, oldest.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố nghệ sĩ mỗi trang, mặc định 20, tối đa 100.

GET/artists/:id/tracks

Thông tin nghệ sĩ và danh sách bài nhạc của họ. 404 nếu nghệ sĩ không tồn tại.

sortenumnewest (mặc định), oldest, popular, title_asc, title_desc.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố bài mỗi trang, mặc định 20, tối đa 100.

GET/me/usage

Cần X-API-Key. Trạng thái key, hạn mức phút hiện tại và lịch sử dùng theo ngày. Luôn Cache-Control: no-store. 401 nếu thiếu key, 403 nếu key sai.

daysintegerSố ngày lịch sử, từ 1 đến 90, mặc định 30.

GET/webhooks

Cần X-API-Key. Danh sách webhook của đối tác kèm meta.supported_events và signature_header. Xem hướng dẫn đầy đủ ở trang Webhook.

GET/tracks/:id/watermarked

Cần X-API-Key. Trả file audio preview đã nhúng watermark ẩn để truy vết nguồn phát tán. Có hạn mức riêng theo key (phút và ngày) qua các header X-Watermark-RateLimit-*, kèm X-Watermark-Code và X-Watermark-Layers. Luôn Cache-Control: no-store; 401 nếu thiếu key, 403 nếu key sai, 429 khi vượt hạn mức hoặc bị tạm khoá IP.

Quy ước chung Hạn mức & RateLimit

Sẵn sàng tích hợp?

Gửi thông tin sản phẩm để admin XuniBOX xét duyệt và cấp API key.

Xin quyền tích hợp