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.
Câu hỏi thường gặp
Tổng hợp từ các câu hỏi thật của đối tác trong quá trình tích hợp. Nếu không tìm thấy câu trả lời, hãy hỏi trợ lý tài liệu ở góc phải màn hình.
Bắt đầu & tài khoản
Tôi xin API key ở đâu và mất bao lâu?
Gửi form tại /api-access. Admin XuniBOX xét duyệt thủ công, thường trong 1–2 ngày làm việc. Khi được duyệt bạn nhận email kèm liên kết đăng nhập cổng đối tác, key hiện đầy đủ đúng một lần.
Có môi trường sandbox riêng không?
Không, chỉ có một base URL duy nhất. API hoàn toàn chỉ đọc nên bạn test thẳng bằng key thật mà không sợ làm hỏng dữ liệu.
Một key dùng cho nhiều môi trường được không?
Được nhưng không nên — hạn mức tính chung trên từng key. Xin key riêng cho staging để traffic test không đẩy production vào lỗi 429.
Key bị lộ thì xử lý thế nào?
Vào cổng đối tác vô hiệu hoá key đang lộ rồi tạo key mới. Key cũ ngừng hoạt động ngay, mọi request tiếp theo trả 403.
Tài khoản đối tác bị tạm khoá thì API còn chạy không?
Không. Khi tài khoản bị tạm khoá, mọi key thuộc tài khoản đó trả 403 và cổng đối tác chuyển sang trang thông báo vô hiệu hoá.
Dữ liệu & đồng bộ
Gọi API có làm tăng play_count không?
Không. play_count chỉ tăng khi người dùng nghe trên xunibox.vn liên tục đủ 10 giây. Mọi endpoint API đều không đụng tới con số này.
Có webhook báo khi kho nhạc có bài mới không?
Có. Đăng ký tại POST /webhooks để nhận track.created, track.updated và track.deleted, mỗi gói tin đều ký HMAC-SHA256. Xem chi tiết ở trang Webhook real-time. Nếu không muốn dựng endpoint public, bạn vẫn có thể poll /tracks?sort=newest mỗi 15–60 phút.
Tôi tải hết kho về database của mình được không?
Được, và nên làm với phần metadata (id, title, artist, genre, duration, bpm). Nhưng tuyệt đối không lưu URL media và không lưu file audio dài hạn.
Duyệt hết kho nhạc thế nào cho hiệu quả?
Dùng limit=100 kèm sort=newest rồi lặp theo page cho tới khi page vượt meta.total_pages. Payload không trả về thời gian đăng, nên để đồng bộ phần mới bạn hãy dùng sort=newest và dừng lại khi gặp id đã lưu ở lần chạy trước (hoặc dùng webhook track.created).
Vì sao ảnh bìa lúc có lúc null?
cover_url là tuỳ chọn. Hãy chuẩn bị sẵn ảnh placeholder trong UI thay vì giả định luôn có ảnh.
Bài bị gỡ thì video người dùng đã xuất có sao không?
Không sao. Bạn chỉ cần ẩn bài khỏi bộ chọn nhạc trong vòng 24 giờ; nội dung đã xuất trước đó vẫn hợp lệ trừ khi có yêu cầu gỡ riêng.
Media & phát nhạc
Nên dùng /tracks/:id hay /tracks/:id/audio-url để làm mới link?
Dùng /tracks/:id/audio-url nếu chỉ cần media: response nhỏ hơn và có sẵn expires_at để đặt lịch làm mới. Dùng /tracks/:id khi cần cả metadata.
Làm mới link cho cả playlist thì sao?
Gọi /tracks/by-ids?ids=… tối đa 50 UUID mỗi lượt thay vì lặp từng bài — tiết kiệm hạn mức đáng kể.
audio_url là bản đầy đủ hay đoạn preview?
Luôn là đoạn preview admin cắt sẵn, dài 15, 30 hoặc 60 giây tuỳ bài. Đọc preview_duration_seconds để hiển thị đúng thanh tiến trình.
Vì sao nhạc phát được lúc test nhưng hôm sau lỗi?
Vì bạn đã lưu audio_url vào database. Link ký hạn chỉ sống khoảng 1 giờ. Chỉ lưu id và lấy link tươi ngay trước khi phát.
Trình duyệt chặn không cho phát nhạc?
Đó là chính sách autoplay. Phải gọi audio.play() bên trong sự kiện click của người dùng, không gọi trong useEffect hay khi trang vừa tải xong.
Người dùng có tải được file nhạc về không?
Nền tảng phát qua link ký hạn ngắn và khuyến nghị bạn dùng controlsList="nodownload" cùng player tự dựng. Không nên đặt nút tải trong giao diện của bạn.
Hiệu năng & hạn mức
Hạn mức mặc định là bao nhiêu?
60 request mỗi phút cho mỗi key, tính theo cửa sổ 60 giây trượt. Admin có thể nâng riêng theo nhu cầu thực tế của bạn.
Làm sao biết mình còn bao nhiêu request?
Đọc header X-RateLimit-Remaining và X-RateLimit-Reset-After trên mọi phản hồi, hoặc gọi GET /me/usage để xem cả lịch sử theo ngày.
Bị 429 thì nên làm gì?
Ngủ đúng số giây trong header Retry-After rồi thử lại, cộng thêm jitter ngẫu nhiên nếu bạn chạy nhiều tiến trình. Tuyệt đối không retry ngay lập tức.
Traffic của tôi rất lớn, có nên xin hạn mức thật cao không?
Thường là không cần. Cache danh sách 5–15 phút ở backend giúp hàng nghìn người dùng chỉ tốn vài request mỗi phút. Chỉ xin nâng hạn mức khi đã cache mà vẫn chạm trần.
Endpoint nào không tính hạn mức?
/healthz, /readyz, /status, /metrics, /health và các file openapi. Chúng trả về X-RateLimit-Policy: unmetered.
Có nên dùng ETag không?
Rất nên. Gửi lại If-None-Match với ETag lần trước, nếu dữ liệu chưa đổi bạn nhận 304 và không tốn băng thông.
Tìm kiếm & tính năng nâng cao
Tìm kiếm có bỏ dấu tiếng Việt không?
Có, dùng endpoint /search. Chuỗi được chuẩn hoá bỏ dấu và hạ chữ thường nên gõ 'hoa nang' vẫn khớp 'Hoà Nắng', đồng thời chịu được sai chính tả nhẹ.
Làm autocomplete cho ô tìm kiếm thế nào?
Gọi /search/suggest với debounce khoảng 150ms và huỷ request cũ bằng AbortController. Kết quả gồm cả bài hát, nghệ sĩ và thể loại.
Có gợi ý bài tương tự không?
Có, /tracks/:id/similar trả về danh sách kèm trường reason cho biết vì sao bài được gợi ý: cùng nghệ sĩ, cùng thể loại hay tên gần giống.
Tôi lấy BPM và tông nhạc ở đâu?
Ở /tracks/:id/waveform, trong khối analysis: bpm, musical_key, energy và loudness_db. Các trường này có thể null với bài cũ.
Vẽ sóng âm mà không tải file nhạc được không?
Được. /tracks/:id/waveform trả sẵn mảng peaks thang 0–100 với số cột tuỳ chọn từ 16 đến 512.
Bảo mật & pháp lý
Gọi API trực tiếp từ trình duyệt được không?
Về kỹ thuật thì được vì CORS mở, nhưng không nên: API key sẽ hiện trong tab Network của mọi người dùng. Hãy đặt một backend proxy gắn key ở phía server.
App mobile có nhúng key được không?
Không. File APK và IPA đều có thể bị dịch ngược. App phải gọi qua backend của bạn.
Tôi phải ghi nguồn thế nào?
Theo định dạng {title} — {artist} (XuniBOX), hiển thị ở mô tả video, overlay khi phát hoặc màn hình thông tin bài hát, khi license.attribution_required là true.
Dùng nhạc cho video quảng cáo được không?
Chỉ khi license.commercial_use_allowed là true. Hãy lọc trước khi hiển thị bài trong luồng tạo nội dung có tài trợ.
Báo cáo nội dung vi phạm ở đâu?
Gửi về legal@xunibox.vn kèm liên kết nội dung và mã bài hát.
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.