Usage

Upload API

Upload files via the form, or programmatically using POST /add/. Include Accept: application/json to receive a JSON response (default when no Accept header is sent).

• Python
• curl
• JavaScript

import requests

with open('/path/to/some/file.jpg', 'rb') as f:
    r = requests.post(
        'http://domain.tld/add/',
        files={"file1": f},
        headers={"Accept": "application/json"}
    )
    print(r.text)

curl -X POST http://domain.tld/add/ \
  -H "Accept: application/json" \
  -F "file1=@/path/to/some/file.jpg"

const form = new FormData();
form.append('file1', document.querySelector('input[type=file]').files[0]);
const res = await fetch('http://domain.tld/add/', {
  method: 'POST',
  headers: { 'Accept': 'application/json' },
  body: form
});
const data = await res.json();
console.log(data);

Typical response:

[
    {
        "sha1": "c4a08279e801ca7459542da745fe4bbd067512b1",
        "md5": "94bb595c8b04fb3375fa264bec26ed7b",
        "size": 208378,
        "extension": "jpg",
        "mime": "image/jpeg",
        "height": 1600,
        "width": 896,
        "path": "upload/c4/c4a08279e801ca7459542da745fe4bbd067512b1/file.jpg",
        "slug": "file",
        "original_name": "file.jpg",
        "metas_path": "upload/c4/c4a08279e801ca7459542da745fe4bbd067512b1/metas.json"
    }
]

Raw Files

Access the original stored file directly:

GET /upload/{subdir}/{sha1}/{slug}.{ext}

{subdir} is the first two characters of the sha1 — available in the path field of the upload response.

Thumbnails

Thumbnails are generated on-the-fly by imgproxy. Two URL patterns are supported:

GET /thumbnails/{subdir}/{sha1}/{slug}-{algo}-{sizex}x{sizey}.{format}
GET /thumbnails/{subdir}/{sha1}/{slug}-original.{format}

The {format} extension controls the output format — independent of the uploaded file's format. A .png upload can be requested as .webp directly, no re-upload needed.

Resizing algorithms

Whitelisted sizes

• 100×100
• 200×200
• 500×500

Output formats

jpg, jpeg, png, gif, webp, avif