Image Convert API Reference

Complete reference for the image format conversion endpoint — request parameters, supported formats, resize options, and code examples.

Endpoint

POST /api/v1/images/convert

Scope required: image

Request

Headers

Header	Required	Description
`Authorization: Bearer <key>`	Yes*	API key with `image` scope
`x-api-key: <key>`	Yes*	Alternative to Bearer token
`Idempotency-Key`	No	Safe retry key

Input Source (choose one)

Field	Type	Source
`file`	Binary	File upload via multipart
`image_url`	String (URI)	Public HTTP/HTTPS URL
`image_base64`	String	Base64-encoded image content

When using the JSON body, use image_base64 (not base64 as in OCR). Provide mime_type and file_name for correct output.

Output Format

Field	Required	Values
`output_format`	Yes	`jpeg`, `png`, `webp`, `avif`

Optional Parameters

Field	Type	Default	Description
`quality`	Integer (1–100)	85 (jpeg), 80 (webp), 50 (avif)	Output quality. Higher = better quality, larger file. Ignored for PNG.
`width`	Integer (1–10000)	—	Output width in pixels
`height`	Integer (1–10000)	—	Output height in pixels
`fit`	String	`inside`	Resize behavior: `inside`, `cover`, `fill`
`preserve_metadata`	Boolean	`false`	Keep non-dangerous source metadata (EXIF, etc.)

Fit Modes

Mode	Behavior
`inside`	Scale to fit within width×height, preserving aspect ratio
`cover`	Scale to cover width×height, crop excess
`fill`	Stretch to exactly width×height

Example

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

Response

Success (200)

{
  "success": true,
  "request_id": "req_xyz...",
  "elapsed_ms": 320,
  "data": {
    "output": {
      "filename": "photo.webp",
      "content_type": "image/webp",
      "format": "webp",
      "width": 1200,
      "height": 900,
      "size_bytes": 48520,
      "base64": "/9j/4AAQ..."
    },
    "input": {
      "source": {
        "kind": "file",
        "name": "photo.jpg",
        "type": "image/jpeg"
      },
      "format": "jpeg",
      "width": 2400,
      "height": 1800,
      "size_bytes": 156200
    },
    "metrics": {
      "input_bytes": 156200,
      "output_bytes": 48520,
      "bytes_saved": 107680,
      "compression_ratio": 0.31
    },
    "usage": {
      "credits": 5,
      "pixel_workload": 4320000,
      "input_pixels": 4320000,
      "output_pixels": 1080000
    },
    "resize": {
      "width": 1200,
      "height": null,
      "fit": "inside"
    }
  }
}

Response Fields

Field	Type	Description
`data.output.base64`	String	Converted image as base64
`data.output.filename`	String	Sanitized output filename
`data.output.content_type`	String	MIME type of the output
`data.output.format`	String	Output format (`jpeg`, `png`, `webp`, `avif`)
`data.output.width` / `height`	Integer	Output dimensions
`data.output.size_bytes`	Integer	Output file size
`data.input`	Object	Source image metadata
`data.metrics`	Object	Size comparison (input/output bytes, bytes saved, ratio)
`data.usage`	Object	Billing info (credits, pixel workload)
`data.resize`	Object	Applied resize (or `null`)

Supported Conversions

From ↓ / To →	JPEG	PNG	WebP	AVIF
JPEG	✅	✅	✅	✅
PNG	✅	✅	✅	✅
WebP	✅	✅	✅	✅
AVIF	✅	✅	✅	✅
GIF	✅	✅	✅	✅
TIFF	✅	✅	✅	✅

GIF and TIFF are accepted as input only (static, first frame/image).

Code Example

import requests

response = requests.post(
    "https://image-to-text.org/api/v1/images/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"file": open("photo.png", "rb")},
    data={
        "output_format": "webp",
        "quality": "85",
        "width": "1200",
        "fit": "inside",
    },
)

data = response.json()
if data["success"]:
    import base64
    with open("output.webp", "wb") as f:
        f.write(base64.b64decode(data["data"]["output"]["base64"]))

Image Convert API Reference

On this page