Developer Reference

Photo-Editing & URL Transformation API

Instaimgr provides on-demand image processing, format optimization, and manipulation via URL paths and HTTP endpoints. Every parameter and endpoint documented below is implemented in img.php, index.php, and security.php.

API Endpoints

The service exposes four core endpoints for image ingestion, uploading, and on-the-fly transformations:

GET /img/{transforms}/originals/{filename}

Dynamic image transformation endpoint (Source: img.php, .htaccess). Chained transformation operations are applied to an existing original image on-the-fly. Returns the processed raster image stream with EXIF metadata stripped and HTTP caching headers.

GET /?url={remoteImageUrl}

Remote image fetch endpoint (Source: index.php, security.php). Ingests a public HTTP/HTTPS image URL with SSRF and decompression bomb validation. When invoked with format=json or header Accept: application/json, returns JSON status and asset details.

POST /

Direct image upload endpoint (Source: index.php). Accepts multipart/form-data with field image (binary raster file up to 10 MB). When submitted with format=json or Accept: application/json, returns JSON confirmation with stored asset URL.

POST /?action=upload_watermark

Watermark logo upload endpoint (Source: index.php). Accepts multipart/form-data with field logo (PNG/JPEG raster file up to 10 MB) for subsequent image watermark overlay transformations.

URL Structure & Chaining

Image operations are chained as slash-separated URL path segments pointing to an existing original image file in originals/ (replace 684ee6cca4e47.jpg with your uploaded filename):

Example Syntax

https://instaimgr.com/img/<operation1>/<operation2>/originals/<filename.ext>

Example URL (Live Asset in originals/)

https://instaimgr.com/img/resize800x600/format-webp/originals/684ee6cca4e47.jpg

Example Output Response Headers

HTTP/1.1 200 OK
Content-Type: image/webp
Cache-Control: public, max-age=31536000, immutable
X-Cache: HIT

Live Transform Endpoint Status

Ready to verify live transform endpoint: /img/resize800x600/format-webp/originals/684ee6cca4e47.jpg

Supported Operations

Operation	Segment Syntax	Parameters & Constraints
Crop	`crop<w>x<h>+<x>+<y>`	Crops rectangle of width × height at offset X, Y. Example: `crop300x200+10+10`
Resize (Exact)	`resize<w>x<h>`	Resizes to specified dimensions. Example: `resize640x480`
Width (Proportional)	`w<width>`	Scales width preserving aspect ratio. Example: `w400`
Height (Proportional)	`h<height>`	Scales height preserving aspect ratio. Example: `h300`
Circle Mask	`circle`	Applies centered elliptical/circle transparency mask. Example: `circle`
Rounded Corners	`round<radius>`	Rounds image corners by pixel radius (max 2000 px). Example: `round16`
Rotate	`rotate<degrees>`	Rotates by degrees (-360 to 360). Example: `rotate90`
Flip Horizontal	`flip-horizontal`	Mirrors the image horizontally.
Flip Vertical	`flip-vertical`	Mirrors the image vertically.
Blur	`blur<radius>`	Gaussian blur radius (1 to 100). Example: `blur8`
Sepia	`sepiaTone<amount>`	Sepia intensity (0 to 100). Example: `sepiaTone50`
Grayscale	`grayscale`	Converts color channels to monochrome grayscale.
Brightness	`brightness<amount>`	Adjusts brightness (-100 to 100). Example: `brightness15`
Contrast	`contrast<amount>`	Adjusts contrast (-100 to 100). Example: `contrast20`
Text Watermark	`watermark-<url_encoded_text>`	Overlays bottom-right text watermark (max 120 chars). Example: `watermark-Copyright%202026`
Image Watermark	`watermarkImage-<filename>`	Overlays logo uploaded in originals directory. Example: `watermarkImage-684ee6cca4e47.jpg`
Output Format	`format-<format>`	Target format: `png`, `webp`, `jpeg`, or `gif`. Example: `format-webp`

cURL Examples & Actual Response Formats

Test image operations and API responses directly from your terminal using these copyable cURL commands. Every response example below reflects real output generated by the live engine:

Example 1: Resize & Convert to WebP (HTTP 200)

curl -s -O -J "https://instaimgr.com/img/resize800x600/format-webp/originals/684ee6cca4e47.jpg"

Example Output Response Details

HTTP/1.1 200 OK
Content-Type: image/webp
Cache-Control: public, max-age=31536000, immutable
X-Cache: HIT
(Binary WebP raster stream; all EXIF, IPTC, and XMP metadata profiles stripped)

Example 2: Crop Rectangle & Rounded Corners (HTTP 200)

curl -s -O -J "https://instaimgr.com/img/crop400x400+50+50/round20/originals/684ee6cca4e47.jpg"

Example Output Response Details

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=31536000, immutable
X-Cache: HIT
(Crops rectangle at offset X:50, Y:50 and rounds corners with 20px radius)

Example 3: Direct Multipart Image Upload (Template — replace photo.jpg with your file)

curl -s -F "image=@photo.jpg" -F "format=json" "https://instaimgr.com/"

Example Output Response JSON

HTTP/1.1 200 OK
Content-Type: application/json

{"success":true,"filename":"684ee6cca4e47.jpg","url":"https://instaimgr.com/originals/684ee6cca4e47.jpg","width":200,"height":200,"format":"jpg"}

Example 4: Oversize Dimension Limit Exceeded (HTTP 400 JSON)

curl -s -i "https://instaimgr.com/img/resize99999x99999/originals/684ee6cca4e47.jpg"

Example Output Response JSON

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Requested resize dimensions exceed allowed limits (max 40 MP)."}

Example 5: Vector Format SVG Rejection (HTTP 400 JSON)

curl -s -i "https://instaimgr.com/?url=https://example.com/vector.svg&format=json"

Example Output Response JSON

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bad Request","message":"SVG files are not permitted. Allowed formats: JPG, PNG, GIF, WEBP."}

Example 6: Missing Original Image Asset (HTTP 404 Error Example)

curl -s -i "https://instaimgr.com/img/resize300x300/originals/nonexistent.jpg"

Example Output Response Details

HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8

Image not found.

Example 7: Private IP Rejection (HTTP 400 JSON) & Rate Limit Exceeded (HTTP 429 JSON after 20 req/min)

curl -s -i -H "Accept: application/json" "https://instaimgr.com/?url=http://127.0.0.1/test.jpg&format=json"

Example Output Response (Requests 1–20: HTTP 400 Bad Request; Request 21+ within 60s: HTTP 429 Too Many Requests)

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bad Request","message":"Access to private, loopback, link-local, or reserved IP ranges is forbidden."}

--- When repeated >20 times within 60 seconds ---
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{"error":"Too Many Requests","message":"Rate limit exceeded for remote URL fetches. Please wait a minute before trying again.","retry_after":60}

Operational Limits & Safeguards

To maintain system stability, requests are validated against technical constraints enforced in code:

Accepted Formats: JPEG, PNG, GIF, and WEBP raster files verified by magic byte signatures. Vector formats (SVG) are rejected (Source: security.php — instaimgr_validate_image_file()).
File Size Cap: Maximum uploaded or remote-fetched file size is 10 MB (Source: security.php — INSTAIMGR_MAX_BYTES = 10485760).
Resolution Cap: Maximum pixel volume is 40 megapixels (Source: security.php — INSTAIMGR_MAX_PIXELS = 40000000).
Single-Side Limit: Maximum width or height is 12,000 pixels (Source: security.php — INSTAIMGR_MAX_DIMENSION = 12000).
Privacy Protection: EXIF, IPTC, and XMP metadata profiles are stripped via Imagick::stripImage() before serving (Source: img.php, index.php).
Rate Limiting: Sliding-window rate limits apply per IP address across uploads (15/min), URL fetches (20/min), and uncached transformations (60/min), returning HTTP 429 with Retry-After: 60 (Source: security.php — instaimgr_check_rate_limit(), index.php, img.php).
Disk Cache & Retention: Transformed images are stored in cache/ with Cache-Control: public, max-age=31536000, immutable and pruned after 30 days (Source: img.php, cron_cleanup.php).

Open Console View Pricing