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.

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

Cấu trúc dữ liệu

Track · application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Tên bài hát",
  "artist": "Tên nghệ sĩ",
  "genre": "Pop",
  "duration": "3:24",
  "audio_url": "https://...signed-preview-url...",
  "preview_start_seconds": 42,
  "preview_duration_seconds": 30,
  "cover_url": "https://...signed-url...",
  "play_count": 1240,
  "created_at": "2026-08-05T01:30:00.000Z"
}

Artist · application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Tên nghệ sĩ",
  "biography": "Tiểu sử nghệ sĩ",
  "avatar_url": "https://...signed-url...",
  "track_count": 12,
  "created_at": "2026-08-05T01:30:00.000Z",
  "media_expires_in": 3600
}

Track

Trường	Kiểu	Mô tả
id	uuid	ID ổn định, dùng làm khóa lưu bên bạn.
title	string	Tên bài hát.
artist	string	Tên nghệ sĩ dạng chữ.
genre	string \| null	Thể loại, có thể trống.
duration	string	Thời lượng bản gốc, dạng m:ss.
audio_url	string	URL ký tạm thời của đoạn preview đã cắt sẵn.
preview_start_seconds	integer	Giây bắt đầu đoạn preview trong bản gốc.
preview_duration_seconds	integer	Độ dài preview: 15, 30 hoặc 60 giây.
cover_url	string \| null	Ảnh bìa ký tạm thời, WebP vuông.
play_count	integer	Lượt phát ghi nhận trên xunibox.vn.
created_at	ISO 8601	Thời điểm bài hát được thêm vào kho.

Artist

Trường	Kiểu	Mô tả
id	uuid	ID nghệ sĩ.
name	string	Tên hiển thị.
biography	string \| null	Tiểu sử dạng text thuần.
avatar_url	string \| null	Ảnh đại diện ký tạm thời, tỉ lệ 1:1.
track_count	integer	Số bài nhạc hiện có (chỉ ở /artists).
created_at	ISO 8601	Thời điểm tạo hồ sơ nghệ sĩ.
media_expires_in	integer	Số giây còn hiệu lực của URL media, hiện là 3600.

API chỉ phát đoạn preview đã được admin cắt sẵn (tối đa 60 giây), không bao giờ trả file gốc đầy đủ. Nếu bạn cần bản full cho mục đích thương mại, liên hệ để ký thỏa thuận riêng.

OpenAPI & thử ngay URL media & hết hạn

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