跳转到主要内容
POST
cURL

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

multipart/form-data
user_image
file
必填

正面人脸图像(例如自拍照)。允许的文件扩展名:tiff、jpg、jpeg、png、webp。最大上传大小:5 MB(超出限制的文件将被拒绝并返回 400)。图像在处理前会自动压缩至约 0.5 MB,因此极高的分辨率并不会提高准确度。图像应仅包含一个拍摄主体。若存在多张人脸,将评估最大的人脸并添加 MULTIPLE_FACES_DETECTED 警告。

face_liveness_score_decline_threshold
number<float>
默认值:30

活体评分阈值(0–100)。计算得出的分数达到或低于此值将发出 LOW_LIVENESS_SCORE 警告,并将 status 设为 Declined。默认值为 30;调高此值可实施更严格的防欺骗攻击策略。超出 0–100 范围的值将返回 400。

必填范围: 0 <= x <= 100
示例:

30

rotate_image
boolean
默认值:false

为 true 时,服务会尝试按 90 度旋转输入内容的各个方向,并使用人脸检测效果最佳的方向。在缺少 EXIF 方向信息时非常有用。会增加延迟。

示例:

false

save_api_request
boolean
默认值:true

为 true(默认)时,将此次调用持久化为 API 类型会话,存储人脸图像,发出 status.updated Webhook,并将检测到的人脸录入到您的人脸搜索索引中。为 false 时,该调用为单次执行,不存储任何内容,也不录入人脸。黑名单和重复筛查在两种情况下都会运行。

示例:

true

vendor_data
string

可选的不透明标识符(您的用户 ID、邮箱、UUID 等),存储在持久化会话中并予以回显。还用于在重复人脸检查中排除具有相同 vendor_data 的先前会话,从而避免在重新验证同一用户时触发 DUPLICATED_FACE。

示例:

"user-123"

metadata
object

与会话一同存储(当 save_api_request=true 时)并原样返回的可选 JSON 对象。在 multipart 请求中,请将其作为 JSON 编码的字符串字段发送,它将被解析为对象。

示例:

响应

静默活体检测已完成。liveness.score 是模型对图像显示为活人的置信度(0–100);除非触发了 error 严重级别的警告,否则 status 为 Approved。欺骗攻击或处于黑名单的人脸仍会返回 200,请检查 liveness.status 和 liveness.warnings,而不仅仅是 HTTP 状态码。当 save_api_request=true 时,request_id 为持久化的会话 ID。

request_id
string<uuid>

当 save_api_request=true 时持久化的会话 ID(可用于 GET /v3/session/{sessionId}/decision/);否则为一个临时的关联 UUID。

liveness
object
vendor_data
string | null

您发送的 vendor_data 回显,或 null。

metadata
object | null

您发送的 metadata 对象回显,或 null。

created_at
string<date-time>

响应生成时的 ISO 8601 时间戳(UTC),例如 2026-06-12T01:04:42.763237+00:00。

最后修改于 2026年11月7日