Authentication

All API requests require a Bearer token. Create tokens in your Dashboard after logging in with GitHub.

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Requests without a valid token receive a 401 Unauthenticated response. Banned users receive 403 Forbidden.

If a conversion would exceed your remaining tokens, the API returns 402 with an insufficient_tokens error.

Endpoints

All endpoints are prefixed with /api/v1 and require authentication. Encode endpoints additionally require sufficient token balance.

Encode single image

POST /api/v1/encode

Upload a single image file as multipart/form-data.

Parameter	Type	Required	Description
`image`	file	required	Image file. Accepted formats: jpg, jpeg, jfif, png, gif, bmp, svg, webp, ico, tiff, tif, avif, heic, heif. Max 5 MB.
`optimize-images`	string	optional	Set to `"true"` to optimize JPEG/PNG before encoding (jpegoptim/optipng). Default: false.
`format`	string	optional	Controls the format of the `output` field. Values: `raw` (default), `data_uri`, `image`, `css`, `css_full`, `markdown`, `json`.

200 Response

JSON

{
    "name": "photo.jpg",
    "extension": "jpg",
    "size": 45231,
    "size_encoded": 60308,
    "mime_type": "image/jpeg",
    "width": 800,
    "height": 600,
    "convert_time": 0.042,
    "optimized": 0,
    "output": "/9j/4AAQSkZJRg...",
    "tokens_used": 1
}

The output field format depends on the format parameter. By default it contains the raw base64 string. Set format=image to get a ready-to-use <img> tag, format=css for a CSS background rule, etc.

Encode batch (up to 20 images)

POST /api/v1/encode/batch

Upload multiple image files. Each file is processed individually and deducts tokens separately.

Parameter	Type	Required	Description
`images[]`	file[]	required	Array of image files. Maximum 20 files per request.
`optimize-images`	string	optional	Set to `"true"` to optimize all images before encoding.
`format`	string	optional	Controls the format of the `output` field per result. Values: `raw` (default), `data_uri`, `image`, `css`, `css_full`, `markdown`, `json`.

200 Response

JSON

{
    "results": [
        {
            "name": "photo1.jpg",
            "extension": "jpg",
            "size": 45231,
            "size_encoded": 60308,
            "mime_type": "image/jpeg",
            "width": 800,
            "height": 600,
            "convert_time": 0.042,
            "optimized": 0,
            "output": "/9j/4AAQSkZJRg...",
            "tokens_used": 1
        },
        {
            "name": "icon.png",
            "extension": "png",
            "size": 2105430,
            "size_encoded": 2807240,
            "mime_type": "image/png",
            "width": 512,
            "height": 512,
            "convert_time": 0.118,
            "optimized": 1,
            "output": "iVBORw0KGgoAAAA...",
            "tokens_used": 3
        }
    ]
}

If a single file in the batch fails (e.g. wrong format), its entry contains error and message fields instead of the output data. Other files are still processed.

Check usage

GET /api/v1/usage

Returns your current token balance, usage stats, and pricing tiers.

200 Response

JSON

{
    "total_remaining": 9587,
    "api_calls_this_month": 13,
    "tokens_used_this_month": 18,
    "token_tiers": [
        { "up_to_mb": 1, "tokens": 1 },
        { "up_to_mb": 2, "tokens": 2 },
        { "up_to_mb": 3, "tokens": 3 },
        { "up_to_mb": 4, "tokens": 4 },
        { "up_to_mb": 5, "tokens": 5 }
    ],
    "max_file_size_mb": 5,
    "rate_limit": {
        "requests_per_minute": 60
    }
}

List tokens

GET /api/v1/tokens

Returns all API keys for the authenticated user.

200 Response

JSON

{
    "tokens": [
        {
            "id": 1,
            "name": "My Project",
            "last_used_at": "2026-03-27T14:30:00+00:00",
            "created_at": "2026-03-01T10:00:00+00:00"
        }
    ]
}

Rate limits

API requests are rate-limited per user:

60

requests per minute

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`Retry-After`	Seconds to wait before retrying (only on `429`)

When rate-limited, the API responds with 429 Too Many Requests.

Error codes

All error responses include an error code and a human-readable message:

{
    "error": "no_file",
    "message": "No valid file upload given."
}

HTTP	Error Code	Description
200	-	Success
400	`no_file`	No image file was included in the request
401	-	Invalid or missing API key
402	`quota_exceeded`	No tokens remaining
402	`insufficient_tokens`	File requires more tokens than you have remaining
413	`file_too_large`	File exceeds maximum size (5 MB)
422	`unsupported_format`	Unsupported file type
422	`too_many_files`	Batch request exceeds 20 files
429	`rate_limit_exceeded`	Rate limit exceeded (60 requests per minute)
500	`upload_failed`	Upload or server processing failed

Code examples

Encode single file

cURL

curl -X POST https://www.base64-image.de/api/v1/encode \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@photo.jpg" \
  -F "optimize-images=false" \
  -F "format=image"

JavaScript

const form = new FormData();
form.append('image', fileInput.files[0]);
form.append('optimize-images', 'false');  // optional
form.append('format', 'image');           // optional: raw, data_uri, image, css, css_full, markdown, json

const response = await fetch('https://www.base64-image.de/api/v1/encode', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
    body: form,
});

const data = await response.json();
console.log(data.name);          // "photo.jpg"
console.log(data.tokens_used);   // 1
console.log(data.output);        // formatted output (raw base64 by default)

PHP

$client = new \GuzzleHttp\Client();

$response = $client->post('https://www.base64-image.de/api/v1/encode', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
    ],
    'multipart' => [
        ['name' => 'image', 'contents' => fopen('photo.jpg', 'r')],
        ['name' => 'optimize-images', 'contents' => 'false'],  // optional
        ['name' => 'format', 'contents' => 'image'],           // optional
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['output'];       // formatted output (raw base64 by default)
echo $data['tokens_used'];  // 1

Python

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://www.base64-image.de/api/v1/encode',
        headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
        files={'image': f},
        data={'optimize-images': 'false', 'format': 'image'},  # both optional
    )

data = response.json()
print(data['name'])          # "photo.jpg"
print(data['tokens_used'])   # 1
print(data['output'][:50])   # formatted output (raw base64 by default)

Batch encode (up to 20 files)

cURL

curl -X POST https://www.base64-image.de/api/v1/encode/batch \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "images[]=@photo1.jpg" \
  -F "images[]=@photo2.png" \
  -F "images[]=@icon.svg" \
  -F "optimize-images=false"

JavaScript

const form = new FormData();
for (const file of fileInput.files) {
    form.append('images[]', file);
}
form.append('optimize-images', 'false');  // optional

const response = await fetch('https://www.base64-image.de/api/v1/encode/batch', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
    body: form,
});

const data = await response.json();
data.results.forEach(result => {
    if (result.error) {
        console.error(result.name, result.message);
    } else {
        console.log(result.name, result.tokens_used, 'tokens');
    }
});

PHP

$client = new \GuzzleHttp\Client();
$files = ['photo1.jpg', 'photo2.png', 'icon.svg'];

$multipart = [];
foreach ($files as $file) {
    $multipart[] = ['name' => 'images[]', 'contents' => fopen($file, 'r')];
}
$multipart[] = ['name' => 'optimize-images', 'contents' => 'false'];

$response = $client->post('https://www.base64-image.de/api/v1/encode/batch', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_TOKEN'],
    'multipart' => $multipart,
]);

$data = json_decode($response->getBody(), true);
foreach ($data['results'] as $result) {
    echo $result['name'] . ': ' . $result['tokens_used'] . " tokens\n";
}

Python

import requests

file_paths = ['photo1.jpg', 'photo2.png', 'icon.svg']
files = [('images[]', open(p, 'rb')) for p in file_paths]

response = requests.post(
    'https://www.base64-image.de/api/v1/encode/batch',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    files=files,
    data={'optimize-images': 'false'},  # optional
)

data = response.json()
for result in data['results']:
    if 'error' in result:
        print(f"Error: {result['name']} - {result['message']}")
    else:
        print(f"{result['name']}: {result['tokens_used']} tokens")

for _, fh in files:
    fh.close()

Check usage & balance

cURL

# Check token balance
curl https://www.base64-image.de/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# List API keys
curl https://www.base64-image.de/api/v1/tokens \
  -H "Authorization: Bearer YOUR_API_TOKEN"

JavaScript

const response = await fetch('https://www.base64-image.de/api/v1/usage', {
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
});
const balance = await response.json();

console.log(`Total: ${balance.total_remaining}`);
console.log(`API calls: ${balance.api_calls_this_month}`);

PHP

$client = new \GuzzleHttp\Client();

$response = $client->get('https://www.base64-image.de/api/v1/usage', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_TOKEN'],
]);

$balance = json_decode($response->getBody(), true);
echo "Total: {$balance['total_remaining']}\n";

Python

import requests

response = requests.get(
    'https://www.base64-image.de/api/v1/usage',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
)

balance = response.json()
print(f"Total: {balance['total_remaining']}")

API documentation

Authentication

Endpoints

Encode single image

Encode batch (up to 20 images)

Check usage

List tokens

Rate limits

Error codes

Code examples

Encode single file

Batch encode (up to 20 files)

Check usage & balance