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

Xác thực bằng API key

Cập nhật mới nhất: mọi endpoint dữ liệu đều bắt buộc gửi header X-API-Key. Gọi /tracks, /search, /artists, /trending… mà thiếu key sẽ nhận 401. Chỉ nhóm endpoint hạ tầng (health, status, metrics, đặc tả OpenAPI) là mở.

Endpoint	Cần X-API-Key?	Ghi chú
GET /tracks, /tracks/:id, /tracks/by-ids, /tracks/:id/audio-url, /tracks/:id/license, /tracks/:id/similar, /tracks/:id/waveform, /tracks/waveforms	Có	Đọc metadata và link nghe thử đã ký.
GET /search, /search/suggest, /trending, /licenses, /genres, /artists, /artists/:id/tracks	Có	Tìm kiếm, gợi ý, bảng xếp hạng và dữ liệu tra cứu.
GET /api/public (chỉ mục), /health, /healthz, /readyz, /status, /metrics, /openapi.json, /openapi.v1.json, /tracks/:id/cover	Không	Hạ tầng, ảnh bìa và đặc tả — vẫn có hạn mức theo IP.
GET /me/usage	Có	Báo cáo mức dùng của chính key đó.
GET / POST / DELETE /webhooks	Có	Quản lý webhook của đối tác.
GET /tracks/:id/watermarked	Có	Trả file audio có watermark ẩn, có hạn mức riêng theo key.

Khi cần key, gửi trong header X-API-Key. Không đặt trong query string, không nhúng vào bundle frontend, không commit vào repo. Key có tiền tố xnb_live_ và chỉ hiện đầy đủ đúng một lần lúc admin cấp.

HTTP header

GET /api/public/me/usage HTTP/1.1
Host: xunibox.vn
Accept: application/json
X-API-Key: xnb_live_your_key

Gọi từ backend, đừng gọi từ trình duyệt. API bật CORS * nên trình duyệt gọi được, nhưng nếu request có key thì key sẽ nằm trong tab Network của mọi người dùng. Cách đúng: frontend của bạn gọi backend của bạn, backend gắn key rồi gọi XuniBOX.

Giới hạn tần suất

Các endpoint công khai hiện chưa tính hạn mức — nhưng hãy cache phía bạn và tránh poll liên tục, vì XuniBOX có thể bật hạn mức cho nhóm này về sau. Các endpoint cần key có hạn mức request/phút do admin đặt (mặc định 60); khi chạm trần bạn nhận 429 kèm Retry-After tính bằng giây.

Header	Ý nghĩa
X-RateLimit-Limit	Số request tối đa trong cửa sổ hiện tại.
X-RateLimit-Remaining	Số request còn lại.
X-RateLimit-Reset	Unix timestamp khi hạn mức reset.
Retry-After	Số giây nên chờ trước khi thử lại (chỉ có ở 429).

Cần hạn mức cao hơn cho đợt import ban đầu, hoặc cần key để dùng webhook và audio watermark? Nhắn qua form xin quyền tích hợp, ghi rõ số bài dự kiến đồng bộ.

Tổng quan Bắt đầu nhanh

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