跳转到主要内容
POST
curl
通过上传 base64 编码的人脸图像,将其添加到人脸黑名单或白名单中。Didit 会检测图像中的人脸,保留其中最大的人脸,存储图像及该人脸的裁剪图,并计算生物特征模板,新会话将与该模板进行比对。新条目的 value 即该人脸的 UUID。 仅适用于 entry_type: face 且 list_type: blocklist 或 list_type: allowlist 的名单。
如果您要将已有会话中的人脸加入黑名单或白名单,请改用 创建条目 并传入 reference_session_id:该条目会关联回对应会话。
图像必须包含清晰可见的人脸,且解码后不超过 2 MB。若未检测到人脸,请求将返回 400,且不会创建条目。若人脸分析服务暂时不可用,请求将返回 503:请稍后重试。
要将人脸从名单中移除,请删除其条目:删除后,该人脸将不再匹配新会话。

授权

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。

路径参数

list_uuid
string<uuid>
必填

entry_type: face 且 list_type: blocklist 或 allowlist 的列表的 UUID。

请求体

application/json
image
string<byte>
必填

Base64 编码的 JPEG 或 PNG,解码后最大 2 MB,展示清晰可见的人脸。请发送纯 Base64 字符串,不要包含 data:image/...;base64, 前缀。

comment
string
默认值:""

可选的自由文本备注,例如列入名单的原因。

响应

人脸条目已创建。

列表中的一个值。

uuid
string<uuid>
必填

条目标识符。在“删除列表条目”中用作 entry_uuid。

value
string
必填

列入名单的值:E.164 格式的电话号码、邮箱地址、证件号码、IP 地址或 CIDR 范围、设备指纹、钱包地址、银行账户、ISO 3166-1 alpha-3 国家/地区代码、vendor_data、key 名单上的任意字符串,或人脸名单上已存储人脸的 UUID。除电话号码和国家/地区代码外,您发送的值均以小写形式存储。匹配不区分大小写。

display_label
string | null
必填

便于人类阅读的标签。当您未提供时,Didit 会为从会话中获取的条目自动填充该标签(例如持有人姓名和证件号码)。

Maximum string length: 512
comment
string
必填

自由文本备注。未设置时为空字符串。

added_by
string | null
必填

添加此条目的主体:api(API 密钥)、控制台用户的邮箱地址或 console、system 或 migration(Didit 创建的条目),或者 rule(交易或监控规则操作)。

reference_session_id
string<uuid> | null
必填

该条目来源的验证会话。如果条目是按值添加的,则为 null。

reference_session_number
integer | null
必填

控制台中显示的该会话在应用范围内的编号。

reference_session_type
enum<string> | null
必填

个人验证会话为 kyc,企业验证会话为 kyb,不存在会话时为 null。

可用选项:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
必填

该条目代表的记录:从会话中读取的人脸、证件、电话或邮箱记录,通过“向列表上传人脸”创建的人脸,或您发送的 UUID(例如交易 UUID 或用户的 didit_internal_id)。

metadata
object | null
必填

额外上下文。包含 Didit 设置的键(在此列出)并合并您在创建条目时发送的任何 metadata,按存储原样返回。无内容时为 null。

created_at
string<date-time>
必填

条目添加的时间。

最后修改于 2026年11月7日