Imghippo API Documentation

The Imghippo API is a REST API for image hosting, direct URL generation, image optimization, format conversion, and background removal. All endpoints accept multipart/form-data requests and return immediate JSON responses.

Base URLhttps://api.imghippo.com/v1

ProtocolHTTPS

MethodPOST

Content-Typemultipart/form-data

AuthenticationAPI Key

Quick Start

Choose an endpoint for your operation
Send a POST request with your api_key and file
Receive the processed file URL in the response

Typical Use Cases

Content Management

Upload and store images for websites and applications

Image Optimization

Compress images to reduce file sizes for faster page loads

Format Conversion

Convert between image formats (PNG, JPG, WEBP, HEIC)

Document Processing

Convert Word documents to PDF format

Background Removal

Automatically remove backgrounds from product images

Batch Processing

Automate image processing workflows at scale

Authentication

All API requests require authentication using an API key. Include it as a field in every multipart/form-data request body.

⚠️

Security Notice: Keep your API key secure. Never expose it in client-side code or public repositories. Always use environment variables.

How to Authenticate

Include the api_key parameter in every request:

CURL

curl -X POST https://api.imghippo.com/v1/upload \
  -F "api_key=YOUR_API_KEY" \
  -F "file=@image.jpg"

Parameter Conventions

All requests must use multipart/form-data encoding
File uploads use the file input type
Parameter names are case-sensitive
Required fields must be included in every request
Optional parameters can be omitted
Maximum file size is 50MB per request

Usage Limits & Storage

Your account includes 500 MB of free storage. All uploaded and processed files count toward your total storage usage.

Once you reach the 500 MB limit:

New uploads and processing requests will be restricted
Existing files remain accessible

For higher storage needs, visit API Pricing.

File Parameter Naming

Parameter	Type	Required	Description
file	file	Required	Image Upload — original image file
image	file	Required	Image Processing (Compress, Remove BG)
file	file	Required	Document Conversion

Images & Documents

Request Workflow

Prepare your image or document file
Include your API key in the request
Send a POST request to the appropriate endpoint
Receive immediate response with processed file URL
Use the returned URL to access your file

Upload Image

POSThttps://api.imghippo.com/v1/upload

Upload an image file to Imghippo for storage and hosting. Single file per request.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
file	file	Required	Image file to upload
title	string	Optional	Title for the image

Supported Formats

JPGJPEGPNGGIFWEBPSVG

Response

JSON

{
  "status": 200,
  "message": "Uploaded successfully",
  "data": {
    "title": "My photo",
    "url": "https://i.imghippo.com/files/Ro2lJ1729256143.jpg",
    "view_url": "https://i.imghippo.com/files/Ro2lJ1729256143.jpg",
    "extension": "jpg",
    "size": 204800,
    "created_at": "2024-06-04T12:00:00.000Z"
  }
}

⚠️

Storage limit: 500 MB for free accounts. Higher limits available on paid plans.

Delete Image

DELETEhttps://api.imghippo.com/v1/delete

Delete a previously uploaded image. Only files uploaded by your account can be deleted. Uses JSON body, not multipart.

Request Body (JSON)

JSON

{
  "api_key": "your-api-key-here",
  "url": "https://i.imghippo.com/files/Ro2lJ1729256143.jpg"
}

Parameter	Type	Required	Description
api_key	string	Required	Your API key
url	string	Required	Full URL of the image to delete

Response

JSON

{
  "status": 200,
  "message": "File deleted successfully",
  "deleted_url": "https://i.imghippo.com/files/Ro2lJ1729256143.jpg"
}

Compress

Request Workflow

Select the compression endpoint based on your image format
Prepare your image file for compression
Send POST request with API key and image file
Receive compressed image URL with size reduction details
Download or use the optimized image

Compress Image (All Formats)

POSThttps://api.imghippo.com/v1/compress-image

Compress images in any supported format. Accepts JPEG, PNG, WebP, and GIF. Adaptive quality based on file size.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	Up to 5 image files (JPEG, PNG, WebP, GIF)

Response

JSON

{
  "status": 200,
  "message": "Processing complete",
  "summary": { "total": 1, "succeeded": 1, "failed": 0 },
  "data": [
    {
      "status": "success",
      "index": 0,
      "original_name": "photo.jpg",
      "output_url": "https://i.imghippo.com/compressed/compressed_1717400000_a1b2c3.jpg",
      "original_size": 2048576,
      "output_size": 512000,
      "saved_percent": 75.0,
      "format": "jpg"
    }
  ]
}

PNG files are converted to JPEG for better compression. Returns the original if compressed output is larger.

Compress JPG

POSThttps://api.imghippo.com/v1/compress/jpg

Compress JPG images while maintaining visual quality. Typical compression: 60-80% size reduction.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	JPG image to compress (up to 5 files)

Compress PNG

POSThttps://api.imghippo.com/v1/compress/png

Compress PNG images with lossless compression. Preserves transparency.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	PNG image to compress (up to 5 files)

Compress GIF

POSThttps://api.imghippo.com/v1/compress/gif

Compress GIF animations while preserving animation frames and timing.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	GIF image to compress (up to 5 files)

Compress SVG

POSThttps://api.imghippo.com/v1/compress/svg

Optimize SVG files by removing unnecessary metadata and whitespace.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	SVG file to compress (up to 5 files)

Convert

Request Workflow

Choose the conversion endpoint based on input and output formats
Prepare your source file
Send POST request with API key and source file
Receive converted file URL in the specified format
Access the converted file via the returned URL

Word to PDF

POSThttps://api.imghippo.com/v1/convert/word-to-pdf

Convert Microsoft Word documents (.doc, .docx) to PDF format.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
file	file[]	Required	Word document (.doc, .docx) (up to 5 files)

PNG to JPG

POSThttps://api.imghippo.com/v1/convert/png-to-jpg

Convert PNG images to JPG format. Note: Transparency will be replaced with white background.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	PNG image (up to 5 files)

JPG to PNG

POSThttps://api.imghippo.com/v1/convert/jpg-to-png

Convert JPG images to PNG format. Useful for images requiring transparency or lossless quality.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	JPG image (up to 5 files)

HEIC to JPG

POSThttps://api.imghippo.com/v1/convert/heic-to-jpg

Convert HEIC images (iPhone default format) to widely compatible JPG format.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	HEIC image (up to 5 files)

WEBP to JPG

POSThttps://api.imghippo.com/v1/convert/webp-to-jpg

Convert WEBP images to JPG format for broader compatibility.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	WEBP image (up to 5 files)

JPG to WEBP

POSThttps://api.imghippo.com/v1/convert/jpg-to-webp

Convert JPG images to WEBP format for superior compression and quality.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	JPG image (up to 5 files)

Optimise & Edit

Remove Background

POSThttps://api.imghippo.com/v1/remove-background

Automatically remove the background from images using AI-powered detection. Output is always PNG with transparent background.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	Up to 5 image files (JPEG, PNG, WebP)

Response

JSON

{
  "status": 200,
  "message": "Processing complete",
  "summary": { "total": 1, "succeeded": 1, "failed": 0 },
  "data": [
    {
      "status": "success",
      "index": 0,
      "original_name": "portrait.jpg",
      "output_url": "https://i.imghippo.com/converted/removebackground/bg_removed_1717400000_a1b2c3.png",
      "original_size": 204800,
      "output_size": 153600,
      "format": "png"
    }
  ]
}

Processing may take longer due to AI inference. Output is always PNG format.

Resize Image

POSThttps://api.imghippo.com/v1/resize-image

Resize images to specific dimensions. Provide width, height, or both. If only one is given, the other is calculated to maintain aspect ratio.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file[]	Required	Up to 5 image files (JPEG, PNG, WebP, GIF, BMP, TIFF)
width	number	Optional	Target width in pixels (at least one of width/height required)
height	number	Optional	Target height in pixels (at least one of width/height required)

Response

JSON

{
  "status": 200,
  "message": "Processing complete",
  "summary": { "total": 1, "succeeded": 1, "failed": 0 },
  "data": [
    {
      "status": "success",
      "index": 0,
      "original_name": "photo.jpg",
      "output_url": "https://i.imghippo.com/converted/resize-image/resized_1717400000_a1b2c3.jpg",
      "original_size": 2048576,
      "output_size": 512000,
      "saved_percent": 75.0,
      "format": "jpg"
    }
  ]
}

Images smaller than target dimensions are not upscaled. Output format matches input format.

Crop Image

POSThttps://api.imghippo.com/v1/crop-image

Crop an image to a specific region. Provide the x/y offset and width/height of the crop area. Single file per request.

Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key
image	file	Required	Single image file
x	number	Required	Crop X offset in pixels (from top-left)
y	number	Required	Crop Y offset in pixels (from top-left)
width	number	Required	Crop region width in pixels
height	number	Required	Crop region height in pixels

Response

JSON

{
  "status": 200,
  "message": "Processing complete",
  "summary": { "total": 1, "succeeded": 1, "failed": 0 },
  "data": [
    {
      "status": "success",
      "index": 0,
      "original_name": "photo.jpg",
      "output_url": "https://i.imghippo.com/converted/crop-image/cropped_1717400000_a1b2c3.jpg",
      "original_size": 524288,
      "output_size": 131072,
      "saved_percent": 75.0,
      "format": "jpg"
    }
  ]
}

⚠️

Crop region must not exceed image bounds. x and y must be at least 0, width and height must be greater than 0.

Response

Batch Response Format

All processing endpoints (compress, convert, resize, crop, remove-background) return the same batch response shape:

JSON

{
  "status": 200,
  "message": "Processing complete",
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  },
  "data": [
    {
      "status": "success",
      "index": 0,
      "original_name": "photo.jpg",
      "output_url": "https://i.imghippo.com/compressed/compressed_1717400000_a1b2c3.jpg",
      "original_size": 2048576,
      "output_size": 512000,
      "saved_percent": 75.0,
      "format": "jpg"
    },
    {
      "status": "failed",
      "index": 1,
      "original_name": "corrupt.png",
      "error": "Processing failed"
    }
  ]
}

summary.total

Total files submitted in the request

summary.succeeded

Number of files processed successfully

summary.failed

Number of files that failed processing

data[].status

'success' or 'failed' for each file

data[].index

Position of the file in the batch (0-based)

data[].output_url

URL of the processed file (download from here)

data[].original_size

Original file size in bytes

data[].output_size

Output file size in bytes

data[].saved_percent

Percentage of space saved

data[].format

Output format (e.g. jpg, png, pdf)

One failed file does NOT fail the whole batch. Other files still process successfully.

Error Codes

Code	Status	Description	Common Causes
200	OK	Request completed successfully	—
400	Bad Request	Invalid parameters or missing required fields	Missing api_key, invalid file format
401	Unauthorized	Invalid or missing API key	Incorrect API key, expired key
413	Payload Too Large	File size exceeds maximum limit	File larger than 50MB
415	Unsupported Media Type	File format not supported	Unsupported file extension
500	Internal Server Error	Server error occurred during processing	Temporary server issue, corrupted file

Code Examples

cURL

Upload

BASH

curl -X POST https://api.imghippo.com/v1/upload \
  -F "api_key=your-api-key-here" \
  -F "file=@/path/to/image.jpg" \
  -F "title=My Photo"

Compress

BASH

curl -X POST https://api.imghippo.com/v1/compress-image \
  -F "api_key=your-api-key-here" \
  -F "image=@/path/to/photo.jpg"

Convert PNG to JPG

BASH

curl -X POST https://api.imghippo.com/v1/convert/png-to-jpg \
  -F "api_key=your-api-key-here" \
  -F "image=@/path/to/image.png"

Resize

BASH

curl -X POST https://api.imghippo.com/v1/resize-image \
  -F "api_key=your-api-key-here" \
  -F "image=@/path/to/photo.jpg" \
  -F "width=800"

Crop

BASH

curl -X POST https://api.imghippo.com/v1/crop-image \
  -F "api_key=your-api-key-here" \
  -F "image=@/path/to/photo.jpg" \
  -F "x=100" -F "y=50" -F "width=800" -F "height=600"

Remove Background

BASH

curl -X POST https://api.imghippo.com/v1/remove-background \
  -F "api_key=your-api-key-here" \
  -F "image=@/path/to/portrait.jpg"

Delete

BASH

curl -X DELETE https://api.imghippo.com/v1/delete \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-api-key-here", "url": "https://i.imghippo.com/files/Ro2lJ1729256143.jpg"}'

JavaScript

JAVASCRIPT

const formData = new FormData();
formData.append('api_key', 'your-api-key-here');
formData.append('file', fileInput.files[0]);

const response = await fetch('https://api.imghippo.com/v1/upload', {
  method: 'POST',
  body: formData,
});

const result = await response.json();
console.log(result.data.url);

Python

PYTHON

import requests

response = requests.post(
    'https://api.imghippo.com/v1/upload',
    data={'api_key': 'your-api-key-here'},
    files={'file': open('image.jpg', 'rb')}
)

print(response.json()['data']['url'])