API Documentation

The imgfast API allows you to integrate image conversion into your applications. API access is available on the Pro plan.

Authentication

All API requests require an API key in the X-API-Key header.

X-API-Key: imgfast_your_api_key_here

Create API keys from your dashboard.

Convert Image

Upload and convert an image to a different format with advanced processing options.

POST /api/v1/convert

Basic Parameters (multipart/form-data)

Parameter	Type	Required	Description
`file`	File	Yes	Image file to convert
`output_format`	String	Yes	Target format (jpg, png, webp, avif, svg, gif, ico, tiff, pdf, heif, jxl, jp2)
`width`	Integer	No	Target width in pixels (max: 8000)
`height`	Integer	No	Target height in pixels (max: 8000)
`quality`	Integer	No	Quality (1-100, default: 80)
`compression`	String	No	`lossy` or `lossless` (default: lossy)
`resize_mode`	String	No	`preserve`, `stretch`, `crop`, or `contain` (default: preserve)

Advanced Parameters

Parameter	Type	Description
`trim`	Boolean	Automatically crop to visible pixels (removes uniform borders/padding)
`progressive`	Boolean	Enable progressive/interlaced encoding for better web performance (default: true)
`auto_rotate`	Boolean	Auto-rotate based on EXIF orientation (default: false)
`background_color`	String	Background color when removing transparency (hex format, e.g., #FFFFFF)
`dpi`	Integer	Set DPI for output image (1-600, default: 72)
`strip_metadata`	Boolean	Remove all metadata (EXIF, XMP, ICC) for privacy/size optimization
`keep_exif`	Boolean	Preserve EXIF metadata (camera info, GPS, etc.)
`keep_metadata`	Boolean	Preserve general metadata
`keep_xmp`	Boolean	Preserve XMP metadata
`keep_icc`	Boolean	Preserve ICC color profiles
`chroma_subsampling`	String	Chroma subsampling for JPEG/AVIF/JP2: `4:4:4` (best quality), `4:2:2` (balanced), `4:2:0` (smallest), `auto` (default)
`colourspace`	String	Output colourspace: `srgb` (default), `rgb`, `cmyk`, `lab`, `b-w` (grayscale)
`edits`	JSON String	Image editing operations (see Image Editing section)
`watermark`	JSON String	Watermark configuration (see Watermarking section)
`watermark_image`	File	Watermark image file (for image watermarks)

Example Request

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@image.jpg" \
  -F "output_format=webp" \
  -F "quality=90" \
  -F "width=800"

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Image conversion job created",
  "status_url": "/api/v1/status/550e8400-e29b-41d4-a716-446655440000",
  "download_url": "/api/v1/download/550e8400-e29b-41d4-a716-446655440000"
}

Image Editing

Apply advanced image editing operations using the edits parameter (JSON string).

Editing Operations

Operation	Type	Range	Description
`crop`	Object	{x, y, width, height}	Crop to specific region (pixels)
`rotate`	Integer	0, 90, 180, 270	Rotate image (degrees)
`flipH`	Boolean	-	Flip horizontally
`flipV`	Boolean	-	Flip vertically
`brightness`	Integer	-100 to 100	Adjust brightness
`contrast`	Integer	-100 to 100	Adjust contrast
`saturation`	Integer	-100 to 100	Adjust saturation
`hue`	Integer	-180 to 180	Adjust hue rotation
`blur`	Integer	0 to 100	Apply blur effect
`sharpen`	Integer	0 to 100	Apply sharpen effect
`grayscale`	Boolean	-	Convert to grayscale
`roundedCorners`	Object	{mode, value}	Apply rounded corners (see below)

Rounded Corners

The roundedCorners option supports three modes for different use cases:

Mode	Value Range	Description
`percent`	0-50	Corner radius as percentage of image (50 = circle/ellipse)
`pixels`	0-500	Corner radius in absolute pixels
`squircle`	1-100	Apple-style superellipse (1 = rectangular, 100 = ellipse-like)

Example: Image with Edits

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=webp" \
  -F "quality=85" \
  -F 'edits={"brightness":10,"contrast":15,"sharpen":25,"rotate":90}'

Example: Crop and Color Adjustments

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=jpg" \
  -F 'edits={"crop":{"x":100,"y":100,"width":800,"height":600},"saturation":20}'

Example: Rounded Corners (Percentage)

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=png" \
  -F 'edits={"roundedCorners":{"mode":"percent","value":20}}'

Example: Apple-Style Squircle

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@app-icon.png" \
  -F "output_format=png" \
  -F "width=512" \
  -F "height=512" \
  -F 'edits={"roundedCorners":{"mode":"squircle","value":60}}'

Tip: Use PNG or WebP output for rounded corners to preserve transparency.

Watermarking

Add text or image watermarks to protect your images using the watermark parameter.

Watermark Configuration

Property	Type	Required	Description
`type`	String	Yes	"text" or "image"
`text`	String	For text	Watermark text (max 100 chars)
`position`	String	Yes	"top-left", "top-right", "bottom-left", "bottom-right", "center"
`opacity`	Integer	Yes	0-100 (percentage)
`fontSize`	Integer	No	Font size in pixels (1-200, default: auto)
`fontColor`	String	No	Hex color (default: #FFFFFF)
`fontFamily`	String	No	Font family (default: Arial)

Example: Text Watermark

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=jpg" \
  -F 'watermark={"type":"text","text":"© 2025 MyBrand","position":"bottom-right","opacity":60,"fontColor":"#FFFFFF"}'

Example: Image Watermark

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "watermark_image=@logo.png" \
  -F "output_format=jpg" \
  -F 'watermark={"type":"image","position":"top-right","opacity":70}'

Advanced Examples

Complete Example: All Features Combined

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=webp" \
  -F "quality=85" \
  -F "width=1200" \
  -F "height=800" \
  -F "resize_mode=crop" \
  -F "progressive=true" \
  -F "auto_rotate=true" \
  -F "strip_metadata=true" \
  -F "chroma_subsampling=4:4:4" \
  -F "colourspace=srgb" \
  -F 'watermark={"type":"text","text":"© MyBrand","position":"bottom-right","opacity":60}' \
  -F 'edits={"brightness":10,"contrast":5,"sharpen":20,"roundedCorners":{"mode":"percent","value":10}}'

Example: Print-Ready Image (High DPI, Metadata Preserved)

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=jpg" \
  -F "quality=95" \
  -F "compression=lossless" \
  -F "dpi=300" \
  -F "keep_icc=true" \
  -F "keep_exif=true"

Example: Privacy-Focused Conversion

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=webp" \
  -F "quality=80" \
  -F "strip_metadata=true" \
  -F "auto_rotate=true"

Example: Contain Mode (Resize with Padding)

Resize images to exact dimensions with transparent or colored padding, perfect for uniform thumbnails or profile pictures without distortion.

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@portrait.jpg" \
  -F "output_format=png" \
  -F "width=500" \
  -F "height=500" \
  -F "resize_mode=contain" \
  -F "background_color=#FFFFFF"

Note: Without background_color, the padding will be transparent (for PNG, WebP, AVIF formats).

Example: Maximum Quality JPEG (Full Chroma)

Use chroma_subsampling=4:4:4 for maximum color fidelity in JPEG output.

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=jpg" \
  -F "quality=95" \
  -F "chroma_subsampling=4:4:4"

Example: Grayscale Conversion (B&W Colourspace)

Convert to true grayscale output using the b-w colourspace.

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=jpg" \
  -F "colourspace=b-w"

Example: CMYK for Print

Convert to CMYK colourspace for professional print workflows.

curl -X POST https://imgfast.com/api/v1/convert \
  -H "X-API-Key: imgfast_your_api_key" \
  -F "file=@photo.jpg" \
  -F "output_format=tiff" \
  -F "colourspace=cmyk" \
  -F "dpi=300" \
  -F "keep_icc=true"

Check Status

Check the status of a conversion job.

GET /api/v1/status/:job_id

Example Request

curl https://imgfast.com/api/v1/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: imgfast_your_api_key"

Response (Completed)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-10-18T12:00:00Z",
  "completed_at": "2025-10-18T12:00:05Z",
  "processing_time_ms": 1234,
  "output_format": "webp",
  "output_size_bytes": 45678,
  "download_url": "/api/v1/download/550e8400-e29b-41d4-a716-446655440000"
}

Download Image

Download the converted image.

GET /api/v1/download/:job_id

Example Request

curl https://imgfast.com/api/v1/download/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: imgfast_your_api_key" \
  -o converted.webp

Files are available for 24 hours after conversion.

Usage & Billing

The API has no rate limits. You can make as many API requests as you need.

API usage is charged at $0.01 per image on the Pro plan, billed monthly through Stripe.

Note: This is separate from your Pro plan's Web UI limit of 1000 images/day. Web UI uploads are included in your subscription, while API requests are billed separately.

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - API access requires Pro plan
`404`	Not Found - Job or file not found
`500`	Internal Server Error

Ready to get started?

Upgrade to Pro to access the API.

View Pricing