跳转到主要内容
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(不支持 PDF)。最大上传大小:5 MB(较大文件将被拒绝并返回 400)。图像在处理前会自动压缩至约 0.3 MB,因此极高的分辨率并不会提高准确性。

face_liveness_score_decline_threshold
number<float>
默认值:30

活体阈值(0–100)。活体 score 达到或低于此值将添加 LOW_LIVENESS_SCORE 警告并予以拒绝。调高此值可实施更严格的防欺骗攻击策略;超出 0–100 范围的值将返回 400。

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

30

age_estimation_decline_threshold
integer
默认值:18

可接受的最低估算年龄(周岁)。估算年龄低于该值将添加 AGE_BELOW_MINIMUM 警告并予以拒绝。设为 0 可禁用年龄检查(此时调用仅执行活体检测 + 年龄估算,不做出基于年龄的决策)。

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

18

rotate_image
boolean
默认值:false

为 true 时,服务会按 90 度递增(0、90、180、270)尝试输入图像,并使用人脸检测效果最佳的方向,这对于缺少 EXIF 方向信息的移动端拍摄非常有用。会增加延迟,因此仅在您无法保证图像为正向时启用。

示例:

false

save_api_request
boolean
默认值:true

为 true(默认)时,将此次调用持久化为 API 类型的会话,在 Business Console 中可见,可使用返回的 request_id 通过 GET /v3/session/{sessionId}/decision/ 检索,通过 status.updated Webhook 发出通知,并将检测到的人脸添加到您应用的人脸索引中。为 false 时,不存储任何内容,且 request_id 仅为用于关联响应的临时 UUID。

示例:

true

vendor_data
string

可选的不透明字符串(您的内部用户 ID、邮箱、UUID 等),存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联,并在稍后筛选会话。

示例:

"user-123"

metadata
object

与会话一同存储(当 save_api_request=true 时)并在响应中原样返回的可选 JSON 对象。在 multipart 请求中,请将其作为 JSON 编码的字符串字段发送(例如 metadata={"flow":"age-gate"}),它会被解析为对象。

示例:

响应

年龄估算和被动活体检测已完成。age_estimation.age_estimation 是模型预测的最大检测人脸年龄(以岁为单位,未检测到则为 null);age_estimation.score 是被动活体检测分数(0–100);仅当 warnings 为空时,status 才为 Approved。未成年或欺骗攻击的抓拍仍会返回 200 及 status: "Declined",请检查响应体,而不仅仅是 HTTP 状态码。当 save_api_request=true 时,request_id 为持久化的会话 ID。

request_id
string<uuid>

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

age_estimation
object
vendor_data
string | null

您发送的 vendor_data 回显,或 null。

metadata
object | null

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

created_at
string<date-time>

响应生成时的 ISO 8601 时间戳(UTC)。

最后修改于 2026年11月7日