File Processing API Documentation

Introduction

This API provides endpoints for processing files including image compression, PDF compression, and format conversion. The base URL for all endpoints is https://minipng.com/.

API Version

Current version: v1.0.0

Contact

For support, please contact: [email protected]

Authentication

API Key Authentication

All API requests require authentication using an API key. You need to include your API key in the header of each request.

Header Name: X-User-Token
Header Value: Your API Token
Example:
X-User-Token: your_api_token_here

Success Responses

The API uses standard HTTP success response codes to indicate successful operations. All successful responses follow a consistent format and include relevant data.

200 OK

The request has succeeded. The response includes the requested data.

Common Uses:
  • Retrieving user profile
  • Getting API usage statistics
  • Fetching file information
Example Response:
{
   "success": true,
   "data": {
     "user": {
       "id": 123,
       "name": "John Doe",
       "email": "[email protected]"
     }
   }
}
201 Created

The request has succeeded and a new resource has been created as a result.

Common Uses:
  • Image compression
  • PDF compression
  • File conversion
Example Response:
{
   "success": true,
   "output_ext": "jpg",
   "size_before": 1024000,
   "size_after": 512000,
   "compression_percentage": "50%",
   "download": "https://example.com/compressed/image.jpg"
}

Error Responses

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with the server.

400 Bad Request

The server cannot or will not process the request due to an error that is perceived to be a client error.

Common Causes:
  • Invalid request parameters
  • Missing required fields
  • Invalid file format
  • Insufficient balance
Example Response:
{
   "error": "Invalid source URL provided",
   "message": "The provided URL is not accessible or invalid"
}
404 Not Found

The requested resource could not be found but may be available in the future.

Common Causes:
  • Invalid API endpoint
  • Resource has been deleted
  • File not found at the provided URL
Example Response:
{
   "error": "Resource not found",
   "message": "The requested file could not be found at the provided URL"
}
500 Internal Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request.

Common Causes:
  • Server processing error
  • Database connection issues
  • File processing failure
  • External service unavailability
Example Response:
{
   "error": "Internal server error",
   "message": "An unexpected error occurred while processing your request",
   "request_id": "req_123456789"
}

Image Processing

POST /api/v1/compress/image

Compress an image file to reduce its size while maintaining quality.

Request Body (JSON):
Parameter Type Required Description
source_url string (URL) Yes URL of the image to compress
Example Request:
{
  "source_url": "https://example.com/image.jpg"
}
201 - Image compressed successfully
{
  "success": true,
  "output_ext": "jpg",
  "size_before": 1024000,
  "size_after": 512000,
  "compression_percentage": "50%",
  "download": "https://minipng.com/api/download/file-uuid"
}
400 - Bad request or insufficient balance
{
  "error": "Invalid source URL provided"
}
500 - Server error
{
  "status": "error",
  "message": "An unexpected error occurred"
}
POST /api/v1/convert/image

Convert an image to a different format.

Request Body (JSON):
Parameter Type Required Description
source_url string (URL) Yes URL of the image to convert
output_format string (enum) Yes Format to convert to: png, jpg, jpeg, webp, gif
quality integer (1-100) No Quality of the output image (default: 85)
Example Request:
{
  "source_url": "https://example.com/image.jpg",
  "output_format": "webp",
  "quality": 90
}
201 - Image converted successfully
{
  "success": true,
  "input_format": "jpg",
  "output_format": "webp",
  "quality": 90,
  "size_before": "1.5 MB",
  "size_after": "1.2 MB",
  "compression_percentage": 20,
  "download": "https://minipng.com/api/download/file-uuid"
}
400 - Bad request or insufficient balance
{
  "error": "Invalid output format specified"
}
500 - Server error
{
  "status": "error",
  "message": "An unexpected error occurred"
}

PDF Processing

POST /api/v1/compress/pdf

Compress a PDF file to reduce its size while maintaining quality.

Request Body (JSON):
Parameter Type Required Description
source_url string (URL) Yes URL of the PDF to compress
Example Request:
{
  "source_url": "https://example.com/document.pdf"
}
201 - PDF compressed successfully
{
  "success": true,
  "output_ext": "pdf",
  "size_before": 1024000,
  "size_after": 512000,
  "compression_percentage": "50%",
  "download": "https://minipng.com/api/download/file-uuid"
}
400 - Bad request or insufficient balance
{
  "error": "Invalid source URL provided"
}
500 - Server error
{
  "status": "error",
  "message": "An unexpected error occurred"
}
POST /api/v1/convert/pdf-to-images

Convert a PDF document to a set of images (one per page).

Request Body (JSON):
Parameter Type Required Description
source_url string (URL) Yes URL of the PDF to convert
images_quality string (enum) No Quality of output images: low, medium, high (default: medium)
images_format string (enum) No Format of output images: png, jpg (default: png)
Example Request:
{
  "source_url": "https://example.com/document.pdf",
  "images_quality": "high",
  "images_format": "jpg"
}
201 - PDF converted successfully
{
  "success": true,
  "total_images": 5,
  "total_size": "2.5 MB",
  "download": "https://minipng.com/api/download/file-uuid"
}
400 - Bad request or insufficient balance
{
  "error": "Invalid source URL provided"
}
500 - Server error
{
  "status": "error",
  "message": "An unexpected error occurred"
}

User

GET /api/v1/profile

Get user profile and API usage information.

No parameters required

This endpoint only requires authentication via the X-User-Token header.

200 - User profile retrieved successfully
{
  "success": true,
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "[email protected]"
    },
    "tokens": [
      {
        "id": 1,
        "name": "Production API Key",
        "token": "api_xyz123...",
        "created_at": "2023-01-15T10:30:00Z",
        "last_used_at": "2023-06-20T15:45:22Z",
        "usage_count": 157,
        "is_active": true,
        "is_current": true
      }
    ],
    "credits": {
      "current_balance": 500
    }
  }
}