Compression API Documentation

Authentication

All API requests require an x-api-key header with your API key. You can find your key on the Settings page.

Compress Image

POST https://smallest.zip/api/compress

Upload a JPEG image as multipart/form-data. Returns the compressed image as binary data.

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	`multipart/form-data`	Yes

Request Body

Multipart form data with a field named image containing the JPEG file.

Response

200 OK — Returns the compressed image as application/octet-stream binary data.

Error responses return JSON:

Status	Meaning
`401`	Missing or invalid API key
`402`	No credits remaining
`400`	Bad request (no image provided or wrong content type)
`500`	Compression failed (no credit deducted)

S3-Compatible Write-back API

PUT https://smallest.zip/s3/{bucket}/{key}?type=image

A drop-in S3-compatible endpoint. Send your file as a raw binary PUT body — the service compresses it, then writes the result directly to your configured S3 bucket using the IAM credentials you saved on the Settings page. Your application never needs to know compression happened.

Configure S3 write-back credentials per content type on your Settings page.

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	MIME type of the file (e.g. `image/jpeg`)	No

Query Parameters

Parameter	Values	Default
`type`	`image`, `video`, `text`, `pdf`	inferred from Content-Type

Response

200 OK — Returns JSON with compression metadata:

{
  "original_size": 2048576,
  "compressed_size": 921600,
  "compression_ratio": 55.00,
  "key": "photos/sunset.jpg",
  "bucket": "my-bucket"
}

The compressed file is also written to your S3 bucket at {prefix}/{key} (if a prefix is configured).

Error responses return JSON with an error field (same status codes as the compress endpoint, plus 501 for unsupported content types).

curl -X PUT "https://smallest.zip/s3/my-bucket/photos/sunset.jpg?type=image" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

import requests

with open("photo.jpg", "rb") as f:
    data = f.read()

response = requests.put(
    "https://smallest.zip/s3/my-bucket/photos/sunset.jpg",
    params={"type": "image"},
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "image/jpeg",
    },
    data=data,
)
print(response.json())

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var imageBytes = File.ReadAllBytes("photo.jpg");
var content = new ByteArrayContent(imageBytes);
content.Headers.ContentType = new("image/jpeg");

var response = await client.PutAsync(
    "https://smallest.zip/s3/my-bucket/photos/sunset.jpg?type=image",
    content);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Code Examples

curl -X POST https://smallest.zip/api/compress \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  --output compressed.jpg

const form = new FormData();
form.append("image", fileInput.files[0]);

const response = await fetch("https://smallest.zip/api/compress", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: form,
});

const blob = await response.blob();
const url = URL.createObjectURL(blob);
// Use the compressed image blob

import requests

headers = {"x-api-key": "YOUR_API_KEY"}
files = {"image": open("photo.jpg", "rb")}

response = requests.post(
    "https://smallest.zip/api/compress",
    headers=headers,
    files=files,
)

with open("compressed.jpg", "wb") as f:
    f.write(response.content)

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

using var content = new MultipartFormDataContent();
var imageBytes = File.ReadAllBytes("photo.jpg");
content.Add(new ByteArrayContent(imageBytes), "image", "photo.jpg");

var response = await client.PostAsync(
    "https://smallest.zip/api/compress", content);

var compressed = await response.Content.ReadAsByteArrayAsync();
File.WriteAllBytes("compressed.jpg", compressed);

package main

import (
    "bytes"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("image", "photo.jpg")
    file, _ := os.Open("photo.jpg")
    io.Copy(part, file)
    file.Close()
    writer.Close()

    req, _ := http.NewRequest("POST",
        "https://smallest.zip/api/compress", body)
    req.Header.Set("x-api-key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", writer.FormDataContentType())

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    out, _ := os.Create("compressed.jpg")
    io.Copy(out, resp.Body)
    out.Close()
}