格照

API v1 · Quickstart

几分钟完成首次调用

API 支持直接生成成品，也支持先生成水印预览、确认后再生成成品。

管理 API Key浏览全部接口 →
01

两种生成方式

根据产品是否需要用户确认预览，使用对应流程。

直接生成成品

create(mode=final) → result → 下载

适合自动化制证、后台批处理等已经确定要出成品的场景。处理成功后扣费。

先预览再生成成品

create(mode=preview) → result → finalize → 下载

适合需要用户先确认效果的页面。预览免费，确认成品时才扣费。

  1. 1
    准备 API Key 和规格代码

    保存邮箱验证后生成的默认密钥，并从规格列表选择一个 code。所有请求都通过 Authorization 请求头传递 API Key。

  2. 2
    创建并保存 photo_id

    调用 POST /idphoto/create 上传照片。直接生成成品时传入 mode=final；先看预览时传入 mode=preview。

  3. 3
    查询并执行下一步

    统一轮询 GET /idphoto/result。成品模式进入 completed 后下载；预览模式进入 preview_ready 后展示预览，并在用户确认时调用 finalize。

02

认证与幂等

所有公开接口共用一套简单约定。

Bearer 认证
Authorization: Bearer idp_live_xxx

API Key 只能放在服务端，不要写入网页、App 包、日志或版本库。

安全重试
Idempotency-Key: order-photo-0001

创建接口要求 8～128 位安全字符。请求超时后，使用相同内容和幂等键重试，不会重复创建或扣费。

03

创建第一个成品任务

请求为 multipart/form-data，接口立即返回证件照标识。

export API_KEY=idp_live_xxx

curl --silent --show-error \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: first-photo-0001" \
  -F "image=@portrait.jpg" \
  -F "mode=final" \
  -F "specification_code=one-inch" \
  -F 'backgrounds=[{"type":"preset","value":"white"}]' \
  "https://gezhao.cn/api/open/gezhao/idphoto/create"
保存两个标识

photo_id 用于查询证件照结果，job_id 用于查询处理进度。成品处理成功后扣除积分，失败则释放冻结积分。

04

查询并下载

result 返回业务状态和文件；status 返回队列处理进度；files 单独返回文件列表。

curl --get -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "photo_id=$PHOTO_ID" \
  "https://gezhao.cn/api/open/gezhao/idphoto/result"
status下一步
queued / processing等待后继续查询
preview_ready展示水印预览；用户确认后调用 finalize
finalizing成品确认中，等待后继续查询
completed使用 files[].download_url 下载成品并停止查询
failed读取 error 和 quality，停止查询

证件照和文件只能由创建它们的同一 API Key 访问。有效期内查询和重复下载不额外扣费。下载地址会 302 跳转到短期签名地址，请让客户端跟随跳转（如 curl -L）。

05

接口一览

点击任一接口查看请求参数、响应字段和完整示例。

GEThttps://gezhao.cn/api/open/gezhao/idphoto/specs获取可用规格→GEThttps://gezhao.cn/api/open/gezhao/idphoto/specs/detail获取规格详情→POSThttps://gezhao.cn/api/open/gezhao/idphoto/create创建证件照→GEThttps://gezhao.cn/api/open/gezhao/idphoto/result查询证件照结果→POSThttps://gezhao.cn/api/open/gezhao/idphoto/finalize确认预览并生成成品→GEThttps://gezhao.cn/api/open/gezhao/idphoto/status查询处理进度→GEThttps://gezhao.cn/api/open/gezhao/idphoto/files查询生成文件→