API Documentation

Convert HEIC images programmatically with our free REST API

100% Free CORS Enabled No API Key Required

Overview

The HoneyConvert API allows you to convert HEIC and HEIF images to PNG, JPEG, or WebP format programmatically. The API is free to use, requires no authentication, and supports cross-origin requests (CORS).

Endpoint

POST https://honeyconvert.com/api/convert

Parameters

Send a multipart/form-data request with the following parameters:

Parameter	Type	Required	Description
`file`	File	Required	The HEIC or HEIF file to convert (max 100MB)
`format`	String	Optional	Output format: `png`, `jpeg`, or `webp`. Default: `png`
`size`	Integer	Optional	Size percentage: `100`, `75`, `50`, or `25`. Default: `100`
`quality`	Integer	Optional	JPEG/WebP quality: `1-100`. Default: `90`. Ignored for PNG.
`rotate`	Integer	Optional	Rotation degrees: `0`, `90`, `180`, or `270`. Default: `0`
`crop`	String	Optional	Aspect ratio: `none`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`. Default: `none`

Code Examples

Basic Conversion

# Convert HEIC to PNG
curl -X POST https://honeyconvert.com/api/convert \
  -F "file=@photo.heic" \
  -o converted.png

With Options

# Convert to JPEG at 75% size with 90-degree rotation
curl -X POST https://honeyconvert.com/api/convert \
  -F "file=@photo.heic" \
  -F "format=jpeg" \
  -F "size=75" \
  -F "rotate=90" \
  -F "quality=85" \
  -o converted.jpg

Square Crop

# Convert to square WebP
curl -X POST https://honeyconvert.com/api/convert \
  -F "file=@photo.heic" \
  -F "format=webp" \
  -F "crop=1:1" \
  -o square.webp

Using requests

import requests

# Basic conversion
with open('photo.heic', 'rb') as f:
    response = requests.post(
        'https://honeyconvert.com/api/convert',
        files={'file': f}
    )

with open('converted.png', 'wb') as f:
    f.write(response.content)

With Options

import requests

with open('photo.heic', 'rb') as f:
    response = requests.post(
        'https://honeyconvert.com/api/convert',
        files={'file': f},
        data={
            'format': 'jpeg',
            'size': '75',
            'rotate': '90',
            'crop': '1:1',
            'quality': '85'
        }
    )

if response.status_code == 200:
    with open('converted.jpg', 'wb') as f:
        f.write(response.content)
else:
    print('Error:', response.json())

Using fetch (Browser)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('format', 'png');

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

if (response.ok) {
    const blob = await response.blob();
    const url = URL.createObjectURL(blob);
    // Use the URL for download or display
} else {
    const error = await response.json();
    console.error(error);
}

Using Node.js (with node-fetch and form-data)

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const form = new FormData();
form.append('file', fs.createReadStream('photo.heic'));
form.append('format', 'jpeg');

const response = await fetch('https://honeyconvert.com/api/convert', {
    method: 'POST',
    body: form
});

const buffer = await response.buffer();
fs.writeFileSync('converted.jpg', buffer);

Using cURL

<?php
$ch = curl_init();

$data = [
    'file' => new CURLFile('photo.heic'),
    'format' => 'png',
    'size' => '75'
];

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://honeyconvert.com/api/convert',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    file_put_contents('converted.png', $response);
} else {
    $error = json_decode($response, true);
    echo 'Error: ' . $error['error'];
}
?>

Response

Success (200 OK)

On success, the API returns the converted image file directly with appropriate headers:

Headers

Content-Type: image/png (or jpeg, webp)
Content-Disposition: attachment; filename="photo.png"
X-HoneyConvert-Format: png
X-HoneyConvert-Size: 100

Error Responses

On error, the API returns a JSON response:

{
    "success": false,
    "error": "No file provided",
    "code": "MISSING_FILE",
    "documentation": "https://honeyconvert.com/api"
}

Error Codes

HTTP Status	Code	Description
400	`MISSING_FILE`	No file was provided in the request
400	`EMPTY_FILE`	The file field was empty
400	`INVALID_FILE_TYPE`	File is not a .heic or .heif file
500	`CONVERSION_FAILED`	The file could not be converted (may be corrupted)
500	`SERVER_ERROR`	An unexpected server error occurred

Rate Limits

The API is free and does not currently enforce strict rate limits. However, we ask that you:

Keep requests under 100 per minute per IP address
Avoid automated bulk conversions of thousands of files
Cache converted images on your end when possible

Excessive usage may result in temporary IP blocking. For high-volume needs, please contact us.

CORS Support

The API supports Cross-Origin Resource Sharing (CORS), allowing you to make requests directly from web browsers. All responses include:

Access-Control-Allow-Origin: *

Need Help?

If you have questions or need assistance integrating the API, please contact us. We're happy to help!

Try the Converter