API Documentation

Process images via REST: resize, compress, convert format, and more. Send a source (URL or upload), get back a URL to the processed image.

Overview

Every request sends an image source (URL, upload ID, or storage key). The API processes it and returns an asset ID and a URL where the result is available for a set time (default 24 hours). Use the quick endpoints for one job at a time, or Process Image for multiple steps in one call.

Quick reference — I want to…

Goal	Endpoint
Reduce file size (same dimensions)	POST /v1/compress
Change format (e.g. PNG → WebP)	POST /v1/convert
Hit a max file size (e.g. 150 KB)	POST /v1/compress-to-size
Resize to exact/proportional dimensions	POST /v1/resize
Only shrink if too big (dimensions or file size)	POST /v1/downsize
Resize + format + effects in one call	POST /v1/process
Use a preset (e.g. Instagram, LinkedIn)	POST /v1/packs/{packId}
Download the processed image	GET /v1/assets/{assetId}

Getting started

Base URL and authentication. All requests need the X-API-Key header; get your key from the dashboard after signup.

Base URL

https://api.imgstax.io/v1

Header

X-API-Key: YOUR_API_KEY

Note: You can revoke and create new API keys from the dashboard at any time.

How responses work

Every processing endpoint returns a JSON object with assetId, url, width, height, sizeBytes, format, and expiresAt. The url is where you (or your users) fetch the actual image file. It expires after the TTL (default 24 hours); after that, use GET /v1/assets/{assetId} only to get the image bytes, or you’ll get 404.

Quick endpoints

One job per request

Each quick endpoint does a single thing (compress, convert, resize, etc.) with a minimal request body. Same source (URL, uploadId, or storageKey) and same response shape (assetId, url, dimensions). For resize + format + effects in one call, use Process Image.

Output (optional)

Omit output to use defaults. output.ttlSeconds = how long the result URL is valid (default 86400 = 24h). After that, the asset URL returns 404.

Compress

POST /v1/compress

Compress an image with optional quality (default 80%). No resizing. Good for reducing file size while keeping dimensions.

Request

{
  "source": { "url": "https://example.com/image.jpg" },
  "quality": 80,
  "format": "Jpeg"
}

quality 1–100 (default 80). format Jpeg, Png, or Webp (default Jpeg). output is optional (see Output options above).

Example

curl -X POST "https://api.imgstax.com/v1/compress" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.jpg"},"quality":80}'

Convert format

POST /v1/convert

Convert an image to PNG, WebP, or JPEG. Optional quality for lossy formats (default 90).

Request

{
  "source": { "url": "https://example.com/image.png" },
  "format": "Webp",
  "quality": 90
}

format is required: Jpeg, Png, or Webp. output is optional.

Example

curl -X POST "https://api.imgstax.com/v1/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.png"},"format":"Webp"}'

Compress to size

POST /v1/compress-to-size

Compress the image to at or below a maximum file size in bytes. Ideal for ad platforms or strict size limits (e.g. 150 KB = 153600 bytes). Format must be Jpeg or WebP.

Request

{
  "source": { "url": "https://example.com/image.jpg" },
  "maxSizeBytes": 153600,
  "format": "Jpeg"
}

maxSizeBytes is required (e.g. 153600 for 150 KB). Quality is adjusted automatically. output is optional.

Example

curl -X POST "https://api.imgstax.com/v1/compress-to-size" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.jpg"},"maxSizeBytes":153600}'

Resize

POST /v1/resize

Resize to exact or proportional dimensions. Provide width and/or height. Fit modes: Cover, Contain, DownscaleOnly, FitBlurBackground. See Resize options for details.

Request

{
  "source": { "url": "https://example.com/image.jpg" },
  "width": 1200,
  "height": 630,
  "fit": "Cover",
  "gravity": "Center",
  "format": { "type": "Jpeg", "quality": 90 }
}

At least one of width or height is required. output is optional.

Example

curl -X POST "https://api.imgstax.com/v1/resize" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.jpg"},"width":800,"height":600}'

Downsize (if larger)

POST /v1/downsize

Only reduce size when the image exceeds your limits; never upscale. You can cap dimensions, file size, or both:

Dimension cap: maxWidth and maxHeight — resize only if the image is larger than these (e.g. “no image wider than 1920px”).
File size cap: maxSizeBytes — if the output would be larger than this (e.g. 10MB), compress down to this size. Use for “if higher than 10MB, compress to 10MB”. Format must be Jpeg or WebP.

Provide at least one: both dimension caps, or maxSizeBytes. Images already within the limits are returned unchanged (except optional format).

Request (dimension cap)

{
  "source": { "url": "https://example.com/image.jpg" },
  "maxWidth": 1920,
  "maxHeight": 1080,
  "format": { "type": "Jpeg", "quality": 85 }
}

Request (file size cap: if > 10MB, compress to 10MB)

{
  "source": { "url": "https://example.com/image.jpg" },
  "maxWidth": 0,
  "maxHeight": 0,
  "maxSizeBytes": 10485760,
  "format": { "type": "Jpeg" }
}

Use maxWidth: 0, maxHeight: 0 when you only want a file-size cap (no dimension change). 10485760 bytes = 10MB.

Examples

# Dimension cap only
curl -X POST "https://api.imgstax.com/v1/downsize" -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.jpg"},"maxWidth":1920,"maxHeight":1080}'

# File size cap: if larger than 10MB, compress to 10MB
curl -X POST "https://api.imgstax.com/v1/downsize" -H "X-API-Key: KEY" -H "Content-Type: application/json" \
  -d '{"source":{"url":"https://example.com/photo.jpg"},"maxWidth":0,"maxHeight":0,"maxSizeBytes":10485760}'

Full API

Process Image

POST /v1/process

Combine resize, format, effects, and output in one request. Use when you need multiple transformations, target file size, or full control. For a single operation, prefer the quick endpoints above.

Request body

{
  "source": {
    "url": "https://example.com/image.jpg"
  },
  "resize": {
    "width": 3000,
    "height": 2000,
    "fit": "Cover",
    "gravity": "Center"
  },
  "format": {
    "type": "Jpeg",
    "quality": 90,
    "compressionPriority": "Balanced",
    "targetFileSizeBytes": 153600
  },
  "effects": {
    "grayscale": false,
    "blurRadius": 0,
    "backgroundColor": "#FFFFFF"
  },
  "output": {
    "ttlSeconds": 86400,
    "public": true,
    "idempotencyKey": "optional-unique-key"
  },
  "metadata": {
    "userId": "123",
    "projectId": "abc"
  }
}

Target File Size Compression: Set targetFileSizeBytes (in bytes) to automatically compress the image to meet a specific file size. This is useful for ad platforms with maximum file size requirements. The system will adjust quality automatically. Works with JPEG and WebP formats. If specified, the quality parameter is ignored.

Response

{
  "assetId": "pypjKuCLnJ2YkJGBUcM1-EWK6RU8bQRhPrUy6_QoASA",
  "url": "https://api.imgstax.io/v1/assets/pypjKuCLnJ2YkJGBUcM1-EWK6RU8bQRhPrUy6_QoASA",
  "width": 3000,
  "height": 2000,
  "sizeBytes": 245678,
  "format": "Jpeg",
  "expiresAt": "2024-01-02T12:00:00Z",
  "mimeType": "image/jpeg",
  "metadata": {
    "userId": "123",
    "projectId": "abc"
  }
}

Examples

Basic

curl -X POST "https://api.imgstax.com/v1/process" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "url": "https://example.com/image.jpg"
    },
    "resize": {
      "width": 3000
    },
    "format": {
      "type": "Jpeg",
      "quality": 90
    }
  }'

Target file size

Compress an image to meet a specific file size (e.g., 150KB for ad platforms):

curl -X POST "https://api.imgstax.com/v1/process" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "url": "https://example.com/image.jpg"
    },
    "resize": {
      "width": 1200,
      "height": 630
    },
    "format": {
      "type": "Jpeg",
      "targetFileSizeBytes": 153600
    }
  }'

Process Pack

POST /v1/packs/{packId}

Process an image using a predefined pack of transformations for specific platforms (Instagram, LinkedIn, etc.).

Available packs

instagram-feed - Instagram feed posts
instagram-story - Instagram stories
tiktok - TikTok videos
youtube-thumbnail - YouTube thumbnails
twitter-post - X/Twitter posts
linkedin-post - LinkedIn posts
pinterest-pin - Pinterest pins

Request body

{
  "source": {
    "url": "https://example.com/image.jpg"
  },
  "output": {
    "ttlSeconds": 86400,
    "idempotencyKey": "optional-key"
  }
}

Example

curl -X POST "https://api.imgstax.com/v1/packs/instagram-feed" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "url": "https://example.com/image.jpg"
    }
  }'

Get Asset

GET /v1/assets/{assetId}

Fetch the processed image file by asset ID. Returns the image bytes; Content-Type matches the format (image/jpeg, image/png, image/webp). The url in the processing response is the same as this endpoint with the assetId.

Example

curl "https://api.imgstax.com/v1/assets/pypjKuCLnJ2YkJGBUcM1-EWK6RU8bQRhPrUy6_QoASA" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o output.jpg

Reference

Resize options

Properties

Property	Type	Description
width	number?	Target width in pixels. If only width is provided, height is calculated to maintain aspect ratio.
height	number?	Target height in pixels. If only height is provided, width is calculated to maintain aspect ratio.
fit	string	Resize mode: `Cover`, `Contain`, `FitBlurBackground`, `DownscaleOnly`
gravity	string	Position: `Center`, `Top`, `Bottom`, `Left`, `Right`, or corners

Fit modes

Cover

Fills the entire area, cropping if necessary to maintain aspect ratio.

Contain

Fits within the area, maintaining aspect ratio. Remaining space is filled with background color.

FitBlurBackground

Fits the image within the area, with remaining space filled by a blurred, upscaled version of the image.

DownscaleOnly

Only resizes if the image is larger than target dimensions. Never upscales.

Format options

Properties

Property	Type	Description
type	string	Image format: `Jpeg`, `Png`, `Webp`, `Avif`
quality	number?	Quality setting (1-100). Default: 90. Applies to JPEG and WebP.
compressionPriority	string	Compression priority: `Speed`, `Balanced`, `Quality`

Effects

Properties

Property	Type	Description
grayscale	boolean	Convert image to grayscale
blurRadius	number?	Gaussian blur radius (0-100)
backgroundColor	string?	Background color (hex format, e.g., "#FFFFFF" or "FFFFFF")
pad	object?	Padding options: `top`, `right`, `bottom`, `left`

Error handling

The API uses standard HTTP status codes to indicate success or failure.

Status codes

200 OK

Request successful

400 Bad Request

Invalid request parameters

401 Unauthorized

Missing or invalid API key

404 Not Found

Asset not found or expired

500 Internal Server Error

Server error during processing

Error response format

{
  "error": "Invalid Request",
  "message": "Source image size (60000000 bytes) exceeds maximum allowed size (52428800 bytes)",
  "code": "INVALID_REQUEST"
}

Rate limits

Rate limits are applied per API key to ensure fair usage and system stability.

Note: Rate limit details will be finalized before production launch. Limits will be communicated via response headers and documented here.

Response headers

X-RateLimit-Limit - Total requests allowed per window
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Time when the rate limit resets