Image Compress API Reference

Complete reference for the image compression endpoint — quality-based and target-size compression modes, parameters, and examples.

Endpoint

POST /api/v1/images/compress

Scope required: image

Request

Input Source

Same as Image Convert: file, image_url, or image_base64.

Compression Mode

Choose one of two modes:

Mode	Parameter	Description
Quality	`quality` (1–100)	Compress to a specific quality level
Target Size	`target_size_kb` (≥1)	Compress to approximate a target file size in KB

Note: Target size is best-effort — the response tells you whether it was reached.

Optional Parameters

Field	Type	Default	Description
`output_format`	String	Detected from input	`jpeg`, `png`, `webp`, `avif`. Defaults to input format if it is a supported output format.
`quality`	Integer (1–100)	80	Quality for quality-based mode
`target_size_kb`	Integer (≥1)	—	Target file size for target-size mode
`width`	Integer (1–10000)	—	Output width
`height`	Integer (1–10000)	—	Output height
`fit`	String	`inside`	`inside`, `cover`, `fill`
`preserve_metadata`	Boolean	`false`	Keep safe source metadata

Quality Mode Example

curl -X POST https://image-to-text.org/api/v1/images/compress \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "output_format=webp" \
  -F "quality=75"

Target Size Mode Example

curl -X POST https://image-to-text.org/api/v1/images/compress \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "output_format=jpeg" \
  -F "target_size_kb=200"

Response

Success (200)

{
  "success": true,
  "request_id": "req_abc...",
  "elapsed_ms": 450,
  "data": {
    "output": {
      "filename": "photo.webp",
      "content_type": "image/webp",
      "format": "webp",
      "width": 2400,
      "height": 1800,
      "size_bytes": 42300,
      "base64": "..."
    },
    "input": {
      "source": { "kind": "file", "name": "photo.png", "type": "image/png" },
      "format": "png",
      "width": 2400,
      "height": 1800,
      "size_bytes": 198500
    },
    "metrics": {
      "input_bytes": 198500,
      "output_bytes": 42300,
      "bytes_saved": 156200,
      "compression_ratio": 0.21
    },
    "compression": {
      "quality": 75,
      "target_size_kb": null,
      "target_reached": null,
      "quality_used": 75,
      "preserve_metadata": false
    },
    "usage": {
      "credits": 5,
      "pixel_workload": 4320000,
      "input_pixels": 4320000,
      "output_pixels": 4320000
    }
  }
}

Compression Metadata Fields

Field	Type	Description
`quality`	Integer\|null	Requested quality (quality mode)
`target_size_kb`	Integer\|null	Requested target size (target-size mode)
`target_reached`	Boolean\|null	Whether the target was met
`quality_used`	Integer\|null	Actual quality value used
`preserve_metadata`	Boolean	Whether metadata was preserved

The response includes the same output, input, metrics, and usage fields as the Convert endpoint.

Code Example

import requests

# Quality-based compression
response = requests.post(
    "https://image-to-text.org/api/v1/images/compress",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "image_url": "https://example.com/photo.png",
        "output_format": "webp",
        "quality": 75,
    },
)

# Target-size compression
response = requests.post(
    "https://image-to-text.org/api/v1/images/compress",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "image_url": "https://example.com/photo.png",
        "output_format": "jpeg",
        "target_size_kb": 200,
    },
)

data = response.json()
print(f"Saved: {data['data']['metrics']['bytes_saved']} bytes")
print(f"Credits used: {data['data']['usage']['credits']}")

Image Compress API Reference

On this page