API

Quick start#

This stores photo.png and answers with a direct link to it. That is the whole API in one line.

curl -F "file=@photo.png" https://imgdb.io/api/v1/upload

Base URL

Every path below is relative to this base, over HTTPS.

Upload an image#

Stores one image and returns a direct link to it.

Body

Send the image either way:

• multipart/form-data with a file field, or
• the raw bytes as the body, with a matching Content-Type.

Parameters

Link lifetimes

Seconds / Lifetime

72h (259200 seconds) is the default when ttl is not sent.

Request

curl -F "file=@photo.png" \
  "https://imgdb.io/api/v1/upload?ttl=86400"

Response

{
  "url": "https://imgdb.io/i/Ym5TEo4.png",
  "id": "Ym5TEo4.png",
  "kind": "image",
  "type": "image/png",
  "size": 12345,
  "expires": 1782509812
}

kind is image, protected or once. id is the identifier inside url - only plain image uploads can go into an album. expires is epoch seconds, or null for a link that never expires.

Create an album#

One link for up to 30 images. Post the files in a single request:

curl -F "file=@a.png" -F "file=@b.jpg" -F "file=@c.gif" \
  "https://imgdb.io/api/v1/album?ttl=604800"

Or upload them first and group the ids afterwards. Do it this way for albums over 20 MB - the reverse proxy caps a single request at that, while each image gets its own 16 MB budget.

curl -X POST https://imgdb.io/api/v1/album \
  -H "Content-Type: application/json" \
  -d '{"items":["Ym5TEo4.png","Rk2p1Za.jpg"],"ttl":604800}'

Response

{
  "url": "https://imgdb.io/a/Ym5TEo4",
  "id": "Ym5TEo4",
  "count": 2,
  "expires": 1783114612,
  "protected": false,
  "items": ["Ym5TEo4.png", "Rk2p1Za.jpg"]
}

A password moves the images into a private folder, so they can only be reached through the album gate - the response then omits their ids. Members must be plain image uploads: one-time and password-protected images cannot be grouped. In the two-step flow every image keeps the lifetime it was uploaded with, so give them at least the album's ttl - otherwise the album outlives its own contents.

Look up a link#

Metadata for an image or an album, without downloading anything. Pass the id you got back from upload or album.

curl https://imgdb.io/api/v1/info/Ym5TEo4.png

Response

{
  "kind": "image",
  "id": "Ym5TEo4.png",
  "url": "https://imgdb.io/i/Ym5TEo4.png",
  "type": "image/png",
  "size": 12345,
  "expires": 1782509812
}

One-time and password-protected links are deliberately not exposed here - a one-time link can only be resolved by viewing it, which consumes it.

Limits#

• No key, no token, no signup - the API is open.
• 20 requests per minute and 100 stored images per day, per IP.
• 16 MB per image, 30 images per album, 20 MB per request.
• A 429 response carries a Retry-After header, in seconds.

Accepted formats

PNG, JPG, GIF, WEBP, AVIF and BMP - BMP is converted to PNG. Every image is re-encoded on arrival, which strips EXIF and anything appended after the image data. SVG is not accepted. Links that live longer than 72h are compressed harder to save disk.

Errors#

Every failure is JSON: { "error": "…" }, with the status code:

Examples#

# a direct link, default 72h lifetime
curl -F "file=@photo.png" https://imgdb.io/api/v1/upload

# 24h link that burns after the first view
curl -F "file=@photo.png" \
  "https://imgdb.io/api/v1/upload?ttl=86400&once=1"

# behind a password
curl -H "X-Upload-Password: hunter2" \
  -F "file=@photo.png" https://imgdb.io/api/v1/upload

# raw bytes instead of multipart, link never expires
curl --data-binary @photo.png -H "Content-Type: image/png" \
  "https://imgdb.io/api/v1/upload?ttl=0"

# one album out of three files
curl -F "file=@a.png" -F "file=@b.jpg" -F "file=@c.gif" \
  "https://imgdb.io/api/v1/album?ttl=604800"

# what is behind a link
curl https://imgdb.io/api/v1/info/Ym5TEo4.png