API Documentation

Complete guide to using the Imgstax Image Processing API

Getting Started

Imgstax provides a RESTful API for processing images. All requests should be made to:

https://api.imgstax.com/v1

All requests must include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Note: For testing, you can use the development endpoint at http://localhost:5275/v1

Authentication

All API requests require authentication using an API key. You can obtain your API key from the dashboard after signing up.

Include your API key in the X-API-Key header of every request:

curl -X POST "https://api.imgstax.com/v1/process" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Process Image

Process a single image with custom transformations.

Endpoint

POST /v1/process

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"
  },
  "effects": {
    "grayscale": false,
    "blurRadius": 0,
    "backgroundColor": "#FFFFFF"
  },
  "output": {
    "ttlSeconds": 86400,
    "public": true,
    "idempotencyKey": "optional-unique-key"
  },
  "metadata": {
    "userId": "123",
    "projectId": "abc"
  }
}

Response

{
  "assetId": "pypjKuCLnJ2YkJGBUcM1-EWK6RU8bQRhPrUy6_QoASA",
  "url": "http://localhost:5275/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"
  }
}

Example

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
    }
  }'

Process Pack

Process an image using a predefined pack of transformations for specific platforms.

Endpoint

POST /v1/packs/{packId}

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

Retrieve a processed image by its asset ID.

Endpoint

GET /v1/assets/{assetId}

Response

Returns the processed image file directly. The content type will match the format (image/jpeg, image/png, image/webp).

Example

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

Resize Options

Properties

PropertyTypeDescription
widthnumber?Target width in pixels. If only width is provided, height is calculated to maintain aspect ratio.
heightnumber?Target height in pixels. If only height is provided, width is calculated to maintain aspect ratio.
fitstringResize mode: Cover, Contain, FitBlurBackground, DownscaleOnly
gravitystringPosition: 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

PropertyTypeDescription
typestringImage format: Jpeg, Png, Webp, Avif
qualitynumber?Quality setting (1-100). Default: 90. Applies to JPEG and WebP.
compressionPrioritystringCompression priority: Speed, Balanced, Quality

Effects

Properties

PropertyTypeDescription
grayscalebooleanConvert image to grayscale
blurRadiusnumber?Gaussian blur radius (0-100)
backgroundColorstring?Background color (hex format, e.g., "#FFFFFF" or "FFFFFF")
padobject?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