T02 Fingerlens · API

Địa chỉ gốc

Địa chỉ trang này chính là địa chỉ API. Nếu server chạy qua tunnel thử nghiệm thì địa chỉ sẽ đổi khi tunnel khởi động lại: hãy mở lại trang này để lấy địa chỉ mới.

• JSON là mảng ở gốc (không bọc trong object); Cache-Control: public, max-age=300 (5 phút).
• Chỉ trả các dòng đang hiện. Mọi ảnh là địa chỉ https:// đầy đủ trên CDN, dùng nguyên, không nối thêm.
• Timeout của app: 5 giây kết nối, 10 giây đọc. Chỉ dùng HTTPS.
• id ổn định suốt đời của dòng: lưu id khi người dùng chọn, không dùng vị trí hay tên làm khóa.
• Danh sách có thể đổi bất cứ lúc nào (team sửa Google Sheet rồi đồng bộ). Giữ bản trả về tốt gần nhất để dùng khi gọi lỗi; làm mới tối đa 5 phút một lần.
• Ảnh không bao giờ bị ghi đè: ảnh đổi sẽ có địa chỉ mới trong lần trả về sau.
• Đường dẫn không tồn tại trả 404 dạng JSON.

GET/v1/effects

Danh sách hiệu ứng.

Mẫu

{
  "id": 10,
  "name": "Fire ball",
  "avtLarge": "https://cdn2.teamupinc.xyz/apps-assets/t02-fingerlens-api/thumbs/img_effect_fire_ball.png",
  "frameEffect": 21,
  "isSpecial": true,
  "isPro": false,
  "enableFrame": false,
  "tiles": ["https://.../tiles/fire1.webp", "..."]
}

Trường	Ý nghĩa
id	Số nguyên ổn định. Lưu khi người dùng chọn hoặc mở khóa hiệu ứng.
name	Tên hiển thị.
avtLarge	Ảnh thumbnail.
frameEffect	Mã shader (số, có thể có phần thập phân như 4, 26.1). Chỉ mã app biết mới vẽ được.
isSpecial	true: nằm ở mục đặc biệt (từ cái thứ hai xem quảng cáo thưởng).
isPro	App bỏ qua.
enableFrame	true: vẽ khung bàn tay.
tiles	Các khung sprite theo thứ tự. Chỉ có ở hiệu ứng sprite, các hiệu ứng khác không có trường này.

GET/v1/character-categories

Các nhóm nhân vật, mỗi nhóm kèm danh sách nhân vật.

Mẫu

{
  "id": "anime",
  "name": "Anime",
  "order": 0,
  "characters": [
    {
      "id": 0, "name": "Ace", "category": "anime",
      "paths": ["https://.../characters/ace_1.png", "https://.../characters/ace_2.png"]
    }
  ]
}

Trường	Ý nghĩa
id	Mã nhóm, chuỗi (anime).
name	Tên hiển thị. /<tên> là chuỗi đã dịch sẵn trong app.
order	Thứ tự nhóm, tăng dần.
characters[].id	Số nguyên ổn định. Bộ tự tạo của người dùng lưu số này.
characters[].category	id của nhóm.
characters[].paths	Hai ảnh, là hai khung hoạt ảnh. Luôn đủ hai (nếu sheet chỉ có một thì lặp lại).

GET/v1/finger-sets

Các bộ 5 nhân vật có sẵn.

Mẫu

{
  "id": 0, "name": "Anime Set 1", "isCustom": false,
  "characters": [ { "id": 0, "name": "Ace", "category": "anime", "paths": ["...", "..."] } ]
}

characters có đúng 5 phần tử, từ ngón cái đến ngón út, cùng dạng với phần trên. isCustom luôn là false với bộ của catalog. Bộ có nhân vật bị ẩn sẽ không được trả về.