API Reference — PixShift

Quick Start

Get your first API call working in under 5 minutes.

1Register at pixshift.com/register
2Log in → go to API Keys → create a key → copy it immediately. It is shown once only.
3Make your first call — convert a PNG to WebP:
4Check your usage at the dashboard.

curl -X POST https://pixshift.com/api/v1/convert \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "target_format=webp" \
  --output converted.webp

Overview

The PixShift API converts, compresses, and resizes images via simple HTTP requests. Send a file, get a file back. No SDKs required.

Base URL	https://pixshift.com/api/v1
Current version	v1 — included in the URL path
Request format	multipart/form-data for all image endpoints
Success response	{ "success": true, "data": { … } }
Error response	{ "success": false, "error": { "message": "…", "code": "…" } }
Image response	Binary image body with Content-Type header — not JSON

Breaking changes will increment the version to v2. The v1 endpoint will remain available with advance notice before any deprecation.

Authentication

Image endpoints use API key authentication. Create a key in your dashboard, then include it in every request:

X-API-Key: pxs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key format: pxs_live_ prefix followed by 32 random hex characters.

Security rules: Store the key in an environment variable, never in source code. The raw key is shown once at creation — if lost, revoke it and create a new one. If a key is compromised, revoke it immediately from the dashboard.

Limits

Max file size	4 MB
Accepted input formats	JPEG, PNG, WebP, AVIF, GIF
Accepted output formats	JPEG, PNG, WebP, AVIF
GIF as output	Not supported — GIF can only be used as input

Format is detected from the file's content (magic bytes), not the file extension. Renaming a JPEG to .png will not change how it is processed.

POST/api/v1/convert

Convert an image from one format to another. Supports JPEG, PNG, WebP, AVIF, and GIF as input; JPEG, PNG, WebP, and AVIF as output.

Auth:X-API-Key header

Request — multipart/form-data

Field	Type	Required	Description
file	File	Yes	The image to convert. Max 4 MB.
target_format	string	Yes	Output format. One of: png, jpg, webp, avif.

Response

Binary image. Content-Type is set to the target format's MIME type.

png → image/png · jpg → image/jpeg · webp → image/webp · avif → image/avif

curl -X POST https://pixshift.com/api/v1/convert \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "target_format=webp" \
  --output converted.webp

Errors

Code	HTTP	Meaning
UNAUTHORIZED	401	Missing or invalid API key
VALIDATION_ERROR	400	file or target_format missing, invalid target_format value, or request is not multipart/form-data
FILE_TOO_LARGE	413	File exceeds 4 MB
UNSUPPORTED_MEDIA_TYPE	415	File content not recognised as a supported format
INTERNAL_ERROR	500	Conversion failed on the server

POST/api/v1/compress

Compress an image to reduce file size. Output stays in the same format as the input — only file size changes, not the format.

Auth:X-API-Key header

Request — multipart/form-data

Field	Type	Required	Description
file	File	Yes	The image to compress. Max 4 MB.
quality	integer	Yes	1 (smallest file) to 100 (best quality). Recommended: 75–85.

Response

Binary image in the same format as the input. Content-Type matches the input MIME type.

curl -X POST https://pixshift.com/api/v1/compress \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/photo.jpg" \
  -F "quality=80" \
  --output compressed.jpg

Errors

Code	HTTP	Meaning
UNAUTHORIZED	401	Missing or invalid API key
VALIDATION_ERROR	400	file or quality missing, or quality not in range 1–100
FILE_TOO_LARGE	413	File exceeds 4 MB
UNSUPPORTED_MEDIA_TYPE	415	File content not recognised as a supported format
INTERNAL_ERROR	500	Compression failed on the server

POST/api/v1/resize

Resize an image to specific dimensions. Output stays in the same format as the input.

Auth:X-API-Key header

Request — multipart/form-data

Field	Type	Required	Default	Description
file	File	Yes	—	The image to resize. Max 4 MB.
width	integer	Yes	—	Target width in pixels. Range: 1–5000.
height	integer	Yes	—	Target height in pixels. Range: 1–5000.
keep_aspect_ratio	"true" \| "false"	No	"true"	When true, image is fit within the box without distortion.

Aspect ratio behaviour: When keep_aspect_ratio is true (the default), the image is scaled to fit within the specified box without distortion. Example: a 1000×500 image resized to 400×400 produces 400×200 — width fills the box, height scales proportionally. When false, the image is stretched to exactly the requested dimensions.

Response

Binary image in the same format as the input. Content-Type matches the input MIME type.

curl -X POST https://pixshift.com/api/v1/resize \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/image.png" \
  -F "width=800" \
  -F "height=600" \
  -F "keep_aspect_ratio=true" \
  --output resized.png

Errors

Code	HTTP	Meaning
UNAUTHORIZED	401	Missing or invalid API key
VALIDATION_ERROR	400	file, width, or height missing; dimensions outside 1–5000
FILE_TOO_LARGE	413	File exceeds 4 MB
UNSUPPORTED_MEDIA_TYPE	415	File content not recognised as a supported format
INTERNAL_ERROR	500	Resize failed on the server

Error Reference

Every error response shares the same shape, regardless of which endpoint returned it.

{
  "success": false,
  "error": {
    "message": "Human-readable explanation",
    "code": "MACHINE_READABLE_CODE"
  }
}

Code	HTTP	Meaning
VALIDATION_ERROR	400	A required field is missing, a value is out of range, or the request body is malformed
UNAUTHORIZED	401	No API key in the header, or the key is invalid or revoked
FORBIDDEN	403	Authenticated but not permitted to access this resource
NOT_FOUND	404	The requested resource does not exist
CONFLICT	409	Resource already exists
FILE_TOO_LARGE	413	File exceeds the 4 MB limit
UNSUPPORTED_MEDIA_TYPE	415	File type not accepted — see Limits section for supported formats
RATE_LIMITED	429	Reserved for future rate limiting — not currently triggered
INTERNAL_ERROR	500	Something went wrong on the server — try again or contact support

Common Mistakes

1
Setting Content-Type manually
Do not set the Content-Type header yourself when sending multipart/form-data. The browser and fetch set it automatically with the required boundary value. Setting it manually breaks the request.
2
Parsing the response as JSON
Image endpoints return a binary image body, not JSON. Read the response with .blob() in JavaScript or res.content in Python — not .json().
3
Trusting the file extension
The API detects format from the file's bytes, not the name. A file called image.png that contains JPEG data is treated as JPEG.
4
Losing the API key
The raw key is shown once, at creation. If it is not saved immediately, it cannot be recovered. Revoke it and create a new one.