可运行示例

接入示例

以下示例展示直接生成成品，并明确传入 mode=final。请通过环境变量注入 API Key。

接口地址

https://gezhao.cn/api/open/gezhao。示例中的 portrait.jpg 替换为你的测试图片。

cURL

export API_KEY=idp_live_xxx

curl --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: curl-create-0001" \
  -F "image=@portrait.jpg" \
  -F "mode=final" \
  -F "specification_code=one-inch" \
  -F 'backgrounds=[{"type":"preset","value":"white"}]' \
  -F 'output={"format":"jpeg","dpi":300,"include_layout":true,"layout_size":"6-inch"}' \
  "https://gezhao.cn/api/open/gezhao/idphoto/create"

JavaScript（Node.js 20+）

import {openAsBlob} from "node:fs";

const form = new FormData();
form.set("image", await openAsBlob("portrait.jpg"), "portrait.jpg");
form.set("mode", "final");
form.set("specification_code", "one-inch");
form.set("backgrounds", JSON.stringify([{type: "preset", value: "white"}]));
form.set("output", JSON.stringify({
  format: "jpeg", dpi: 300, include_layout: true, layout_size: "6-inch",
}));

const response = await fetch("https://gezhao.cn/api/open/gezhao/idphoto/create", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": "node-create-0001",
  },
  body: form,
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.photo_id, result.billing.status);

Python（requests）

import json
import os
import requests

with open("portrait.jpg", "rb") as image:
    response = requests.post(
        "https://gezhao.cn/api/open/gezhao/idphoto/create",
        headers={
            "Authorization": f"Bearer {os.environ['API_KEY']}",
            "Idempotency-Key": "python-create-0001",
        },
        files={"image": ("portrait.jpg", image, "image/jpeg")},
        data={
            "mode": "final",
            "specification_code": "one-inch",
            "backgrounds": json.dumps([{"type": "preset", "value": "white"}]),
            "output": json.dumps({
                "format": "jpeg", "dpi": 300,
                "include_layout": True, "layout_size": "6-inch",
            }),
        },
        timeout=30,
    )

result = response.json()
response.raise_for_status()
print(result["photo_id"], result["billing"]["status"])

查询证件照

curl --silent --show-error --get \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "photo_id=$PHOTO_ID" \
  "https://gezhao.cn/api/open/gezhao/idphoto/result"

保存创建接口返回的 photo_id 并轮询此接口。completed 时直接读取 files；failed 时读取 error 和 quality 并停止轮询。

需要先预览时

把创建请求中的 mode 改为 preview。当 result.status 为 preview_ready 时展示预览；用户确认后再调用：

curl --request POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: confirm-preview-0001" \
  --url-query "photo_id=$PHOTO_ID" \
  "https://gezhao.cn/api/open/gezhao/idphoto/finalize"