先说流程

一次核验分两步：拉起拿到一个核验单号，查询拿结论。之所以不合成一次调用， 是因为采集要用户在自己手机上做，几十秒到几分钟都有可能 —— 一次调用挂在那儿等， 连接断了这一单就成了「钱扣了没结论」。分开之后，查询问多少遍都不花钱。

1. POST https://face.yunsapi.com/api/face_start      带上 name / idcard（有公网图就再带 file_url）
   ← { "code": 1001, "data": { "check_id": "K...", "live_url": "https://…" } }

2. 把 live_url 交给用户（手机打开，或者生成二维码让他扫），按提示做一遍活体采集

3. POST https://face.yunsapi.com/api/face_query      带上 check_id，隔几秒问一次，直到拿到 2xxx / 3xxx / 4xxx 里的一个
   ← { "code": 2001, "data": { "check_id": "K...", "state": 2001, "passed": true, "score": 92.4 } }

用户做完采集会落在我们这一页（live.php）—— 那一页不用登录，只把这一单的结论告诉做采集的本人（通过 / 没通过），并且顺手把这一单收尾。 页面的地址里带着这一单的随机单号，没单号打不开。 你那一侧还是要自己查：以 face_query.php 的返回为准，别拿用户截图当结论。

live_url 是要给人用手机打开的，电脑上展示可以现场把它画成二维码让他扫。 验签、订单这类业务判断必须放在你自己的服务端，别放在这一页的返回值上。

密钥怎么带

密钥是两样：密钥 ID（AK 开头，公开的）和密钥（只在控制台显示一次）。两样都要带，少一样就当没带。

POST https://face.yunsapi.com/api/face_start
Content-Type: application/x-www-form-urlencoded
X-Api-Id:  AK3F9C1D2E4B5A60
X-Api-Key: frs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

两样都在请求头时以请求头为准。浏览器里直接发请求会先来一次 OPTIONS 预检， 两个头都已经放行，不用另外配。

密钥 ID 可以随便露（日志里、报错里、找人问事时说出口都行）：它单独调不动接口， 但能拿来对账。密钥本体泄漏了就在控制台点「换密钥」—— ID 不变，你代码里那一行不用改。

一、拉起：api/face_start

{
  "code": 1001,
  "msg": "让用户去做人脸采集，做完之后拿 check_id 来查。",
  "data": {
    "check_id": "K20261007A1B2C3",
    "state": 1001,
    "live_url": "https://活体服务给的那条地址"
  }
}

这一步扣一次费。拉不起来的话这一笔当场退回，返回 code 3002（没做完活体）。

二、查询：api/face_query

查询不扣费，隔几秒问一次都行。HTTP 一律 200 —— 下面这些值是业务结论，看 body 里的 code，别看 HTTP。

返回码：四位数，第一位就是阶段

拿到码就知道该做什么：1 等着、2 是结论、3 让本人重做一次采集、4 重新发起一单。

data.passed 只在有明确结论时才出现：2001 是 true， 2002 / 2003 / 2004 / 3001 是 false。 其余那些码（还没出结果、这一次没拿到结论）不给这个字段 —— 给了等于替你下了「不是同一人」的结论，照着它做业务判断会出事。 data.score 同理，有分值时才有。

从拉起算起超过 300 秒还没有结论就按超时收尾：人没做完活体是 3002，卡在比对那一步是 4002，两种都已经退回。

{
  "code": 2001,
  "msg": "核验通过。",
  "data": { "check_id": "K20261007A1B2C3", "state": 2001, "passed": true, "score": 92.4 }
}

判定线是 60.00 分，达到就算同一人。

想一步出结论：api/face

如果你手上已经有能公网打开的人脸图，用这一个就够：把三个参数一次给全，它当场返回结论（只会有 2xxx 与 4xxx，不会有 1xxx）。它和上面两个接口走的是同一套判断，只是省掉了你去查询那一步。

HTTP 错误码

扣费只发生在拉起那一步（单价 0.40 元，或者扣一个次数）。查询不扣。标着「这一笔会退回」的那几种（2005/2006/2007/3002/4001/4002）不计费。

几个提醒