---
title: "Resize, convert or compress an image"
method: POST
path: "/images"
tags: ["Images"]
---

# Resize, convert or compress an image

`POST /images`

## Request

- Base URL: `https://api.cofferdock.com`
- URL: `https://api.cofferdock.com/images`
- Auth: API key in header `x-api-key`

Resizes (with a fit mode), converts between JPEG/PNG/WebP/AVIF and/or compresses ONE image. Provide at least one of width, height, format or quality. Input formats: PNG, JPEG, WebP, AVIF, GIF, TIFF.

Costs 1 credit per call.

## Request body

- object
  - `file` string, byte, required: The image, base64-encoded.
  - `width` integer: Target width in pixels (1-8000). If you leave height empty, the aspect ratio is kept.
  - `height` integer: Target height in pixels (1-8000). If you leave width empty, the aspect ratio is kept.
  - `fit` 'cover' | 'contain' | 'fill' | 'inside' | 'outside': How to fit when both width and height are given.
  - `position` 'center' | 'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top' | 'entropy' | 'attention': Only affects fit=cover or fit=contain: which part of the image to keep. Use it to crop to a ratio without taking the center, e.g. fit=cover + position=top.
  - `format` 'jpeg' | 'png' | 'webp' | 'avif': Output format (default: same as input).
  - `quality` integer: Compression quality from 1 to 100 for lossy formats (JPEG, WebP): higher = better image and bigger file.
  - `output` 'json' | 'binary' | 'url' | 'image': How to return the image: "json" (base64 in the JSON response), "binary" (the image itself, ready for n8n/Make/Zapier) or "url" (a temporary download link, valid 15 minutes). Default: json when the request is JSON, binary when the input was sent raw.

## Response `200`

The resulting image (shape depends on `output`).

- union
  - object
    - `success` boolean
    - `image` string, byte
    - `mime_type` 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif'
    - `meta` object
      - `size_bytes` integer
      - `format` string
      - `width` integer
      - `height` integer
      - `original_format` string
      - `original_width` integer
      - `original_height` integer
      - `used` integer: Credits used this month, after this call.
      - `remaining` integer, nullable: Credits left this month (null = unlimited).
      - `unlimited` boolean
  - object: Returned when output=url: a temporary download link (valid 15 minutes).
    - `success` boolean
    - `url` string, uri: Temporary download link. Expires in 15 minutes.
    - `expires_at` string, date-time
    - `mime_type` string
    - `size_bytes` integer
    - `meta` object
      - `used` integer: Credits used this month, after this call.
      - `remaining` integer, nullable: Credits left this month (null = unlimited).
      - `unlimited` boolean

## Other responses

- `400`: Invalid input (nothing is charged).
- `401`: Missing or invalid API key.
- `403`: Email not verified.
- `429`: Monthly credit limit reached, or too many requests per minute for this key (see Retry-After).
- `503`: Server busy (queue full). Retry after the seconds in the Retry-After header.

---

[API](https://skmtc.dev/cofferdock/apis/cofferdock-api.md) · [All operations](https://skmtc.dev/cofferdock/apis/cofferdock-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cofferdock/apis/cofferdock-api/revisions/b57aa000d33a?raw)