API Documentation

Integrate Pixelgar's powerful image and text processing tools into your applications with our RESTful API.

Introduction

The Pixelgar API provides programmatic access to our suite of image and text processing tools. With our API, you can integrate powerful image manipulation and text processing capabilities directly into your applications, websites, or workflows.

Base URL

https://api.pixelgar.com/v1

All API requests should be made to this base URL, followed by the specific endpoint for the tool you want to use.

Request Format

The API accepts requests in the following formats:

  • For simple parameters: URL query parameters
  • For complex data: JSON in the request body
  • For file uploads: multipart/form-data

Response Format

All responses are returned in JSON format with the following structure:

{ "success": true, "data": { // Response data specific to the endpoint }, "meta": { // Metadata about the request/response } }

In case of an error, the response will have the following structure:

{ "success": false, "error": { "code": "error_code", "message": "Human-readable error message", "details": { // Additional error details if available } } }

Authentication

API Key Authentication

All API requests require authentication using an API key. You can obtain an API key by signing up for a Pixelgar developer account.

Using Your API Key

Include your API key in the request headers:

X-API-Key: your_api_key_here

Alternatively, you can include it as a query parameter:

https://api.pixelgar.com/v1/image/resize?api_key=your_api_key_here

Security Note

We recommend using the header method for production applications as it's more secure than including the API key in the URL.

Rate Limits

Default Rate Limits

To ensure fair usage and system stability, API requests are subject to rate limiting.

Rate Limit Tiers

Plan Rate Limit Daily Quota
Free 60 requests per minute 1,000 requests per day
Basic 300 requests per minute 10,000 requests per day
Pro 1,200 requests per minute 100,000 requests per day
Enterprise Custom Custom

Rate Limit Headers

Each API response includes headers that provide information about your current rate limit status:

X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 1617981234

These headers indicate:

  • X-RateLimit-Limit: The maximum number of requests you can make per minute
  • X-RateLimit-Remaining: The number of requests remaining in the current window
  • X-RateLimit-Reset: The time at which the current rate limit window resets (Unix timestamp)

Error Handling

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:

Status Code Description
200 OK The request was successful
400 Bad Request The request was invalid or missing required parameters
401 Unauthorized Authentication failed or API key is missing
403 Forbidden The API key doesn't have permission to perform the request
404 Not Found The requested resource doesn't exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error An error occurred on the server

Error Codes

In addition to HTTP status codes, the API returns specific error codes in the response body to provide more detailed information about what went wrong:

{ "success": false, "error": { "code": "invalid_parameter", "message": "The 'width' parameter must be a positive integer", "details": { "parameter": "width", "value": "-100" } } }

Image Resizer API

Resize an Image

Resize an image to specific dimensions while maintaining or adjusting its aspect ratio.

POST /image/resize

Request Parameters

Parameter Type Description
image Required File The image file to resize (JPEG, PNG, GIF, WebP)
width Optional Integer Target width in pixels. At least one of width or height must be provided.
height Optional Integer Target height in pixels. At least one of width or height must be provided.
maintain_aspect_ratio Optional Boolean Whether to maintain the original aspect ratio. Default: true
format Optional String Output format (jpeg, png, webp). Default: same as input
quality Optional Integer Output quality (1-100, only applies to jpeg and webp). Default: 90

Response

{ "success": true, "data": { "url": "https://cdn.pixelgar.com/processed/abc123.jpg", "width": 800, "height": 600, "format": "jpeg", "size": 45678 }, "meta": { "processing_time": 0.235 } }

Example Request

curl -X POST https://api.pixelgar.com/v1/image/resize \ -H "X-API-Key: your_api_key_here" \ -F "image=@photo.jpg" \ -F "width=800" \ -F "height=600" \ -F "format=webp"

Client Libraries

To make integration easier, we provide official client libraries for several popular programming languages.

JavaScript

Official JavaScript/Node.js client for the Pixelgar API. Compatible with browsers and Node.js environments.

View on GitHub →

Python

Python client library for the Pixelgar API. Supports Python 3.6+ with async/await support.

View on GitHub →

PHP

PHP client for the Pixelgar API. Compatible with PHP 7.2+ and includes Laravel integration.

View on GitHub →

Ruby

Ruby gem for the Pixelgar API. Includes Rails integration and supports Ruby 2.5+.

View on GitHub →

Webhooks

For long-running operations, you can use webhooks to receive notifications when processing is complete.

Setting Up Webhooks

To use webhooks, provide a webhook_url parameter with any API request. When the operation completes, we'll send a POST request to your webhook URL with the results.

Example Webhook Payload

{ "event": "image.resize.completed", "created_at": "2025-04-07T00:41:09Z", "data": { "request_id": "req_abc123", "url": "https://cdn.pixelgar.com/processed/abc123.jpg", "width": 800, "height": 600, "format": "jpeg", "size": 45678 } }

Need Help?

If you have any questions or need assistance with the API, our developer support team is here to help.

Contact Developer Support