API Documentation

Overview

Deflato API lets you compress images and generate AI images programmatically. Send an image, get a compressed version back. Simple.

Base URL: https://deflato.com/api/v1

Authentication: Authorization: Bearer YOUR_API_KEY

API access requires a Pro plan. Generate keys in your account.

POST/api/v1/compress

Compress a single image. Returns the compressed file as binary.

Parameter	Type	Default	Description
`file`	file	required	Image file (JPEG, PNG, WEBP, HEIC, TIFF, BMP, RAW)
`quality`	int	80	Output quality 1-100
`max_dimension`	int	0	Max width/height in px (0 = no resize)
`output_format`	string	JPEG	JPEG, PNG, WEBP, or AVIF
`strip_exif`	bool	true	Remove EXIF metadata

Example: cURL

curl -X POST https://deflato.com/api/v1/compress \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@photo.jpg" \ -F "quality=75" \ -F "output_format=WEBP" \ -F "max_dimension=1920" \ --output compressed.webp

Example: Python

import requests resp = requests.post( "https://deflato.com/api/v1/compress", headers={"Authorization": "Bearer YOUR_API_KEY"}, files={"file": open("photo.jpg", "rb")}, data={"quality": "75", "output_format": "WEBP"}, ) with open("compressed.webp", "wb") as f: f.write(resp.content) # resp.headers['Content-Length'] = compressed size

Example: JavaScript (Node.js)

const FormData = require('form-data'); const fs = require('fs'); const fetch = require('node-fetch'); const form = new FormData(); form.append('file', fs.createReadStream('photo.jpg')); form.append('quality', '75'); form.append('output_format', 'WEBP'); const resp = await fetch('https://deflato.com/api/v1/compress', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' }, body: form, }); fs.writeFileSync('compressed.webp', Buffer.from(await resp.arrayBuffer()));

POST/api/v1/info

Get compression info without downloading. Returns JSON with sizes, dimensions, savings.

Same parameters as /compress.

// Response: { "success": true, "input_size": 2456789, "output_size": 345678, "input_dimensions": [4032, 3024], "output_dimensions": [1920, 1440], "savings_percent": 86, "output_format": "WEBP" }

Rate Limits

Plan	Compress/day	AI Generate/day	Max file size
Free trial	20 total (lifetime)	3 total (lifetime)	50 MB
Pro ($7)	500	8	500 MB
Creator ($25)	500	15	500 MB
Business ($79)	500	50	500 MB
Day Pass ($2)	500	5	500 MB

Free users can create 1 API key with 20 lifetime requests to test the API. Upgrade to Pro or Creator for daily limits.

/api/v1/describe (AI alt-text) is free with no rate limit for all plans.

Supported Output Formats

Format	Extension	Best for
JPEG	.jpg	Photos, best compatibility
WEBP	.webp	Web — 25-30% smaller than JPEG
AVIF	.avif	Modern web — 40-50% smaller than JPEG
PNG	.png	Transparency, screenshots

POST/api/v1/compress-document

Compress images inside PDF, DOCX, PPTX, or XLSX. Text and layout stay intact. Unique — no other API offers this.

Parameter	Type	Default	Description
`file`	file	required	PDF, DOCX, PPTX, or XLSX file
`quality`	int	75	Image quality 1-100
`max_dimension`	int	1920	Max image dimension in px

Example: cURL

curl -X POST https://deflato.com/api/v1/compress-document \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@report.pdf" \ -F "quality=70" \ --output report_compressed.pdf

Example: Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.compress_document("report.pdf", quality=70) print(f"Saved {result.savings_percent}%")

`POST /api/v1/generate`

Generate an image from a text prompt using AI.

Request: JSON body

Parameter	Type	Default	Description
`prompt`	string	required	Text description of the image
`model`	string	photo	fast, photo, design, or icon
`aspect_ratio`	string	1:1	1:1, 16:9, 9:16, 4:3, etc.
`style`	string	any	Style for design/icon models
`resolution`	string	1K	1K, 2K, 4K (photo model only)
`output_format`	string	png	png or jpg

Response: Binary image file (PNG or JPEG)

curl -X POST https://deflato.com/api/v1/generate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"mountain landscape at sunset","model":"photo"}' \
  -o generated.png

Python:

from deflato import Deflato
client = Deflato("YOUR_KEY")
result = client.generate("mountain sunset", model="photo", format="jpg")
print(result.output_path)  # deflato-ai-1234567.jpg

Node.js:

const Deflato = require('deflato');
const client = new Deflato('YOUR_KEY');
const result = await client.generate('mountain sunset', { model: 'photo', format: 'jpg' });
console.log(result.outputPath);

Available styles for Design model:

digital_illustration, hand_drawn, pixel_art, 2d_art_poster, handmade_3d, grain, hand_drawn_outline, engraving_color, realistic_image, hdr, natural_light, studio_portrait, hard_flash, motion_blur

Available styles for Icon model:

line_art, line_circuit, engraving, linocut

POST/api/v1/describe

Generate an AI description (alt-text / caption) for an image. Useful for SEO and accessibility. Free — no rate limit.

Parameter	Type	Description
`file`	file	Image file (provide file OR image_url)
`image_url`	string	URL of the image (alternative to file upload)

Response: JSON

{ "description": "A golden retriever sitting on a beach at sunset with waves in the background" }

Example: cURL

curl -X POST https://deflato.com/api/v1/describe -H "Authorization: Bearer YOUR_API_KEY" -F "file=@photo.jpg"

Example: Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.describe(input_path="photo.jpg") print(result.description) # "A golden retriever sitting on a beach at sunset"

Example: Node.js

const Deflato = require("deflato"); const client = new Deflato("YOUR_API_KEY"); const result = await client.describe({ filePath: "photo.jpg" }); console.log(result.description); // or with URL: const r2 = await client.describe({ imageUrl: "https://example.com/photo.jpg" });

POST/api/v1/convert

Convert an image to a different format without additional compression. Uses quality=95 internally for minimal loss. Useful for HEIC→JPEG, PNG→WEBP, etc.

Same parameters as /compress but intended for format conversion rather than size reduction.

Example: cURL

curl -X POST https://deflato.com/api/v1/compress \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@photo.heic" \ -F "quality=95" \ -F "output_format=JPEG" \ --output photo.jpg

Example: Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.convert_format("photo.heic", output_format="JPEG") print(result.output_path) # photo.jpg

Example: Node.js

const Deflato = require("deflato"); const client = new Deflato("YOUR_API_KEY"); const result = await client.convertFormat("photo.heic", "JPEG"); console.log(result.outputPath); // photo.jpg

POST/api/v1/edit

Edit an existing image using AI instructions (img2img). Supports two models: fast (~10s, context-aware) and precise (~30s, higher quality). Uses same AI generation limits as /generate.

Parameter	Type	Default	Description
`file` or `image_url`	file/string	—	Image to edit (multipart file upload or URL)
`prompt`	string	—	Edit instructions (e.g. "add sunglasses", "change background to beach")
`model`	string	precise	fast or precise
`output_format`	string	png	png or jpg

Response: edited image (binary PNG/JPG file).

Example: cURL (with URL)

curl -X POST https://deflato.com/api/v1/edit \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://example.com/photo.jpg", "prompt": "add sunglasses", "model": "fast"}' \ --output edited.png

Example: cURL (file upload)

curl -X POST https://deflato.com/api/v1/edit \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@portrait.jpg" \ -F "prompt=change background to a sunset beach" \ -F "model=fast" \ --output edited.png

Example: Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.edit("add sunglasses", input_path="portrait.jpg", model="fast") print(result.output_path)

Example: Node.js

const Deflato = require("deflato"); const client = new Deflato("YOUR_API_KEY"); const result = await client.edit("add sunglasses", { filePath: "portrait.jpg", model: "fast" }); console.log(result.outputPath);

Error Codes

Code	Meaning
`401`	Invalid or missing API key
`403`	Pro plan required
`429`	Rate limit exceeded
`400`	No file provided or invalid parameters
`500`	Processing error

POST/api/v1/remove-bg

Remove background from an image. Two-step AI process: first replaces background with white, then removes it for clean transparent PNG. Requires Pro plan.

cURL

curl -X POST https://deflato.com/api/v1/remove-bg \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@photo.jpg" \ -o transparent.png

Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.remove_bg("photo.jpg", output="transparent.png") print(result.output_path, result.output_size)

Node.js

const Deflato = require('deflato'); const client = new Deflato('YOUR_API_KEY'); const result = await client.removeBg('photo.jpg');

Response

Binary PNG image with transparent background. Content-Type: image/png.

Takes 20-60 seconds depending on image complexity.

POST/api/v1/upscale

AI upscale — increase image resolution while keeping crisp details. Powered by Recraft Crisp Upscale. Requires Pro plan.

cURL

curl -X POST https://deflato.com/api/v1/upscale \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@small.jpg" \ -o upscaled.png

Python

from deflato import Deflato client = Deflato("YOUR_API_KEY") result = client.upscale("small.jpg", output="upscaled.png") print(result.output_path, result.output_size)

Node.js

const Deflato = require('deflato'); const client = new Deflato('YOUR_API_KEY'); const result = await client.upscale('small.jpg');

Response

Upscaled image (binary). Format matches input or PNG. Takes 10-30 seconds.

SDKs & Integrations

Python SDK

pip install deflato

from deflato import Deflato client = Deflato("YOUR_API_KEY") # Compress result = client.compress("photo.jpg", format="WEBP", quality=75) print(f"Saved {result.savings_percent}%") # Compress document result = client.compress_document("report.pdf", quality=70) # Convert format result = client.convert_format("photo.heic", output_format="JPEG") # AI generate result = client.generate("sunset over mountains", model="photo") # AI describe (free) result = client.describe(input_path="photo.jpg") print(result.description)

Node.js SDK

npm install deflato

MCP Server (AI Assistants)

Published on npm. One command setup:

# Claude Code: claude mcp add deflato npx mcp-server-deflato -e DEFLATO_API_KEY=your-key # Claude Desktop — add to config: { "mcpServers": { "deflato": { "command": "npx", "args": ["mcp-server-deflato"], "env": { "DEFLATO_API_KEY": "your-key" } } } }

Then ask your AI: "Compress all images in ./assets to WEBP"

npm: npmjs.com/package/mcp-server-deflato