Skip to main content

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.

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
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.
​
format
string
default:"webp"
Output format. Accepted values: webp, avif, jpg, png.
​
quality
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.
​
maxWidth
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.
​
maxHeight
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.
​
sessionId
string
Custom identifier used to group results from the same session. If omitted, the API generates a random identifier automatically.

​
Watermark

​
watermarkFile
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.
​
watermarkScale
number
default:"20"
Watermark width as a percentage of the base image width. Accepted range: 5–50.
​
watermarkOpacity
number
default:"80"
Watermark opacity from 0 (fully transparent) to 100 (fully opaque).
​
watermarkPosition
string
default:"BR"
Position of the watermark on the image. Accepted values:
ValuePosition
TLTop left
TCTop center
TRTop right
MLMiddle left
MCMiddle center
MRMiddle right
BLBottom left
BCBottom center
BRBottom right (default)

​
AI features

​
autoAltText
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.
​
autoRenameSEO
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.
​
language
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.
​
aiContext
string
A short phrase describing the context of your images, used to improve AI output quality. Example: "ecommerce store selling sportswear".
​
seoKeywords
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

​
data
object[]
Array of optimized image results, one per successfully processed file.

​
Error codes

StatusErrorDescription
400Maximum 20 images allowed per batchThe request includes more than 20 files.
400File <name> exceeds the 20MB limitOne or more files exceed the 20 MB per-file limit.
401UnauthorizedThe API key is missing or invalid.
403(plan limit message)Your plan’s monthly compression limit has been reached.
403ia_not_availableAI features require a paid plan. Upgrade to Starter or higher.
403no_creditsYou 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."
}