Vipsac API Documentation

The Vipsac API allows you to transcode standard images into highly optimized, native AVIF binaries.

Authentication

The API uses API keys for authentication. Pass your secret key in the HTTP header of all requests.

• Header Name: X-API-Key
• Format: Keys are case-sensitive and prefixed with sk_live_ (e.g., X-API-Key: sk_live_...).

Endpoint: Transcode Image

Converts standard image formats (JPEG, PNG, WebP) into compressed, web-optimized AVIF files.

Request Details

• Method: POST
• URL: https://api.vipsac.dev/v1/transcode/image
• Content-Type: multipart/form-data

Request Body

Core Processing Behaviors

• Format & Quality: Output is strictly AVIF encoded at 80% quality.
• Privacy & Optimization: All image metadata (EXIF data) is automatically stripped to reduce file size and ensure privacy.
• Smart Resizing:
  • Images with a width greater than 1200px are automatically scaled down to a maximum width of 1200px (aspect ratio is preserved).
  • Images 1200px wide or smaller retain their original dimensions.

Code Examples

JavaScript / Node.js (Fetch API)

const formData = new FormData();
formData.append('image', imageFileBuffer);

const response = await fetch('https://api.vipsac.dev/v1/transcode/image', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_sk_live_key_here'
  },
  body: formData
});

if (response.ok) {
  const avifBuffer = await response.arrayBuffer();
  // Serve or upload to S3/R2
}

Python (Requests Library)

import requests

files = {'image': open('photo.jpg', 'rb')}
headers = {'X-API-Key': 'your_sk_live_key_here'}

response = requests.post('https://api.vipsac.dev/v1/transcode/image', headers=headers, files=files)

if response.status_code == 200:
    with open('optimized.avif', 'wb') as f:
        f.write(response.content)

Limits & Throttling

To ensure platform stability and prevent abuse, the following guardrails are strictly enforced:

1. Rate Limits (Token-Bucket)

• Sustained Rate: 5 requests per second (req/sec) per API key.
• Burst Capacity: Up to 10 concurrent requests allowed for short bursts.

2. File Size Limits by Tier

Payload sizes are evaluated at the edge. Any payload exceeding the absolute maximum of 30MB is dropped immediately.

3. Concurrency & Queueing

• The engine processes a maximum of 3 concurrent images at any given time.
• If the engine is busy, incoming requests are queued. If a request waits in the queue for more than 2 seconds, it is rejected to prevent CPU thrashing.

4. Dimensional Limits (Anti-Bomb Protection)

To protect the processing cores against malicious decompression bombs (e.g., heavily compressed files that expand to massive resolutions), the engine enforces a strict dimensional ceiling.

Any image with a width or height exceeding 5000 pixels will be instantly rejected with a 400 Bad Request before being allocated to memory.

Response Codes

Success (200)

Client Errors (4xx)

Server Errors (5xx)