XuniBOX

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 nhanhXem endpointsTra cứu yêu cầu

Bản quyền & tuân thủ

Mỗi bài nhạc trong kho đều gắn một mã giấy phép quy định phạm vi sử dụng. Nền tảng của bạn có trách nhiệm chỉ hiển thị bài phù hợp với bối cảnh người dùng và hiển thị ghi nguồn khi giấy phép yêu cầu.

GET/licenses

Danh mục toàn bộ mã giấy phép đang dùng. Không cần API key, cache 1 giờ.

GET/tracks/:id/license

Thông tin bản quyền chi tiết của một bài: ISRC, ngày phát hành, cờ explicit, lãnh thổ và nghĩa vụ tuân thủ.

GET /licenses — danh mục giấy phép

Request
curl --request GET --url 'https://xunibox.vn/api/public/licenses'
Response
HTTP/1.1 200 OK
Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400

{
  "data": [
    {
      "code": "xunibox-standard",
      "name": "XuniBOX Standard",
      "summary": "Dùng miễn phí trong video của người dùng cuối, bắt buộc ghi nguồn.",
      "url": "https://xunibox.vn/policies/license",
      "attribution_required": true,
      "commercial_use_allowed": true
    },
    {
      "code": "xunibox-commercial",
      "name": "XuniBOX Commercial",
      "summary": "Dùng cho nội dung thương mại, không bắt buộc ghi nguồn.",
      "attribution_required": false,
      "commercial_use_allowed": true
    },
    {
      "code": "xunibox-restricted",
      "name": "XuniBOX Restricted",
      "summary": "Chỉ dùng phi thương mại, cấm quảng cáo và nội dung tài trợ.",
      "attribution_required": true,
      "commercial_use_allowed": false
    }
  ],
  "meta": {
    "default_license": "xunibox-standard",
    "takedown_contact": "legal@xunibox.vn",
    "attribution_format": "{title} — {artist} (XuniBOX)"
  }
}
Mã giấy phépThương mạiGhi nguồnDùng khi nào
xunibox-standardĐược phépBắt buộcMặc định cho phần lớn kho nhạc. Người dùng cuối tự do ghép vào video, kể cả kênh có kiếm tiền.
xunibox-commercialĐược phépKhông bắt buộcDùng cho quảng cáo, nội dung tài trợ, thương hiệu — không cần hiện dòng ghi nguồn.
xunibox-restrictedKhông được phépBắt buộcChỉ nội dung phi thương mại. Phải ẩn khỏi luồng tạo quảng cáo và video có tài trợ.

GET /tracks/:id/license

Request
curl --request GET \
  --url 'https://xunibox.vn/api/public/tracks/550e8400-e29b-41d4-a716-446655440000/license' \
  --header 'X-API-Key: xnb_live_your_key'
Response
HTTP/1.1 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Hoà Nắng",
  "artist": "Hoàng Nam",
  "isrc": "VNA012600123",
  "release_date": "2026-03-18",
  "is_explicit": false,
  "license": {
    "code": "xunibox-standard",
    "name": "XuniBOX Standard",
    "attribution_required": true,
    "commercial_use_allowed": true,
    "territory": "worldwide",
    "url": "https://xunibox.vn/policies/license"
  },
  "compliance": {
    "must_display_attribution": true,
    "takedown_contact": "legal@xunibox.vn",
    "notes": "Đối tác phải ngừng dùng bài nhạc cho nội dung mới trong vòng 24 giờ kể từ khi nhận webhook track.deleted."
  }
}
TrườngKiểuÝ nghĩa
license.codestringMã giấy phép, tham chiếu tới /licenses.
license.attribution_requiredbooleantrue nghĩa là giao diện của bạn phải hiển thị dòng ghi nguồn khi phát và khi xuất video.
license.commercial_use_allowedbooleanfalse nghĩa là cấm dùng cho nội dung có tài trợ, quảng cáo hoặc bán hàng.
license.territorystringworldwide, hoặc danh sách mã quốc gia ISO cách nhau bởi dấu phẩy, ví dụ VN,TH.
isrcstring | nullMã ghi âm quốc tế, dùng khi bạn phải báo cáo bản quyền cho bên thứ ba.
release_datedate | nullNgày phát hành chính thức theo định dạng YYYY-MM-DD.
is_explicitbooleantrue nghĩa là lời bài hát có nội dung nhạy cảm — nên ẩn ở chế độ dành cho trẻ em.
compliance.takedown_contactstringĐịa chỉ nhận yêu cầu gỡ bài: legal@xunibox.vn.

Lọc theo bối cảnh sử dụng

Đừng để người dùng chọn xong bài rồi mới báo lỗi. Hãy lọc ngay từ lúc dựng danh sách trong bộ chọn nhạc.

JavaScript — canUseTrack
// Chặn ở tầng ứng dụng: lọc bài theo bối cảnh sử dụng.
function canUseTrack(track, context) {
  const license = track.license ?? {};

  // Video có tài trợ / quảng cáo cần giấy phép cho phép thương mại.
  if (context.isSponsored && license.commercial_use_allowed === false) return false;

  // Nội dung cho trẻ em: loại bài gắn cờ explicit.
  if (context.audience === "kids" && track.is_explicit) return false;

  // Lãnh thổ: "worldwide" hoặc mã ISO quốc gia.
  if (license.territory && license.territory !== "worldwide") {
    if (!license.territory.split(",").includes(context.country)) return false;
  }

  return true;
}

// Hiển thị ghi nguồn đúng định dạng XuniBOX yêu cầu.
function attributionLine(track) {
  if (track.license?.attribution_required === false) return null;
  return `${track.title} — ${track.artist} (XuniBOX)`;
}

Hiển thị ghi nguồn

Định dạng chuẩn là {title} — {artist} (XuniBOX), ví dụ Hoà Nắng — Hoàng Nam (XuniBOX). Dòng này phải xuất hiện ở ít nhất một trong các vị trí: mô tả video, overlay khi phát nhạc, hoặc màn hình thông tin bài hát.

Nghĩa vụ khi bài bị gỡ

Khi nhận webhook track.deleted hoặc thấy bài trả về 404, bạn phải ngừng cho người dùng chọn bài đó trong vòng 24 giờ. Video đã xuất trước đó không bị ảnh hưởng, trừ khi XuniBOX gửi yêu cầu gỡ riêng qua legal@xunibox.vn.
Tình huốngThời hạn xử lýHành động tối thiểu
Nhận webhook track.deleted24 giờẨn bài khỏi bộ chọn nhạc và khỏi kết quả tìm kiếm nội bộ.
Nhận yêu cầu gỡ trực tiếp từ XuniBOX48 giờGỡ hoặc tắt tiếng nhạc trong các nội dung được nêu tên.
Bài đổi sang giấy phép hẹp hơn (track.updated)24 giờÁp dụng bộ lọc mới, không cần gỡ nội dung cũ.
Bạn phát hiện nội dung vi phạm của người dùngNgay khi biếtBáo về legal@xunibox.vn kèm liên kết nội dung.
Webhook real-timeThư viện & SDK

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