Image Host API

Use the zyo.lol API to upload, list and delete Image Host files and pastes from your own scripts, bots and apps. Every response is JSON with a type of success or error and a message.

Base URL

All endpoints live under this URL. The API works on the main site, not on short links.

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

Authentication

You need Image Host Image Host to use the API.

1. Create a key. Open Image Host settings and go to Image Host › Settings › API keys · ShareX, then click New key.
2. Copy it right away. The key starts with zyo_ and is only shown once. You can also download a ready ShareX config there.
3. Send it with every request in the Authorization header. Bearer zyo_… works too.

Authorization: zyo_your_key

POST bodies can be JSON or form data. Uploads must be multipart form data.

Limits

Uploaded files and pastes are scanned for unsafe content and may be hidden until an admin reviews them.

Uploading big files

There are two ways to upload a file:

• One request with Upload a file, for files up to 95 MB.
• Direct upload in three steps, for anything up to your plan limit. The file goes straight to storage, so it is faster and big files work.

1. Start. Send the file name and exact size to POST /uploads. You get an upload_url, the headers to send and a key.
2. Upload. PUT the raw file to upload_url with exactly those headers. Do not add the Authorization header here. The link expires 10 minutes after step 1, so start the PUT right away.
3. Finish. Send the key to POST /uploads/complete. You get the same file object as a normal upload.

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

Errors

Errors use an HTTP status code, and most include a short code you can check in your app.

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

Upload problems such as a file that is too big, an unsupported type or a full storage return status 400 with a message that says what is wrong. A single request over about 100 MB is stopped by Cloudflare with status 413 and an HTML page, before it reaches zyo.lol, so always use direct upload for big files.

Redirected here with status 307

If an API request answers with status 307 and sends you to this page, the API is briefly limited because zyo.lol is receiving unusual traffic. Your request never reached zyo.lol, so nothing was uploaded, changed or deleted.

1. Wait and try again. The limit usually lifts within about 10 minutes.
2. Create a new key if it keeps happening. Open Image Host settings, click New key and update your app or ShareX.
3. Uploading from the zyo.lol panel still works while the API is limited.

Account

Check which account a key belongs to and how much storage is left.

Get your account

Returns your username, storage usage and limits. Sizes are in bytes.

Request

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

Response

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

Files

Upload, list, look up and delete the images and videos on your Image Host.

List files

Returns your files, newest first. When more is true, ask for the next page.

Request

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

Response

{
  "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"
}

Upload a file

Uploads one file as multipart form data in a single request, up to 95 MB. PNG, JPG, GIF, WEBP, MP4, WEBM and MOV files are supported. For bigger files use Start a direct upload. The image field is a file object like the one in List files.

Request

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

Response

{
  "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."
}

Start a direct upload

Step 1 of a direct upload, for files of any size up to your plan limit (100 MB, or 250 MB with Premium). Returns a one-time upload link that expires after 10 minutes. Then PUT the file to upload_url with exactly the headers from the response, and call Finish a direct upload.

Request

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

Response

{
  "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."
}

Finish a direct upload

Step 3 of a direct upload. Call it right after the PUT finished. The file is checked, saved and returned with status 201, like Upload a file. A key works only once and only for the account that started it.

Request

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"}'

Response

{
  "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."
}

Get a file

Returns one of your files by its code.

Request

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

Response

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

Delete a file

Deletes one of your files. This cannot be undone.

Request

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

Response

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

Pastes

Create and manage Paste Bin notes and code snippets.

List pastes

Returns your pastes, recently updated first. Content is not included, use Get a paste for that.

Request

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

Response

{
  "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"
}

Create a paste

Creates a paste and returns it with status 201. New pastes are scanned for unsafe content shortly after they are saved.

Request

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

Response

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

Get a paste

Returns one of your pastes with its content.

Request

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

Response

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

Update or delete a paste

Updates only the fields you send and keeps the rest, or deletes the paste.

Request

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"}'

Response

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

Related