照片自动审核 API 文档

考试报名照片审核与证件照检测接口

1. 接口说明 #

本接口用于接入方系统提交照片自动审核任务，并获取审核结果。适用于考试报名照片审核自动化、报名证件照合规检测、考试照片审核结果回传等业务场景，可帮助考试报名系统、人事考试平台、招考服务平台和职业资格报名系统完成照片上传前的自动审核与结果回传。

接口支持各类自考、公务员考试、事业单位考试、职业资格考试、教师资格考试、考研、成考、英语四六级、计算机等级考试等报名照片审核场景，主要用于将考试报名照片审核工具的处理流程接口化、自动化，帮助接入方批量提交照片并获取审核结果，降低人工操作成本并提升照片提交通过率。

接口入口：https://www.clipimg.com/app/picture_check_api.php

鉴权方式：业务参数中传 apikey。

建议接入流程：

调用审核项目列表接口，获取可用的 robot_id。
调用提交任务接口，提交待审核照片。
优先通过回调接口接收结果。
如回调接收失败，可通过主动查询接口按 order_id 查询结果。

2. 获取审核项目列表 #

审核项目列表用于获取当前可用的照片审核规则。不同审核项目可对应不同考试类型、地区或平台要求，例如公务员考试照片审核、自考报名照片审核、人事考试照片审核、职业资格考试证件照审核等。

请求信息 #

请求方式：GET
请求地址：https://www.clipimg.com/app/picture_check_api.php/robots

请求示例 #

curl "https://www.clipimg.com/app/picture_check_api.php/robots"

响应示例 #

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "title": "天津市国考照片审核",
      "category": "国考",
      "province": "天津"
    }
  ]
}

字段说明 #

字段	说明
id	审核项目 ID，提交任务时使用
title	审核项目名称
category	审核分类
province	适用地区

3. 提交审核任务 #

请求信息 #

请求方式：POST
请求地址：https://www.clipimg.com/app/picture_check_api.php/submit_task
Content-Type：推荐 application/json

请求参数 #

参数名	必填	说明
apikey	是	接入方 API 密钥
check_info_name	是	审核项目名称
check_img	是	待审核照片 URL
app_name	是	应用名称
order_id	是	接入方订单号，建议唯一
robot_id	是	审核项目 ID
callback_url	是	审核结果回调地址

请求示例 #

curl -X POST "https://www.clipimg.com/app/picture_check_api.php/submit_task" \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "YOUR_API_KEY",
    "check_info_name": "证件照自动审核",
    "check_img": "https://example.com/input.jpg",
    "app_name": "接入方业务系统",
    "order_id": "ORDER_20260330_0001",
    "robot_id": 1,
    "callback_url": "https://partner.example.com/api/picture-check/callback"
  }'

响应示例 #

{
  "code": 0,
  "data": null
}

说明：

code = 0 表示任务提交成功。
审核结果以后续回调或主动查询结果为准。
提交成功不代表审核已完成，需等待回调或主动查询最终状态。

4. 回调通知 #

回调方式 #

请求方式：POST
Content-Type：application/json
回调目标：提交任务时传入的 callback_url

回调示例 #

{
  "id": 12345,
  "order_id": "ORDER_20260330_0001",
  "app_name": "接入方业务系统",
  "check_info_name": "证件照自动审核",
  "check_status": 1,
  "checked_img": "https://oss-temporary-url...",
  "fail_msg": "",
  "timestamp": 1774838884
}

字段说明 #

字段	说明
id	平台任务 ID
order_id	接入方订单号
app_name	应用名称
check_info_name	审核项目名称
check_status	审核状态：`1`=通过，`2`=未通过
checked_img	审核通过后的照片地址，失败时为空
fail_msg	失败原因或说明
timestamp	回调时间戳

说明：

审核通过时，checked_img 为 OSS 临时访问地址，请尽快下载或转存。
回调接口建议按 order_id 做幂等处理。
若回调处理异常，建议立即返回非 2xx，并由业务侧触发主动查询兜底。

5. 主动查询任务结果 #

当接入方未收到回调，或回调处理失败时，可通过此接口主动查询结果。

请求信息 #

请求方式：GET
请求地址：https://www.clipimg.com/app/picture_check_api.php/query_task

请求参数 #

参数名	必填	说明
apikey	是	接入方 API 密钥
order_id	是	提交任务时传入的订单号

请求示例 #

curl "https://www.clipimg.com/app/picture_check_api.php/query_task?apikey=YOUR_API_KEY&order_id=ORDER_20260330_0001"

响应示例 #

{
  "code": 0,
  "data": {
    "id": 12345,
    "order_id": "ORDER_20260330_0001",
    "app_name": "接入方业务系统",
    "check_info_name": "证件照自动审核",
    "check_status": 1,
    "check_status_text": "通过",
    "checked_img": "https://oss-temporary-url...",
    "fail_msg": "",
    "create_time": "2026-03-30 12:00:00"
  }
}

说明：

check_status = 0：待处理
check_status = 1：通过
check_status = 2：未通过
建议以 query_task 查询结果作为最终一致性兜底。

6. 错误码 #

提交任务接口 #

code	说明
0	提交成功
1	apikey 无效
2	审核项目 ID 无效
3	入库失败
5	缺少 `callback_url`

主动查询接口 #

code	说明
0	查询成功
1	apikey 无效
6	`order_id` 不能为空
7	未查询到任务记录

7. 接入建议与注意事项 #

使用 order_id 作为业务唯一标识，并保证全局唯一，避免重复提交导致任务识别冲突。
回调接收与主动查询建议同时接入：回调用于低延迟，查询用于最终一致性兜底。
回调接口必须支持幂等处理，建议按 order_id 去重写入，重复通知不重复入库。
callback_url 建议使用稳定 HTTPS 地址，避免临时域名、重定向链路或频繁变更。
check_img 需为可公网访问的直链照片地址，且在审核期间保持可访问。
checked_img 为临时访问地址，收到后请尽快下载或转存，避免过期导致无法访问。
建议在你方系统记录完整审计信息：order_id、回调原文、查询原文、处理时间与状态。
建议设置超时与重试策略：提交超时可重试，同一 order_id 重试时应保持业务幂等。
联调上线前请覆盖以下场景：通过、未通过、回调失败、查询兜底、重复回调。