创建流程POST

从您的后端创建 Human Token 流程，并在 data.humanToken 中获取 humanToken。

Markdown

Human Token 运行在 Human API 的 POST /client/v1/process 端点上。使用 API Only 流程（api+humantoken、api+liveness+humantoken 和 api+liveness+humantoken+revalidation）时，流程在一次调用中完成创建和结束：响应中已在 data.humanToken 里携带结果。使用 Human Token Journey 流程（humantoken 和 humantoken+revalidation）时，响应包含流程的 id、token 和旅程的 link，用户完成旅程后即可获取结果。+revalidation 流程需要一个 references 数组，其中包含先前获取的 humanToken 用于重新验证。

流程

Human Token 支持两种集成模式：

• API Only — 您的后端在 imageBase64 中发送自拍。
• Human Token Journey — 用户在 Web 上完成 Unico 旅程，然后返回您的 callbackUri。

Flow	Capabilities	Possible result	Integration components required	Example
api+humantoken	Human Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken	LivenessHuman Token	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
api+liveness+humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	LivenessHuman Token	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb
humantoken+revalidation	LivenessHuman TokenRevalidation	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED	APIWeb

端点

环境	URL
生产环境	POST https://humantoken.unico.app/client/v1/process

请求

请求头

Header	值
x-unico-accesskey	<your_access_key>（参见身份验证）
Content-Type	application/json

请求体参数

字段	类型	必填	描述
flow	string	是	Human Token 流程：api+humantoken、api+liveness+humantoken、api+liveness+humantoken+revalidation（API Only）或 humantoken、humantoken+revalidation（Human Token Journey）。参见流程。
imageBase64	string	API Only	由您的前端采集并直接发送的自拍，base64 编码。支持 PNG、JPEG 或 WebP，最大 800 KB。请遵循采集标准。
callbackUri	string	Human Token Journey	旅程结束后用户被重定向到的 URL。
companyBranchId	string	否	分支标识符。提供时，流程将使用指定分支的配置。
references	array	重新验证流程	引用对象数组。+revalidation 流程必填。每个对象包含 referenceType（REFERENCE_TYPE_HUMAN_TOKEN）和 referenceContent（之前获取的 humanToken 值）。

响应

200 OK

字段	类型	描述
id	string (UUID)	流程标识符。可通过获取流程再次查询该流程。
state	string	流程状态 — 参见 解读结果。仅在 API Only 流程中返回。
token	string	已创建流程的令牌，您可以使用它来打开 Journey SDK 体验。仅在 Human Token Journey 流程（humantoken、humantoken+revalidation）中提供。
link	string	Human Token Journey 的 URL：将用户引导至该地址。仅在 Human Token Journey 流程（humantoken、humantoken+revalidation）中返回。
data.​humanToken.​value	string	人脸的稳定、不透明标识符（最多 100 个字符）。同一个人始终解析为相同的值。仅在 API Only 流程中返回（非重新验证）。
data.​humanTokenMatch	string	如果自拍与引用的 humanToken 匹配则为 "true"，否则为 "false"。仅在 +revalidation API Only 流程中返回。

解读结果

state	含义	处理方式
PROCESS_STATE_FINISHED	data.humanToken.value 有值：真人，具有 Human Token。	在您的记录中查找 value：如果存在，则为回访用户或可能的重复；如果不存在，则为新的人员。
PROCESS_STATE_FINISHED	没有 data.humanToken，或 value 为空：无法判定。	将其视为无法确定的结果。切勿存储或匹配空的 value；根据您的业务规则重试流程或拒绝。
PROCESS_STATE_FAILED	识别过程失败。	根据您的业务规则，重试该流程或拒绝。
PROCESS_STATE_CREATED	流程已创建。	请等待。稍后通过获取流程获取结果。
PROCESS_STATE_CANCELED	流程已取消。	如果仍需验证该用户，请创建新流程。

警告

使用 data.humanToken.value 之前，请务必确认其不为空。

错误代码

备注

当 x-unico-accesskey 请求头中的访问密钥缺失或无效时返回的 HTTP 状态码仍在确认中。参见身份验证。

400 Bad Request

代码	消息	描述
3	invalid flow	指定的流程不存在时。
3	INVALID_IMAGE	图像不是有效的 base64，或疑似注入攻击时。
3	IMAGE_TOO_LARGE	图像超过 800 KB 的大小上限时。
3	UNSUPPORTED_IMAGE_FORMAT	图像格式不是 PNG、JPEG 或 WebP 时。
3	MISSING_IMAGE	该流程需要图像但未发送时。
3	INVALID_REQUEST	请求体为空或无法解析时。
9	monthly process limit of <monthly_limit> reached for this tenant	当已达到每月使用限制时。
9	PROCESS_FAILED	流程在创建过程中进入终止失败状态时。

403 Forbidden

代码	消息	描述
7	PERMISSION_DENIED	凭据有效但无权执行此操作时。

429 Too Many Requests

已达到速率限制。当您的系统收到 HTTP 429 错误时，必须实施机制以防止级联故障并避免加重限制。

最佳实践：

• 冷却期（backoff）： 立即停止或限制系统的后续请求。不要在紧密循环中持续重试失败的请求。
• 排队与限流（Queueing & throttling）： 在您的一侧缓冲或排队传出请求，以便在重新发送之前控制流量。
• 带抖动的指数退避（Exponential backoff with jitter）： 重试时，在尝试之间以指数方式增加等待时间（例如，1秒、2秒、4秒、8秒），并添加一个小的随机延迟（"抖动"），以防止所有排队请求在完全相同的毫秒重试的羊群效应。

警告

在未应用退避的情况下持续请求受速率限制的端点，可能会延长限制期并严重影响系统的运行吞吐量。在您的一侧正确限流请求可确保更顺畅、更具弹性的集成。

有关默认限制、增加请求及其他详细信息，请参阅速率限制。

500 Internal Server Error

代码	消息	描述
13	Internal failure! Try again later	发生内部错误时。

有关该端点的完整代码列表，请参见 Human API 的创建流程参考。

后续步骤

• 将 humanToken 值与您的用户记录一同存储，以便在后续的 Human Token 调用中识别同一个人。
• 如需再次查询该流程（用于审计或技术支持），请使用获取流程。