跳转到主要内容
POST
curl

概述

当你从其他服务商导入用户,并且已经为每个人准备了可信的人脸图片时,请使用此 endpoint。用户仍然以你的 vendor_data 作为键,但此资料附件 endpoint 使用 didit_internal_id 来明确指定目标用户。
这与上传人脸到名单不同。资料上传会将人脸附加到用户上,用于留存证据、重复检测和人脸搜索。名单上传则会将人脸添加到人脸类型的黑名单中,使之后的匹配会话可以被拒绝。

endpoint

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

迁移流程

1

创建或查找用户

新建资料时调用 POST /v3/users/create/,已有资料时调用 GET /v3/users/{vendor_data}/。
2

存储 didit_internal_id

用户响应中包含 didit_internal_id。请继续在您的数据库中使用 vendor_data,仅在用户资料附件 endpoint 中使用 didit_internal_id。
3

上传人脸

在 image 字段中发送原始 base64 图片。后端会在保存前验证图片是否能够解码、图片大小以及是否检测到人脸。

示例

请求体

响应

验证与限制

  • 每个用户最多手动上传 5 张人脸。
  • 解码后的图片最大大小为 2 MB。
  • 图片必须是有效的 base64,并且能够解码为图片。
  • 图片中必须包含可检测的人脸。如有可能,请使用正面、光线充足的人脸裁剪图。
  • 上传的人脸会被索引,用于之后的重复检测和人脸搜索。
  • 上传的人脸不会自动加入黑名单。

列出或删除已上传的人脸

列出资料人脸:
删除一张资料人脸:

权限

使用同一应用的 API 密钥。该密钥所属的应用必须有权管理目标用户的资料。

失败情况

  • 400:base64 无效、图片无效、未检测到人脸、图片超过 2 MB,或该用户已上传 5 张人脸。
  • 401:缺少凭证或凭证无效。
  • 403:API 密钥有效,但无权管理该用户资料。
  • 404:应用中不存在该 didit_internal_id 对应的用户。
  • 429:请求受到速率限制;请根据 Retry-After 进行退避。

相关内容

授权

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。

路径参数

organization_id
string<uuid>
必填

拥有该应用的组织 UUID。

application_id
string<uuid>
必填

拥有该用户资料的应用 UUID。

didit_internal_id
string<uuid>
必填

Didit 内部用户 UUID,由 GET /v3/users/{vendor_data}/ 和 POST /v3/users/create/ 作为 didit_internal_id 返回。

请求体

application/json
image
string<byte>
必填

原始 base64 编码的 JPG 或 PNG 人脸图像。请勿包含 data:image/...;base64, 前缀。解码后的最大尺寸:2 MB。

comment
string
默认值:""

针对所上传人脸的可选备注,操作员可见。

响应

人脸已上传并附加到用户个人资料中。

uuid
string<uuid>
必填

已上传用户人脸记录的 UUID。

image_url
string<uri> | null
必填

已上传人脸图像的签名 URL。

comment
string | null
必填

上传人脸时提供的备注。

uploaded_by
string | null
必填

上传者的邮箱或操作者标识符(若可用)。

created_at
string<date-time>
必填

上传时间戳。

最后修改于 2026年11月7日