POST /api/compress — compress and optimize images

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.

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.

Request

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

Parameters

Core

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.

string

default:"webp"

Output format. Accepted values: webp, avif, jpg, png.

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.

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.

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.

string

Custom identifier used to group results from the same session. If omitted, the API generates a random identifier automatically.

Watermark

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.

number

default:"20"

Watermark width as a percentage of the base image width. Accepted range: 5–50.

number

default:"80"

Watermark opacity from 0 (fully transparent) to 100 (fully opaque).

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)

AI features

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.

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.

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.

string

A short phrase describing the context of your images, used to improve AI output quality. Example: "ecommerce store selling sportswear".

string

Keywords to guide AI alt text and filename generation. Example: "running shoes men".

Example request

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.

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

Response fields

object[]

Array of optimized image results, one per successfully processed file.

Show properties

string

The original filename as provided in the request (e.g., photo.jpg).

string

The output filename with the new extension (e.g., photo.webp). If autoRenameSEO was enabled, this will be an AI-generated SEO filename.

number

Size of the original file in bytes.

number

Size of the optimized output file in bytes.

string

Signed URL to download the optimized image. This URL is temporary — download the file promptly after receiving it.

string

AI-generated alt text for the image. Only present when autoAltText is true and AI processing succeeds. Maximum 80 characters.

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:

{
  "error": "ia_not_available",
  "message": "AI features require a paid plan. Upgrade to Starter."
}

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

Overview

Endpoints

POST /api/compress — compress and optimize images

Request

Parameters

Core

Watermark

AI features

Example request

Response

200 OK

Response fields

Error codes

403 AI error response shape

​Request

​Parameters

​Core

​Watermark

​AI features

​Example request

​Response

​200 OK

​Response fields

​Error codes

​403 AI error response shape

Request

Parameters

Core

Watermark

AI features

Example request

Response

200 OK

Response fields

Error codes

403 AI error response shape