API reference/16 of 24

Convert

Change format and compress in one request.

POST/convert

Turns images into another format and compresses them in the same step. For photos, switching format (especially to WebP or AVIF) often saves far more than same-format compress — sometimes 50–90% smaller with little or no visible difference.

Always returns the format you ask for, even when the result is bigger than the original (for example PNG or BMP from a photo). Prefer convert when you can choose the delivery format; use compress when you must keep JPEG-as-JPEG or PNG-as-PNG.

Takes the same options as compress. Animated GIF and WebP (up to 48 frames) stay animated when you ask for gif or webp. Any other format gets the first frame, and a multi-page TIFF or HEIC its first page.

Body (multipart/form-data)

  • files[]fileRequired

    1 or more images in any supported input format, up to your plan’s batch limit.

  • formatstringRequired

    Output format: webp, avif, jpeg (or jpg), png, gif, tiff (or tif), bmp or ico.

  • qualitystring | integer

    "balanced" (default), "high" or "smallest". Pro and Business can also send a number from 1 to 100. Images are encoded at exactly this quality.

  • target_kbinteger

    Pro and Business. Aim for a file size from 10 to 102400 KB: quality becomes a ceiling and is lowered step by step until each file fits.

  • losslessboolean

    Pro and Business. Pixel-perfect output for WebP, AVIF, PNG and TIFF. GIF uses a max 256-colour palette (not pixel-perfect). Not available for JPEG.

  • maxWidthinteger

    Shrink wider images to this width. 640 to 2560 px; values outside are moved into that range. Never enlarges.

  • maxHeightinteger

    Shrink taller images to this height. 480 to 2560 px, moved into range the same way. With maxWidth, images fit inside the box.

  • keep_metadataboolean

    Keep EXIF and color profile data. Defaults to false: metadata, including GPS location, is removed.

curl https://api.comprestack.com/api/v1/convert \
  -H "Authorization: Bearer $COMPRESTACK_API_KEY" \
  -F "files[]=@IMG_2041.heic" \
  -F "format=jpeg"
Response
{
  "id": "job_4f1c9a2e7b3d5c8f0a6e1b9d",
  "object": "job",
  "mode": "convert",
  "status": "done",
  "format": "jpeg",
  "files": [
    {
      "index": 0,
      "name": "IMG_2041.jpg",
      "original_size": 2913502,
      "size": 1688120,
      "saved_percent": 42.1,
      "unchanged": false,
      "width": 4032,
      "height": 3024,
      "format": "jpeg"
    }
  ],
  "created_at": "2026-10-17T10:42:08.114Z",
  "expires_at": "2026-10-17T11:42:08.114Z",
  "images_used": 1,
  "usage": {
    "plan": "pro",
    "images_used": 1285,
    "images_limit": 2500,
    "pack_images": 500,
    "remaining": 1215
  },
  "download_url": "/api/v1/jobs/job_4f1c9a2e7b3d5c8f0a6e1b9d/download?token=8c2f…e71a"
}