# Image Convert API

> Convert, resize, crop and analyse images: WebP, AVIF, JPEG, PNG and GIF.

Accepts an upload or a public URL, applies EXIF orientation, resizes with your chosen fit, optionally rotates, flips, blurs, sharpens or grayscales, strips all metadata and encodes to the format you ask for. `info=1` returns dimensions, format, transparency, orientation and a five-colour dominant palette instead of an image.

- **Endpoint:** `POST https://api.zactonz.com/image/`
- **Category:** Media
- **Version:** 1
- **Status:** stable
- **Authentication:** `Authorization: Bearer YOUR_API_KEY`
- **Reference page:** https://developers.zactonz.com/apis/image-convert/

## Parameters

Send parameters as `application/x-www-form-urlencoded` form fields in the request body.

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `file` | string | no |  | The image as a multipart upload. JPEG, PNG, GIF, WebP, AVIF or BMP, up to your plan's upload limit. |
| `url` | string | no |  | Public URL of the image instead of an upload. |
| `format` | enum | no | `webp` | Output format: `webp` (default), `avif`, `jpeg`, `png`, `gif`, or `keep` to keep the source format. Allowed values: `webp`, `avif`, `jpeg`, `png`, `gif`, `keep`. |
| `quality` | integer | no | `82` | 1 to 100 for lossy formats. |
| `width` | integer | no |  | Target width in pixels, up to 8000. Omit to derive from the height. |
| `height` | integer | no |  | Target height in pixels, up to 8000. Omit to derive from the width. |
| `fit` | enum | no | `inside` | `inside` (default, shrink to fit, never enlarge), `cover` (fill and crop), `contain` (fit with padding, see `background`) or `fill` (stretch). Allowed values: `inside`, `cover`, `contain`, `fill`. |
| `background` | string | no |  | Six hex digits used to flatten transparency and to pad `contain`. JPEG output is flattened on white when unset. |
| `rotate` | integer | no |  | Clockwise degrees, 0 to 359. EXIF orientation is always applied first. |
| `flip` | enum | no |  | `h`, `v` or `both`. Allowed values: `h`, `v`, `both`. |
| `grayscale` | boolean | no |  | `1` converts to grayscale. |
| `blur` | integer | no |  | Gaussian blur passes, 0 to 20. |
| `sharpen` | boolean | no |  | `1` applies a sharpening kernel. |
| `info` | boolean | no |  | `1` returns metadata and dominant colours as JSON without producing an image. |
| `resp` | enum | no | `image` | `image` streams the bytes with `X-Image-Width` and `X-Image-Height` headers. `json` stores the result for 24 hours and returns its link with the metadata. Allowed values: `image`, `json`. |

## Example request

```bash
curl -X POST "https://api.zactonz.com/image/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "url=https://zactonz.com/assets/images/logo.png" \
  --data-urlencode "format=webp" \
  --data-urlencode "quality=80" \
  --data-urlencode "width=800" \
  --data-urlencode "fit=inside" \
  --data-urlencode "resp=image"
```

## Response

OK

| Field | Type | Description |
|---|---|---|
| `status` | integer | `200` on success. |
| `data` | object | The result. |
| `data.source` | object | Dimensions, format, byte size, EXIF orientation, animation and alpha of the input. |
| `data.output` | object | Dimensions, format, byte size and quality of the result. Absent with `info=1`. |
| `data.colors` | object | With `info=1`: `dominant` list of `{hex, share}` and the `average` colour. |
| `data.image` | string | With `resp=json`: hosted link valid for 24 hours. |

```json
{
    "status": 200,
    "data": {
        "source": {
            "width": 1200,
            "height": 800,
            "format": "jpeg",
            "bytes": 184223,
            "orientation": 1,
            "animated": false,
            "alpha": false
        },
        "output": {
            "width": 800,
            "height": 533,
            "format": "webp",
            "bytes": 21874,
            "quality": 80
        }
    }
}
```

## Status codes

The outcome is reported in the JSON `status` field. General rules: https://developers.zactonz.com/apis/errors.md

| status | Meaning | Description |
|---|---|---|
| `400` | Bad request | No `file` upload and no `url` were sent, or a parameter is invalid. |
| `413` | Too large | The upload exceeds your plan's limit or the image exceeds 25 megapixels. |
| `415` | Unsupported | The bytes are not a JPEG, PNG, GIF, WebP, AVIF or BMP image. |
| `401` | Unauthorized | The Authorization header is missing or the key is not recognised. |
| `403` | Forbidden | The key is not licensed for this product. |
| `429` | Too many requests | The per-minute rate or the plan quota is exhausted. Retry after the seconds given in `Retry-After`. |

## Notes

Send the image as a `multipart/form-data` upload named `file`, or pass `url`. Images over 25 megapixels or 8000 pixels on a side are refused before decoding. SVG input is not accepted. Metadata is never carried over to the output.