跳转到主要内容
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,因此极高的分辨率并不会提高准确度。图像必须包含至少一张可检测到的人脸,否则 endpoint 将返回 400。如果存在多张人脸,将搜索最大的人脸并添加 MULTIPLE_FACES_DETECTED 警告。

search_type
enum<string>
默认值:most_similar

搜索策略。most_similar(默认)按相似度对您应用中登记的所有人脸进行排序。blocklisted_or_approved 将候选范围限制在黑名单人脸、白名单人脸、已通过会话中的人脸以及导入的用户档案人脸,其中黑名单条目排在最前。

可用选项:
most_similar,
blocklisted_or_approved
示例:

"most_similar"

rotate_image
boolean
默认值:false

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

示例:

false

save_api_request
boolean
默认值:true

为 true(默认)时,将此次调用持久化为 API 类型会话,发出 status.updated Webhook,对 match_image_url 值进行预签名,并将搜索的人脸录入到您的人脸搜索索引中(人脸搜索录入项会从未来的搜索中排除)。为 false 时,搜索为单次执行,不存储会话,也不录入人脸。

示例:

true

vendor_data
string

可选的不透明标识符(您的用户 ID、邮箱、UUID 等),存储在持久化会话中并予以回显。它不会在搜索结果中排除同一用户的人脸。

示例:

"user-123"

metadata
object

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

示例:

响应

人脸搜索已完成。face_search.matches 包含最多 5 个按相似度排序的相似人脸;空数组表示没有录入的人脸超过相似度底限。仅在命中黑名单时 status 为 Declined;仅有重复匹配仍会返回 Approved,因此请检查 matches 和 warnings,而不仅仅是 status。当 save_api_request=true 时,request_id 为持久化的会话 ID。每个匹配项都包含 source(session、imported、list_entry 或 retained_template)、vendor_user_id 和 biometric_template_id;retained_template 匹配来源于在源会话删除后保留的无图像生物特征模板,其会话字段、match_image_url 和 user_details 均为 null。

request_id
string<uuid>

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

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日