REST API · v1
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.
URL media và chuyện hết hạn
audio_url, cover_url và avatar_url là signed URL sống 1 giờ. Sau đó chúng trả 403 chứ không phải 404, nên nếu thấy ảnh bìa vỡ hay audio im lặng thì gần như chắc chắn là URL đã hết hạn.
- • Lưu
idvào database của bạn, đừng lưu URL. - • Cache response tối đa 5 phút phía bạn là đủ; cache lâu hơn sẽ phục vụ URL sắp chết.
- • Trước khi phát hoặc render/export video, gọi
/tracks/:id/audio-urlđể lấy URL mới — endpoint này nhẹ hơn/tracks/:idvì chỉ trả phần media và luônno-store. - • Cần làm mới hàng loạt (khôi phục playlist) thì dùng
/tracks/by-ids?ids=…, tối đa 50 ID mỗi lượt. - • Dùng
media_expires_in/expires_atđể tự đặt lịch xin URL mới thay vì đoán. - • Nếu bạn tự tải file về hạ tầng của mình, chỉ giữ trong vòng đời tác vụ render rồi xóa.
Làm mới URL trước khi render
// Lúc người dùng chọn nhạc: chỉ lưu ID vào DB của bạn.
await db.videoDrafts.update(draftId, { xunibox_track_id: track.id });
// Lúc render video (có thể vài ngày sau): xin URL mới.
const media = await xuniboxFetch(
`/tracks/${draft.xunibox_track_id}/audio-url`
);
await downloadAudio(media.audio_url); // hết hạn sau media.media_expires_in giây
// Làm mới cả playlist trong một request:
const { data } = await xuniboxFetch(`/tracks/by-ids?ids=${ids.join(",")}`);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.