Image Diff API
Compare two images pixel by pixel (perceptual colour distance, anti-aliasing aware) and get the share of changed pixels, the changed area and a highlighted diff image.
The image diff API compares two PNG or JPEG images of the same size, such as screenshots of a page before and after a change. It uses pixelmatch, the algorithm of many visual regression tools: colours are compared in a perceptual space with a threshold (0 = exact, default 0.1), and differences caused by anti-aliasing are ignored unless include_aa=true.
The JSON result says whether the images are identical, how many pixels differ and what percentage of the image that is, and the bounding box of the changes. output=image returns the diff image itself: the first image faded, with changed pixels in red and anti-aliasing in yellow; include_image=true adds it as base64 to the JSON.
Images of different sizes are reported as such; resize=true scales the second image to the first one before comparing. Each image may have up to 12.5 megapixels.
Parameters
| Name | In | Type | Required | Default | |
|---|---|---|---|---|---|
a | body | file | yes | First image (multipart field a, or a_base64). | |
b | body | file | yes | Second image (b / b_base64). | |
threshold | body|query | number | no | 0.1 | Colour distance threshold 0–1. |
include_aa | body|query | boolean | no | false | Count anti-aliasing as differences. |
output | body|query | string | no | json | json or image (diff PNG). |
resize | body|query | boolean | no | false | Scale b to a when sizes differ. |
Example
curl -X POST "https://apibox.io.vn/v1/image-diff" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "0=@./my-file"const form = new FormData();
form.append('0', fileInput.files[0]);
const res = await fetch('https://apibox.io.vn/v1/image-diff', {
method: 'POST',
headers: { Authorization: 'Bearer YOUR_API_KEY' },
body: form,
});
console.log(await res.json());import requests
res = requests.post(
"https://apibox.io.vn/v1/image-diff",
headers={"Authorization": "Bearer YOUR_API_KEY"},
files={"0": open("my-file", "rb")},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/image-diff');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
CURLOPT_POSTFIELDS => ['0' => new CURLFile('my-file')],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Response
{
"identical": false,
"width": 1200,
"height": 630,
"diff_pixels": 758,
"diff_percent": 0.1003,
"threshold": 0.1,
"bounding_box": {
"x": 409,
"y": 327,
"width": 324,
"height": 58
}
}Use cases
- Visual regression tests in CI
- Detect unexpected changes on monitored web pages
- Compare design mock-ups with implementation
- Check that image processing keeps quality
FAQ
What threshold should I use?
0.1 for screenshots; 0 to detect any change; 0.2–0.3 for photos and JPEGs with compression noise.
Do I need screenshots of the same size?
Yes for exact comparisons; resize=true makes them comparable but adds interpolation differences.
Can it take screenshots for me?
No, send the images; screenshots need a browser service.
Related APIs
Webhook Tester
Create a unique URL that captures every HTTP request sent to it – method, headers, query and body – then inspect them in the browser or via API.
👤Vietnamese Fake Data
Realistic Vietnamese test data: names, addresses on the 2025 map, mobile numbers by network, CCCD and tax codes with a valid structure, companies, bank accounts.
{?}JSON Schema Mock Data
Generate realistic sample JSON from a JSON Schema (types, formats, enums, patterns, ranges, $ref, oneOf / allOf), validated against the schema.