格照

API v1 · Reference

接口参考

查看各接口的请求方式、参数、响应字段和调用示例。

统一约定

接口地址为 https://gezhao.cn/api/open/gezhao，统一使用 Authorization: Bearer API Key 认证。JSON 响应都会包含链路标识 request_id，错误结构见错误码。

流程对应关系

直接成品：create(mode=final) → result → 下载。预览确认：create(mode=preview) → result → finalize → 下载。status 查询队列进度，files 查询文件列表。查看流程说明

GET

获取规格列表

https://gezhao.cn/api/open/gezhao/idphoto/specs

获取全部可用的证件照规格。返回的 code 用于创建证件照。

响应字段

字段类型说明
itemsSpecification[]规格列表
items[].codestring用于创建证件照的规格代码
items[].width_px / height_pxinteger成品宽高，单位为像素
items[].width_mm / height_mmnumber成品宽高，单位为毫米
items[].backgroundsstring[]可选的背景色

请求示例

1curl --silent --show-error \
2  -H "Authorization: Bearer $API_KEY" \
3  "https://gezhao.cn/api/open/gezhao/idphoto/specs"

响应示例

{
  "request_id": "req_example_001",
  "items": [{
    "code": "one-inch",
    "name": "一寸",
    "width_mm": 25,
    "height_mm": 35,
    "width_px": 295,
    "height_px": 413,
    "dpi": 300,
    "use": "常用证件照",
    "backgrounds": ["#FFFFFF", "#438EDB", "#D73232"]
  }]
}
GET

获取规格详情

https://gezhao.cn/api/open/gezhao/idphoto/specs/detail

根据规格代码获取尺寸、分辨率和可选背景色。

请求参数

名称是否必填类型说明
code是string查询参数，填写规格代码，例如 one-inch

响应字段

字段类型说明
codestring规格代码
namestring规格名称
width_px / height_pxinteger成品宽高，单位为像素
width_mm / height_mmnumber成品宽高，单位为毫米
dpiinteger输出分辨率
backgroundsstring[]可选的背景色

请求示例

1curl --silent --show-error --get \
2  -H "Authorization: Bearer $API_KEY" \
3  --data-urlencode "code=$SPECIFICATION_CODE" \
4  "https://gezhao.cn/api/open/gezhao/idphoto/specs/detail"

响应示例

{
  "request_id": "req_example_002",
  "code": "one-inch",
  "name": "一寸",
  "width_mm": 25,
  "height_mm": 35,
  "width_px": 295,
  "height_px": 413,
  "dpi": 300,
  "use": "常用证件照",
  "backgrounds": ["#FFFFFF", "#438EDB", "#D73232"]
}
POST

创建证件照

https://gezhao.cn/api/open/gezhao/idphoto/create

上传人像照片并创建处理任务。mode=final 直接生成成品；mode=preview 先生成免费水印预览。

请求格式
multipart/form-data
计费
预览免费；成品成功后 5 积分（¥0.50）

请求参数

名称是否必填类型说明
Idempotency-Key是string请求头，填写 8～128 位字符；重试同一请求时请保持不变
image是binary待处理的人像图片
specification_code是string预设规格代码
mode否preview | final生成模式，默认 preview；直接生成成品时传 final
backgrounds否APIBackground[]背景设置，使用 JSON 字符串；最多填写一个
output否APIOutput输出设置，使用 JSON 字符串

响应字段

字段类型说明
photo_idstring证件照资源标识
job_idstring异步任务标识，仅在使用任务进度接口时需要
statusstring处理状态：queued、processing、preview_ready、finalizing、completed 或 failed
modestring生成模式：preview 或 final
specificationSpecification本次任务采用的规格
qualityobject质量检测结果
filesAPIFile[]已生成的文件
billingAPIBilling计费状态及金额
expires_atdate-time资源失效时间

请求示例

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

响应示例

{
  "request_id": "req_example_001",
  "photo_id": "photo_0123456789abcdef0123456789abcdef",
  "job_id": "job_0123456789abcdef0123456789abcdef",
  "status": "queued",
  "mode": "final",
  "specification": {
    "code": "one-inch",
    "name": "一寸",
    "width_px": 295,
    "height_px": 413,
    "width_mm": 25,
    "height_mm": 35,
    "dpi": 300,
    "use": "常用证件照",
    "backgrounds": ["#FFFFFF", "#438EDB", "#D73232"]
  },
  "quality": {},
  "files": [],
  "billing": {
    "pricing_rule_id": "price_api_default",
    "version": 1,
    "points": 5,
    "amount_cents": 50,
    "currency": "CNY",
    "status": "frozen",
    "charged": false
  },
  "created_at": "2026-07-15T08:00:00Z",
  "expires_at": "2026-07-16T08:00:00Z"
}
异步响应 · 202 Accepted

业务侧保存 photo_id 并用它查询结果；job_id 只在需要任务诊断时使用。请求超时后，使用相同内容和幂等键重试。

GET

查询证件照结果

https://gezhao.cn/api/open/gezhao/idphoto/result

使用 photo_id 查询业务状态、质量检测、计费信息和可下载文件。

请求参数

名称是否必填类型说明
photo_id是string查询参数，填写创建接口返回的 photo_id

响应字段

字段类型说明
photo_idstring证件照资源标识
job_idstring异步任务标识，仅在使用任务进度接口时需要
statusstring处理状态：queued、processing、preview_ready、finalizing、completed 或 failed
modestring生成模式：preview 或 final
specificationSpecification本次任务采用的规格
qualityobject质量检测结果
filesAPIFile[]已生成的文件
billingAPIBilling计费状态及金额
expires_atdate-time资源失效时间

请求示例

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

响应示例

{
  "request_id": "req_example_001",
  "photo_id": "photo_0123456789abcdef0123456789abcdef",
  "job_id": "job_0123456789abcdef0123456789abcdef",
  "status": "completed",
  "mode": "final",
  "specification": {
    "code": "one-inch",
    "name": "一寸",
    "width_px": 295,
    "height_px": 413,
    "width_mm": 25,
    "height_mm": 35,
    "dpi": 300,
    "use": "常用证件照",
    "backgrounds": ["#FFFFFF", "#438EDB", "#D73232"]
  },
  "quality": {},
  "files": [
    {
      "file_id": "file_11111111111111111111111111111111",
      "kind": "photo",
      "format": "jpeg",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 48216,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_11111111111111111111111111111111",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_22222222222222222222222222222222",
      "kind": "transparent",
      "format": "png",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 93640,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_22222222222222222222222222222222",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_33333333333333333333333333333333",
      "kind": "layout",
      "format": "jpeg",
      "size_bytes": 186420,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_33333333333333333333333333333333",
      "expires_at": "2026-07-16T08:00:00Z"
    }
  ],
  "billing": {
    "pricing_rule_id": "price_api_default",
    "version": 1,
    "points": 5,
    "amount_cents": 50,
    "currency": "CNY",
    "status": "confirmed",
    "charged": true
  },
  "created_at": "2026-07-15T08:00:00Z",
  "expires_at": "2026-07-16T08:00:00Z"
}
根据 status 决定下一步

queued / processing / finalizing 继续查询；preview_ready 展示预览并等待确认；completed 直接下载；failed 停止查询。

POST

确认预览并生成成品

https://gezhao.cn/api/open/gezhao/idphoto/finalize

仅用于 mode=preview 的流程。用户确认水印预览后调用；接口扣费并开放无水印成品，无需重新上传照片。

计费
成功后 5 积分（¥0.50）

请求参数

名称是否必填类型说明
Idempotency-Key是string请求头，填写 8～128 位字符；重试同一请求时请保持不变
photo_id是string处于 preview_ready 状态的证件照标识

响应字段

字段类型说明
photo_idstring证件照资源标识
job_idstring异步任务标识，仅在使用任务进度接口时需要
statusstring处理状态：queued、processing、preview_ready、finalizing、completed 或 failed
modestring生成模式：preview 或 final
specificationSpecification本次任务采用的规格
qualityobject质量检测结果
filesAPIFile[]已生成的文件
billingAPIBilling计费状态及金额
expires_atdate-time资源失效时间

请求示例

1curl --request POST \
2  -H "Authorization: Bearer $API_KEY" \
3  -H "Idempotency-Key: finalize-photo-0001" \
4  --url-query "photo_id=$PHOTO_ID" \
5  "https://gezhao.cn/api/open/gezhao/idphoto/finalize"

响应示例

{
  "request_id": "req_example_001",
  "photo_id": "photo_0123456789abcdef0123456789abcdef",
  "job_id": "job_0123456789abcdef0123456789abcdef",
  "status": "completed",
  "mode": "final",
  "specification": {
    "code": "one-inch",
    "name": "一寸",
    "width_px": 295,
    "height_px": 413,
    "width_mm": 25,
    "height_mm": 35,
    "dpi": 300,
    "use": "常用证件照",
    "backgrounds": ["#FFFFFF", "#438EDB", "#D73232"]
  },
  "quality": {},
  "files": [
    {
      "file_id": "file_11111111111111111111111111111111",
      "kind": "photo",
      "format": "jpeg",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 48216,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_11111111111111111111111111111111",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_22222222222222222222222222222222",
      "kind": "transparent",
      "format": "png",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 93640,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_22222222222222222222222222222222",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_33333333333333333333333333333333",
      "kind": "layout",
      "format": "jpeg",
      "size_bytes": 186420,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_33333333333333333333333333333333",
      "expires_at": "2026-07-16T08:00:00Z"
    }
  ],
  "billing": {
    "pricing_rule_id": "price_api_default",
    "version": 1,
    "points": 5,
    "amount_cents": 50,
    "currency": "CNY",
    "status": "confirmed",
    "charged": true
  },
  "created_at": "2026-07-15T08:00:00Z",
  "expires_at": "2026-07-16T08:00:00Z"
}
适用条件

此接口处理 mode=preview 且状态为 preview_ready 的证件照。mode=final 的任务由创建流程直接结算。

GET

查询处理进度

https://gezhao.cn/api/open/gezhao/idphoto/status

使用 job_id 查询队列状态和重试次数。

请求参数

名称是否必填类型说明
job_id是string创建接口返回的异步任务标识

响应字段

字段类型说明
job_idstring任务标识
photo_idstring关联的证件照标识
statusstring证件照业务状态
queue_statusstring队列状态：queued、processing、succeeded 或 failed
attempt_countinteger已执行次数
qualityobject质量检测结果
expires_atdate-time任务失效时间

请求示例

1curl --silent --show-error --get \
2  -H "Authorization: Bearer $API_KEY" \
3  --data-urlencode "job_id=$JOB_ID" \
4  "https://gezhao.cn/api/open/gezhao/idphoto/status"

响应示例

{
  "request_id": "req_example_006",
  "job_id": "job_0123456789abcdef0123456789abcdef",
  "photo_id": "photo_0123456789abcdef0123456789abcdef",
  "status": "completed",
  "queue_status": "succeeded",
  "attempt_count": 1,
  "quality": {"passed": true, "issues": []},
  "expires_at": "2026-07-16T08:00:00Z"
}
GET

查询生成文件

https://gezhao.cn/api/open/gezhao/idphoto/files

使用 photo_id 获取当前可访问的预览和成品文件列表。

请求参数

名称是否必填类型说明
photo_id是string证件照资源标识

响应字段

字段类型说明
photo_idstring证件照资源标识
itemsAPIFile[]当前可访问文件，最多 4 个
items[].kindstringpreview、photo、transparent 或 layout
items[].download_urlstring带认证的文件下载地址，响应 302 跳转到 5 分钟有效的签名地址，客户端需跟随跳转（如 curl -L）
expires_atdate-time文件失效时间

请求示例

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

响应示例

{
  "request_id": "req_example_007",
  "photo_id": "photo_0123456789abcdef0123456789abcdef",
  "items": [
    {
      "file_id": "file_11111111111111111111111111111111",
      "kind": "photo",
      "format": "jpeg",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 48216,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_11111111111111111111111111111111",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_22222222222222222222222222222222",
      "kind": "transparent",
      "format": "png",
      "width_px": 295,
      "height_px": 413,
      "size_bytes": 93640,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_22222222222222222222222222222222",
      "expires_at": "2026-07-16T08:00:00Z"
    },
    {
      "file_id": "file_33333333333333333333333333333333",
      "kind": "layout",
      "format": "jpeg",
      "size_bytes": 186420,
      "download_url": "https://gezhao.cn/api/open/gezhao/idphoto/download?file_id=file_33333333333333333333333333333333",
      "expires_at": "2026-07-16T08:00:00Z"
    }
  ],
  "expires_at": "2026-07-16T08:00:00Z"
}