Developer Docs

TL;DR: One conversion endpoint to rule them all.

Try it out

API Token

Image URL

Add Conversion Option

Select an optionHeightDevice Pixel RatioQualityPreserve AnimationFit ModeGravityFlipRotateBlurBrightnessContrastSaturationSharpenBackground Color

Width

Format

jpegjpgpngwebp

Final Conversion URL

Convert

Endpoints

Converting Images

GET https://api.picturething.com/convert/{options}/{url}

Converts and processes images with various options.

• options: A comma seperated string of key=value pairs. See below for conversion options
• url: The URL of the remote you want to convert. Use URL-encoding.

Authentication

To authenticate against any endpoint pass the API token as a header or as a query string parameter.

Authorization: Bearer APITOKEN

or

https://api.picturething.com/convert/width=800,format=webp/https%3A%2F%2Fexample.com%2Fimage.jpg?key=APITOKEN

Image Conversion Options

Note that aspect ratio is always preserved regardless of the mode.

Option	Type	Description	Valid Values
Basic Options
width	integer	Set output image width	1-4096 pixels
height	integer	Set output image height	1-4096 pixels
format	string	Output image format	jpeg, jpg, png, webp
quality	integer	Image quality	1-100
dpr	float	Device pixel ratio	0.1-4.0
Image Processing
blur	integer	Apply Gaussian blur	1-250
brightness	float	Adjust brightness	0.1-10.0
contrast	float	Adjust contrast	0.1-10.0
saturation	float	Adjust color saturation	0.1-10.0
sharpen	float	Apply sharpening	0.1-10.0
background	string	Set background color for transparent images	Hex color code without # (e.g. FF0000 or F00)
anim	boolean	Preserve animation frames	true/false
Image Transformations
fit	string	Affects interpretation of width and height. All resizing modes preserve aspect ratio.	scale-down: Similar to contain, but image is never enlarged. If image is larger than given dimensions, it will be resized. Otherwise original size is kept. contain: Image will be resized to be as large as possible within given dimensions while preserving aspect ratio. If only one dimension is provided, image will match that dimension exactly. cover: Resizes to fill entire area of width and height. If aspect ratio differs, image will be cropped to fit. crop: Image will be shrunk and cropped to fit within specified dimensions. Image will not be enlarged. For smaller images, same as scale-down. For larger images, same as cover.
flip	string	Flip image orientation	h: Flip horizontally. v: Flip vertically. hv: Flip both horizontally and vertically
gravity	string	Control image positioning	Basic positions: left, right, top, bottom, topleft, topright, bottomleft, bottomright, center, auto. Coordinates: x,y values (e.g. 0.5x0.5 for center)
rotate	integer	Rotate image	0-360 degrees
trim	string	Remove surrounding background	Format: “top;right;bottom;left” (e.g. 10;20;10;20)

Error Handling

The API will return validation errors for:

• Invalid option formats (must be key=value)
• Unknown options
• Values outside the allowed ranges
• Invalid formats for specific options
• Malformed input

Examples

Valid options:

width=800,height=600,format=webp
quality=80,dpr=2.0
fit=cover,gravity=center
background=#FF0000
trim=10;20;10;20

Invalid options:

width=5000  // Exceeds maximum width
format=gif  // Invalid format
background=red  // Not a hex color
trim=10,20,10,20  // Wrong separator

Conversion Credits

The same image with the same conversion setting is cached so does not cost another conversion credit.