Image Processing API Documentation

Documentation to help you integrate, and automate image processing with ease.

  • Home
  • Documentation

Overview

The Image Processing API enables users to resize, convert, and adjust the quality of image files, while ensuring secure access through API key authentication and preventing abuse with rate and size limits.

Endpoints

1. POST /v1/img/process

Processes an uploaded image file with options for resizing, format conversion, and quality adjustment.

  • Parameters

    • Headers:
      • api-key (required): API key for authentication.
    • Query Parameters:
      • file (required): The image file to process (max size: 10 MB).
      • width (optional): The desired width of the output image. Can be specified in pixels (e.g., 400) or percentage (e.g., 50%).
      • height (optional): The desired height of the output image. Can be specified in pixels or percentage.
      • format (optional): The target format for the output image. Supported formats include webp, jpg, jpeg, png, bmp, avif, tiff, gif, heic, and heif.
      • quality (optional): Compression level or quality of the output image. Valid values are between 0 and 100 (default is 100).

  • Example Request

    curl -X POST "https://api.bestimageapi.com/v1/img/process?width=50%&format=png&quality=80" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "file=@image-file.jpg" \
--output new-image-file.png

  • Response

    • Success (200 OK):
      • Returns the processed image file as a downloadable attachment.
    • Error:
      • 400 Bad Request: Invalid inputs (e.g., unsupported format, missing required parameters).
      • 413 Payload Too Large: File size exceeds 10 MB limit.
      • 403 Forbidden: Invalid or missing API key.
      • 429 Too Many Requests: Rate limit exceeded.
      • 500 Internal Server Error: Unexpected server error.

2. GET /v1/health

Checks the health status of the API service.

  • Parameters

    • Headers:
      • api-key (required): API key for authentication.

  • Example Request

    • curl -X GET "https://api.bestimageapi.com/v1/health" \
-H "api-key: YOUR_API_KEY"

  • Response

    • Success (200 OK)
    • Error:
      • 403 Forbidden: Invalid or missing API key.
      • 429 Too Many Requests: Rate limit exceeded.

Features

  • Resizing:

    • Adjusts the dimensions of the image based on provided width and/or height while maintaining aspect ratio if only one dimension is specified.

  • Format Conversion:

    • Converts images to supported formats such as PNG, JPEG, WebP, and more.

  • Quality Compression:

    • Compresses or optimizes images to a desired quality level.

Security

  • API Key Authentication:

    • All requests must include a valid API key in the api-key header.
    • Invalid or missing keys will result in a 403 Forbidden response.

  • Rate Limiting:

    • Up to 60 requests per minute.
    • Exceeding this limit will result in a 429 Too Many Requests response.

Error Handling

The API provides clear error messages and appropriate HTTP status codes:

  • 400 Bad Request

    • Invalid inputs or parameters.

  • 403 Forbidden

    • Unauthorized access due to missing or invalid API key.

  • 413 Payload Too Large

    • File size exceeds the 10 MB limit.

  • 429 Too Many Requests

    • Rate limit exceeded.

  • 500 Internal Server Error

    • Unexpected issues on the server side.

Supported Formats

The following image formats are supported:

  • Input: webp, jpg, jpeg, png, bmp, avif, tiff, gif, heif, heic.
  • Output: webp, jpg, jpeg, png, bmp, avif, tiff, gif, heif, heic.

Limitations

  • Maximum file size for uploads: 10 MB (Free trial is 1 MB).
  • Rate limit: Up to 60 requests per minute.
  • Requires at least one parameter (width, height, format, or quality) for processing requests.

Example Usage

  • Resizing an Image

    curl -X POST "https://api.bestimageapi.com/v1/img/process?width=400" \
-H "api-key: YOUR_API_KEY" \
-F "file=@image-file.jpg" \
--output new-image-file.jpg

  • Converting an Image Format

    curl -X POST "https://api.bestimageapi.com/v1/img/process?format=webp" \
-H "api-key: YOUR_API_KEY" \
-F "file=@image-file.jpg" \
--output new-image-file.webp

  • Adjusting Image Quality

    curl -X POST "https://api.bestimageapi.com/v1/img/process?quality=80" \
-H "api-key: YOUR_API_KEY" \
-F "file=@image-file.jpg" \
--output new-image-file.jpg

  • Combining Everything in a Single Request

    curl -X POST "https://api.bestimageapi.com/v1/img/process?quality=80&format=webp&width=400" \
-H "api-key: YOUR_API_KEY" \
-F "file=@image-file.jpg" \
--output new-image-file.webp

For issues or questions, please contact the BestImageAPI support team at support@bestimageapi.com.