> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluximage.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/compress — compress and optimize images

> Compress, convert, resize, watermark, and AI-enhance up to 20 images per request using multipart/form-data. Returns signed download URLs per image.

Send one or more image files to this endpoint to compress and optimize them. You can control output format, quality, dimensions, watermarking, and AI features such as alt text generation and SEO filename renaming. The endpoint processes all files in a batch and returns a signed download URL for each optimized image.

<Note>
  Watermarking and AI features (auto alt text and SEO rename) require a paid plan. Attempting to use these features on a free plan returns a `403` error.
</Note>

## Request

**Method:** `POST`\
**URL:** `https://fluximage.app/api/compress`\
**Content-Type:** `multipart/form-data`\
**Authorization:** `Bearer flx_live_your_key_here`

### Parameters

#### Core

<ParamField path="file" type="File" required>
  Image file to optimize. Repeat this field to include multiple files in a single request. Maximum **20 files** per batch; each file must not exceed **20 MB**.
</ParamField>

<ParamField path="format" type="string" default="webp">
  Output format. Accepted values: `webp`, `avif`, `jpg`, `png`.
</ParamField>

<ParamField path="quality" type="number" default="82">
  Compression quality, from `40` to `100`. Higher values produce larger files with better fidelity. Applies to `webp`, `avif`, and `jpg` outputs; PNG uses lossless compression regardless of this value.
</ParamField>

<ParamField path="maxWidth" type="number">
  Maximum output width in pixels. The image is scaled down proportionally if it exceeds this value. Images smaller than this value are not enlarged.
</ParamField>

<ParamField path="maxHeight" type="number">
  Maximum output height in pixels. The image is scaled down proportionally if it exceeds this value. Images smaller than this value are not enlarged.
</ParamField>

<ParamField path="sessionId" type="string">
  Custom identifier used to group results from the same session. If omitted, the API generates a random identifier automatically.
</ParamField>

#### Watermark

<ParamField path="watermarkFile" type="File">
  PNG image to overlay as a watermark on every processed file. Requires a paid plan. If you are on the free plan, this field is ignored.
</ParamField>

<ParamField path="watermarkScale" type="number" default="20">
  Watermark width as a percentage of the base image width. Accepted range: `5`–`50`.
</ParamField>

<ParamField path="watermarkOpacity" type="number" default="80">
  Watermark opacity from `0` (fully transparent) to `100` (fully opaque).
</ParamField>

<ParamField path="watermarkPosition" type="string" default="BR">
  Position of the watermark on the image. Accepted values:

  | Value | Position               |
  | ----- | ---------------------- |
  | `TL`  | Top left               |
  | `TC`  | Top center             |
  | `TR`  | Top right              |
  | `ML`  | Middle left            |
  | `MC`  | Middle center          |
  | `MR`  | Middle right           |
  | `BL`  | Bottom left            |
  | `BC`  | Bottom center          |
  | `BR`  | Bottom right (default) |
</ParamField>

#### AI features

<ParamField path="autoAltText" type="boolean" default="false">
  When `true`, the API uses AI to generate an SEO-optimized alt text string for each image. Requires a paid plan and available AI credits. Each image consumes one AI credit.
</ParamField>

<ParamField path="autoRenameSEO" type="boolean" default="false">
  When `true`, the API uses AI to generate an SEO-friendly filename for each image (lowercase words joined by hyphens). Requires a paid plan and available AI credits. Enabling both `autoAltText` and `autoRenameSEO` still consumes only **one AI credit per image**, not two.
</ParamField>

<ParamField path="language" type="string" default="English">
  Language used for AI-generated alt text and filenames. Accepted values: `English`, `Español`, `Català`, `Français`, `Deutsch`, `Italiano`, `Português`, `Nederlands`, `Polski`, `Русский`, `中文`, `日本語`, `한국어`, `Arabic`, `Hindi`.
</ParamField>

<ParamField path="aiContext" type="string">
  A short phrase describing the context of your images, used to improve AI output quality. Example: `"ecommerce store selling sportswear"`.
</ParamField>

<ParamField path="seoKeywords" type="string">
  Keywords to guide AI alt text and filename generation. Example: `"running shoes men"`.
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://fluximage.app/api/compress \
  -H "Authorization: Bearer flx_live_your_key_here" \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
  -F "format=webp" \
  -F "quality=82" \
  -F "autoAltText=true" \
  -F "language=English" \
  -F "seoKeywords=product photography"
```

## Response

### 200 OK

Returns a JSON object with a `data` array. Each element corresponds to one successfully optimized image.

```json theme={null}
{
  "data": [
    {
      "originalName": "photo.jpg",
      "newName": "photo.webp",
      "originalSize": 524288,
      "optimizedSize": 98304,
      "downloadUrl": "https://...",
      "altText": "Red running shoes on a white background"
    }
  ]
}
```

#### Response fields

<ResponseField name="data" type="object[]">
  Array of optimized image results, one per successfully processed file.

  <Expandable title="properties">
    <ResponseField name="originalName" type="string">
      The original filename as provided in the request (e.g., `photo.jpg`).
    </ResponseField>

    <ResponseField name="newName" type="string">
      The output filename with the new extension (e.g., `photo.webp`). If `autoRenameSEO` was enabled, this will be an AI-generated SEO filename.
    </ResponseField>

    <ResponseField name="originalSize" type="number">
      Size of the original file in bytes.
    </ResponseField>

    <ResponseField name="optimizedSize" type="number">
      Size of the optimized output file in bytes.
    </ResponseField>

    <ResponseField name="downloadUrl" type="string">
      Signed URL to download the optimized image. This URL is temporary — download the file promptly after receiving it.
    </ResponseField>

    <ResponseField name="altText" type="string">
      AI-generated alt text for the image. Only present when `autoAltText` is `true` and AI processing succeeds. Maximum 80 characters.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error codes

| Status | Error                                 | Description                                                                  |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------- |
| `400`  | `Maximum 20 images allowed per batch` | The request includes more than 20 files.                                     |
| `400`  | `File <name> exceeds the 20MB limit`  | One or more files exceed the 20 MB per-file limit.                           |
| `401`  | `Unauthorized`                        | The API key is missing or invalid.                                           |
| `403`  | *(plan limit message)*                | Your plan's monthly compression limit has been reached.                      |
| `403`  | `ia_not_available`                    | AI features require a paid plan. Upgrade to Starter or higher.               |
| `403`  | `no_credits`                          | You have used all your AI credits this month. Purchase a top-up to continue. |
| `500`  | *(message)*                           | An unexpected server error occurred.                                         |

### 403 AI error response shape

When an AI feature is blocked, the response includes both `error` and `message` fields:

```json theme={null}
{
  "error": "ia_not_available",
  "message": "AI features require a paid plan. Upgrade to Starter."
}
```

```json theme={null}
{
  "error": "no_credits",
  "message": "You have used all your AI credits this month. Purchase a top-up to continue."
}
```