The core of SmallPict is its highly scalable image conversion API. You can use this endpoint to send raw images and receive optimized WebP or AVIF binaries in return.

Base URL

https://api.smallpict.com/v1

Convert Image

Endpoint: POST /plugin/convert

This endpoint accepts raw image binary data via a multipart/form-data request and processes it synchronously.

[!IMPORTANT] You must include your API key in the Authorization: Bearer <API_KEY> header. See the Authentication API guide for details.

Request Format

The request must be formatted as multipart/form-data.

Form Fields

Field	Type	Required	Description
image	File	Yes	The raw image file (JPEG, PNG). Max size 20MB.
format	String	No	Target format: webp (default) or avif.
quality	String	No	Compression level: lossy (default) or lossless.
max_width	Integer	No	Scale the image down to this width before processing.

Example Request (cURL)

curl -X POST https://api.smallpict.com/v1/plugin/convert \
  -H "Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxx" \
  -F "image=@/path/to/large-photo.jpg" \
  -F "format=webp" \
  -F "quality=lossy" \
  -o optimized-photo.webp

Response

Success (200 OK)

On success, the endpoint returns the raw binary data of the optimized image directly in the response body.

The API also includes useful statistics in the HTTP Response Headers:

• X-Original-Size: The file size (in bytes) of the uploaded image.
• X-Optimized-Size: The file size (in bytes) of the returned image.
• X-Savings-Percent: The percentage of data saved.

Error Responses

If the conversion fails, the API will return a JSON object detailing the error.

{
  "error": "Invalid format",
  "message": "The format 'gif' is not supported.",
  "code": "UNSUPPORTED_FORMAT"
}

See the Error Codes page for a complete list of potential errors.