API Image Host

Dùng API của zyo.lol để tải lên, liệt kê và xoá file Image Host cùng paste từ script, bot và ứng dụng của riêng bạn. Mọi response đều là JSON có type là success hoặc error và một message.

Base URL

Mọi endpoint đều nằm dưới URL này. API chạy trên trang chính, không chạy trên link rút gọn.

https://zyo.lol/php/images/api

Xác thực

Bạn cần có Image Host Image Host để dùng API.

1. Tạo key. Mở cài đặt Image Host và vào Image Host › Cài đặt › API key · ShareX, rồi bấm Tạo key.
2. Sao chép ngay. Key bắt đầu bằng zyo_ và chỉ hiện một lần. Bạn cũng có thể tải file cấu hình ShareX có sẵn ở đó.
3. Gửi key trong mọi request qua header Authorization. Dạng Bearer zyo_… cũng được.

Authorization: zyo_your_key

Body của POST có thể là JSON hoặc form data. Riêng upload phải dùng multipart form data.

Giới hạn

File và paste tải lên sẽ được quét nội dung không an toàn và có thể bị ẩn cho đến khi admin xem xét.

Tải lên file lớn

Có hai cách tải lên một file:

• Một request với Tải lên một file, cho file tối đa 95 MB.
• Tải lên trực tiếp qua ba bước, cho mọi file trong giới hạn gói của bạn. File đi thẳng vào kho lưu trữ nên nhanh hơn và tải được file lớn.

1. Bắt đầu. Gửi tên file và kích thước chính xác tới POST /uploads. Bạn nhận được upload_url, các headers cần gửi và một key.
2. Tải lên. PUT nguyên file lên upload_url với đúng các header đó. Không thêm header Authorization ở bước này. Link hết hạn sau 10 phút kể từ bước 1, nên hãy PUT ngay.
3. Hoàn tất. Gửi key tới POST /uploads/complete. Bạn nhận được đối tượng file giống như khi tải lên bình thường.

curl -X PUT "UPLOAD_URL_TU_BUOC_1" \
  -H "Content-Type: application/octet-stream" \
  --upload-file video.mp4

Lỗi

Lỗi dùng mã trạng thái HTTP, và hầu hết có kèm một code ngắn để bạn kiểm tra trong ứng dụng.

{ "code": "not_found", "type": "error", "message": "File not found." }

Lỗi upload như file quá lớn, định dạng không hỗ trợ hoặc hết dung lượng sẽ trả về trạng thái 400 kèm message cho biết lỗi gì. Một request lớn hơn khoảng 100 MB sẽ bị Cloudflare chặn với trạng thái 413 và một trang HTML trước khi tới zyo.lol, vì vậy file lớn hãy luôn dùng tải lên trực tiếp.

Bị chuyển về trang này với trạng thái 307

Nếu request API trả về trạng thái 307 và chuyển bạn tới trang này, API đang bị giới hạn tạm thời vì zyo.lol nhận lưu lượng bất thường. Request của bạn chưa tới zyo.lol, nên không có gì được tải lên, thay đổi hay xoá.

1. Đợi một chút rồi thử lại. Giới hạn thường được gỡ trong khoảng 10 phút.
2. Tạo key mới nếu vẫn bị như vậy. Mở cài đặt Image Host, bấm Tạo key rồi cập nhật ứng dụng hoặc ShareX của bạn.
3. Tải lên từ panel zyo.lol vẫn hoạt động trong lúc API bị giới hạn.

Tài khoản

Xem key thuộc tài khoản nào và còn bao nhiêu dung lượng.

Lấy thông tin tài khoản

Trả về username, dung lượng đã dùng và giới hạn của bạn. Kích thước tính bằng byte.

Yêu cầu

curl https://zyo.lol/php/images/api/me \
  -H "Authorization: zyo_your_key"

Phản hồi

{
  "user": { "id": 1, "username": "wowie" },
  "usage": { "count": 42, "bytes": 9639060 },
  "limits": {
    "premium": true,
    "quota_bytes": 53687091200,
    "max_file_bytes": 262144000
  },
  "type": "success",
  "message": "OK"
}

File

Tải lên, liệt kê, tra cứu và xoá ảnh, video trên Image Host của bạn.

Liệt kê file

Trả về các file của bạn, mới nhất trước. Khi more là true, hãy lấy trang tiếp theo.

Yêu cầu

curl "https://zyo.lol/php/images/api/files?per_page=10&type=image" \
  -H "Authorization: zyo_your_key"

Phản hồi

{
  "files": [
    {
      "id": 1042,
      "code": "aB3xK9q",
      "url": "https://i.zyo.lol/aB3xK9q.png",
      "raw": "https://r2.zyo.lol/img/.../aB3xK9q.png",
      "filename": "screenshot.png",
      "size": "180 KB",
      "resolution": "1920×1080",
      "video": false,
      "kind": "image",
      "bytes": 184320,
      "embed": "",
      "favorite": false,
      "anonymous": false,
      "folder_id": null,
      "views": 12,
      "time": 1793023024,
      "ago": "3d ago",
      "expires": "",
      "review": false
    }
  ],
  "page": 1,
  "more": false,
  "type": "success",
  "message": "OK"
}

Tải lên một file

Tải lên một file dạng multipart form data trong một request, tối đa 95 MB. Hỗ trợ PNG, JPG, GIF, WEBP, MP4, WEBM và MOV. File lớn hơn hãy dùng Bắt đầu tải lên trực tiếp. Trường image là một đối tượng file giống trong Liệt kê file.

Yêu cầu

curl https://zyo.lol/php/images/api/files \
  -H "Authorization: zyo_your_key" \
  -F "file=@screenshot.png"

Phản hồi

{
  "image": {
    "code": "aB3xK9q",
    "url": "https://i.zyo.lol/aB3xK9q.png",
    "raw": "https://r2.zyo.lol/img/.../aB3xK9q.png",
    "filename": "screenshot.png"
  },
  "type": "success",
  "message": "Uploaded."
}

Bắt đầu tải lên trực tiếp

Bước 1 của tải lên trực tiếp, cho file mọi kích thước trong giới hạn gói của bạn (100 MB, hoặc 250 MB với Premium). Trả về một link tải lên dùng một lần, hết hạn sau 10 phút. Sau đó PUT file lên upload_url với đúng các header trong response, rồi gọi Hoàn tất tải lên trực tiếp.

Yêu cầu

curl https://zyo.lol/php/images/api/uploads \
  -H "Authorization: zyo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "video.mp4", "size": 157286400}'

Phản hồi

{
  "upload_url": "https://….r2.cloudflarestorage.com/zyo/pending/1/image_….mp4?X-Amz-…",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/octet-stream",
    "Content-Length": "157286400"
  },
  "key": "pending/1/image_7c1f….mp4",
  "expires_in": 600,
  "type": "success",
  "message": "Upload prepared."
}

Hoàn tất tải lên trực tiếp

Bước 3 của tải lên trực tiếp. Gọi ngay sau khi PUT xong. File được kiểm tra, lưu lại và trả về với mã trạng thái 201, giống Tải lên một file. Mỗi key chỉ dùng được một lần và chỉ cho tài khoản đã tạo nó.

Yêu cầu

curl https://zyo.lol/php/images/api/uploads/complete \
  -H "Authorization: zyo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "pending/1/image_7c1f….mp4", "name": "video.mp4"}'

Phản hồi

{
  "image": {
    "code": "aB3xK9q",
    "url": "https://i.zyo.lol/aB3xK9q.mp4",
    "raw": "https://r2.zyo.lol/img/.../aB3xK9q.mp4",
    "filename": "video.mp4"
  },
  "type": "success",
  "message": "Uploaded."
}

Lấy một file

Trả về một file của bạn theo mã.

Yêu cầu

curl "https://zyo.lol/php/images/api/file?code=aB3xK9q" \
  -H "Authorization: zyo_your_key"

Phản hồi

{
  "file": { "code": "aB3xK9q", "url": "https://i.zyo.lol/aB3xK9q.png", "views": 12 },
  "type": "success",
  "message": "OK"
}

Xoá một file

Xoá một file của bạn. Không thể hoàn tác.

Yêu cầu

curl https://zyo.lol/php/images/api/file \
  -H "Authorization: zyo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"code": "aB3xK9q", "action": "delete"}'

Phản hồi

{
  "type": "success",
  "message": "File deleted"
}

Paste

Tạo và quản lý ghi chú, đoạn code trên Paste Bin.

Liệt kê paste

Trả về các paste của bạn, mới cập nhật trước. Không kèm nội dung, hãy dùng Lấy một paste để xem nội dung.

Yêu cầu

curl https://zyo.lol/php/images/api/pastes \
  -H "Authorization: zyo_your_key"

Phản hồi

{
  "pastes": [
    {
      "slug": "NbtD5TtH",
      "url": "https://i.zyo.lol/NbtD5TtH",
      "title": "Notes",
      "mode": "markdown",
      "locked": false,
      "burn": false,
      "views": 3,
      "expires_at": null
    }
  ],
  "type": "success",
  "message": "OK"
}

Tạo paste

Tạo một paste và trả về với mã trạng thái 201. Paste mới sẽ được quét nội dung không an toàn ngay sau khi lưu.

Yêu cầu

curl https://zyo.lol/php/images/api/pastes \
  -H "Authorization: zyo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Notes", "content": "# Hello"}'

Phản hồi

{
  "paste": { "slug": "NbtD5TtH", "url": "https://i.zyo.lol/NbtD5TtH", "title": "Notes" },
  "type": "success",
  "message": "Paste created."
}

Lấy một paste

Trả về một paste của bạn kèm nội dung.

Yêu cầu

curl "https://zyo.lol/php/images/api/paste?slug=NbtD5TtH" \
  -H "Authorization: zyo_your_key"

Phản hồi

{
  "paste": { "slug": "NbtD5TtH", "title": "Notes", "content": "# Hello" },
  "type": "success",
  "message": "OK"
}

Cập nhật hoặc xoá paste

Chỉ cập nhật các trường bạn gửi và giữ nguyên phần còn lại, hoặc xoá paste.

Yêu cầu

curl https://zyo.lol/php/images/api/paste \
  -H "Authorization: zyo_your_key" \
  -H "Content-Type: application/json" \
  -d '{"slug": "NbtD5TtH", "action": "update", "title": "New title"}'

Phản hồi

{
  "paste": { "slug": "NbtD5TtH", "title": "New title" },
  "type": "success",
  "message": "Paste saved."
}

Liên quan