Image Processing API

Use Developer API Keys with the image scope to convert and compress one image per synchronous request. API requests consume Processing Credits, write Image API Request Logs, and return inline Base64 output.

Authentication

Send a Developer API Key with either header:

Authorization: Bearer sk_dev_...
# or
x-api-key: sk_dev_...

Keys must include the image API Scope. OCR-only keys are rejected.

Limits and Billing

• Input: JPEG, PNG, WebP, AVIF, GIF, or TIFF static image.
• Output: JPEG, PNG, WebP, or AVIF.
• Sources: multipart file, JSON image_url, or JSON image_base64.
• Limits: 25 MB input, 50 MP pixels, 20 MB raw output, 30 seconds.
• Billing: larger of input/output pixel count, minimum 1 Processing Credit.
• Metadata is stripped by default. Set preserve_metadata=true for best-effort preservation.

Convert

curl -X POST https://image-to-text.org/api/v1/images/convert \
  -H "Authorization: Bearer sk_dev_..." \
  -F "[email protected]" \
  -F "output_format=webp" \
  -F "width=1200" \
  -F "fit=inside"

The response includes data.output.base64, filename, content type, dimensions, size, data.metrics, and data.usage.

Compress

Quality compression:

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

Target-size compression:

curl -X POST https://image-to-text.org/api/v1/images/compress \
  -H "Authorization: Bearer sk_dev_..." \
  -H "Idempotency-Key: image-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "output_format": "jpeg",
    "target_size_kb": 200
  }'

Target-size compression is best effort. A successful response includes target_reached and quality_used.

Errors, Idempotency, and Rate Limits

All errors use:

{
  "success": false,
  "request_id": "...",
  "error": {
    "code": "invalid_input",
    "message": "...",
    "retryable": false
  }
}

Use Idempotency-Key for retry-safe billable requests. Exact replays within 24 hours return the stored response without another credit charge. Reusing the same key with different input or options returns idempotency_conflict. Image API daily limits and minimum request intervals are separate from OCR limits.

The unified OpenAPI contract is available at /api/v1/openapi.