ID Photo Maker API
PixMiller REST API · v1
Send a portrait; the API removes the portrait background, swaps to a standard ID background color and crops to the requested spec.
This endpoint is in preview — the route and parameters are being finalised and may change before launch. Conventions (X-Api-Key auth, JSON response) match the live background removal API.
POST
https://api.pixmiller.com/v1/id-photo
1
Authentication & request
Send your secret key in the
X-Api-Key: YOUR_API_KEY request header. Create and manage keys on your account page.
| Parameter | Type | Required | Description |
|---|---|---|---|
image_file
|
file | required | Portrait photo — front-facing, evenly lit |
spec
|
string | required | Spec: 1inch / 2inch / us_passport / cn_visa … |
bg_color
|
string | optional | Background: white (default) / blue / red |
2
Code samples
Pick a language and copy — runs as-is.1curl -X POST "https://api.pixmiller.com/v1/id-photo" \2 -H "X-Api-Key: YOUR_API_KEY" \3 -F "[email protected]" \4 -F "spec=1inch" \5 -F "bg_color=blue"
1import requests23resp = requests.post(4 "https://api.pixmiller.com/v1/id-photo",5 headers={"X-Api-Key": "YOUR_API_KEY"},6 files={"image_file": open("face.jpg", "rb")},7 data={"spec": "1inch", "bg_color": "blue"},8)9print(resp.json()["url"])
1import fs from "node:fs";23const form = new FormData();4form.append("image_file", new Blob([fs.readFileSync("face.jpg")]), "face.jpg");5form.append("spec", "1inch");6form.append("bg_color", "blue");7const resp = await fetch("https://api.pixmiller.com/v1/id-photo", {8 method: "POST",9 headers: { "X-Api-Key": "YOUR_API_KEY" },10 body: form,11});12console.log((await resp.json()).url);
3
Response
1{2 "url": "https://cdn.pixmiller.com/result/8Kd2pQ.png"3}
url
Temporary URL of the processed image (the underlying image is auto-deleted after 3 days).
4
Errors
Errors return the matching status code and a JSON body shaped like {"errors":{"code":"…","message":"…"}}.
400
validation error
Missing or invalid image_file, file too large, or conflicting image sources.
401
authentication_failed
The X-Api-Key header is missing or invalid.
402
not_enough_credit
size=full was requested but the account has no HD credits left.
422
invalid_image
The image could not be processed — too small, unsupported, or failed to decode.
429
throttled
Rate limit exceeded. Slow down and retry after the Retry-After header.