证件照制作 API
PixMiller REST API · v1
传入一张人像，API 会移除人像背景、换成标准证件底色，并按所选规格裁切。
该端点处于预览阶段 —— 路由与参数仍在最终确定中，上线前可能调整。约定（X-Api-Key 鉴权、JSON 响应）与已上线的抠图 API 一致。
POST
https://api.pixmiller.com/v1/id-photo
1
鉴权与请求
在
X-Api-Key: YOUR_API_KEY 请求头中发送你的密钥。在账户页面创建和管理密钥。
| 参数 | 类型 | 必填参数 | 说明 |
|---|---|---|---|
image_file
|
file | 必填 | 人像照——正脸、光线均匀 |
spec
|
string | 必填 | 规格：1inch / 2inch / us_passport / cn_visa … |
bg_color
|
string | 选填 | 底色：white（默认）/ blue / red |
2
代码示例
选择语言并复制——可直接运行。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
响应
1{2 "url": "https://cdn.pixmiller.com/result/8Kd2pQ.png"3}
url
处理后图片的临时 URL（原图会在 3 天后自动删除）。
4
错误
错误会返回对应的 HTTP 状态码，JSON 响应体形如： {"errors":{"code":"…","message":"…"}}.
400
validation error
缺少或无效的 image_file、文件过大，或同时提供了多个图片来源。
401
authentication_failed
X-Api-Key 请求头缺失或无效。
402
not_enough_credit
请求了 size=full，但账户已无高清点数。
422
invalid_image
图片无法处理 —— 尺寸过小、格式不支持，或解码失败。
429
throttled
超出速率限制。请放慢请求，并在 Retry-After 指示的时间后重试。