生物特征模板 API

默认情况下，删除验证会话也会删除该会话中为人脸搜索 1:N和重复检测提供支持的人脸特征向量。需要在会话删除后仍保持重复检测正常工作的应用，可以选择启用生物特征模板保留。启用后，Didit 会照常删除会话及其全部数据，但会保留一个单独管理、不含图像的人脸生物特征模板，并将其关联到该会话所属的用户。 Biometric Templates API 让您可以准确查看应用持有哪些模板、保留原因和保留期限，并可随时清除这些模板。每个模板也可在 Business Console 的 Lists → Biometric templates 中查看，并会显示在所属用户的个人资料中。

被保留的生物特征模板属于生物特征数据。它不是匿名数据，不是临时数据，也不会随会话一并删除。它将一直保留，直到预定到期时间、适用法律规定的更早期限、用户被删除、提出隐私擦除请求或被明确清除。仅当您的控制者指令和隐私声明涵盖模板保留时，才应启用该功能。

模板的创建方式

触发条件	`source_type`	指令来源
您在已启用保留的应用上删除会话，或在删除会话或批量删除会话中发送 `retain_face_embeddings: true`	`session_delete`	`instruction_source: api` 或 `console`
您应用的常规数据保留期限在已启用保留的应用上使某个会话到期	`automatic_retention`	`instruction_source: automatic_retention`
您指示 Didit 对您启用保留之前已删除的会话执行的回填操作	`backfill`	`instruction_source: backfill`

保留模板需要关联用户。未附带 vendor_data 创建的会话没有关联用户，因此无法保留模板。此类删除会返回 ineligible_no_vendor_user，人脸特征向量会随会话一并删除。

模板包含的内容

保留的内容	绝不保留的内容
用于比对的数值人脸模板	人脸图像、活体视频、证件图像、人像裁剪图以及任何其他媒体文件
新生成的随机模板 `uuid` 和不透明的 `provenance_reference`	已删除会话的 ID、编号、决策结果、提取的身份信息字段或特征 payload
所属用户（`vendor_user_uuid`）。读取模板时会从用户信息中解析 `vendor_data`，绝不复制	黑名单状态、既往比对结果、欺诈标签或跨组织身份声明
`retained_at`、`expires_at`、`retention_policy`、`retention_override`、`instruction_class`、`instruction_source`、`instruction_id`、`retained_by`、`retained_by_type`	操作者的邮箱地址

模板仅限于租户范围内使用，并且只能依据您在应用内的指示使用：包括重复人脸和多账户检测、生物识别认证，以及您自己的人脸名单。模板绝不用于模型训练、分析、跨组织比对、网络共享信号，或 Didit 独立的欺诈处理。

模板对象

{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}

字段	类型	说明
`uuid`	UUID	模板 ID。随机生成，不由已删除的会话或其人脸推导而来。
`vendor_user_uuid`	UUID	所属用户。
`vendor_data`	字符串或 null	用户当前的 `vendor_data`，在您读取模板时解析。
`source_type`	枚举	`session_delete`、`automatic_retention` 或 `backfill`。
`provenance_reference`	UUID	不透明引用，用于将模板与其审计追踪关联。它不是已删除会话的 ID，也无法通过 API 解析为该会话。
`retention_policy`	枚举	保留时适用的应用策略：`delete_with_session` 或 `retain_until_user_deleted`。
`retention_override`	布尔值或 null	删除请求中发送的 `retain_face_embeddings` 值；若适用的是策略，则为 `null`。
`retained_at`	日期时间	模板的创建时间。
`expires_at`	日期时间	模板到期并被自动清除的时间。始终有值。
`retained_by`	字符串	发出指令的主体：API 密钥对应应用 ID，控制台操作对应控制台成员 ID，自动保留对应 `service:` 标识符。绝不是邮箱地址。
`retained_by_type`	枚举	`API_KEY`、`CONSOLE_USER` 或 `SYSTEM`。
`instruction_class`	枚举	`operational_session_delete` 或 `privacy_erasure`。
`instruction_source`	枚举	`api`、`console`、`automatic_retention`、`backfill`、`privacy_erasure`、`explicit_template_purge`、`vendor_user_delete`、`expiry`、`reconciliation`、`migration` 或 `system`。
`instruction_id`	字符串	您在删除请求中发送的 `instruction_id`；若您未提供，则为 Didit 生成的 ID。
`held_out_of_use`	布尔值	仅在法律保全适用期间为 `true`。被暂停使用的模板会被排除在所有比对之外。参见法律保全。
`status`	枚举	生命周期状态，见下文。
`purged_at`	日期时间或 null	模板被清除的时间。

状态

`status`	含义	是否参与比对？
`pending`	模板正在创建中。如果创建该模板的删除请求返回 `503`，请重复该删除请求以完成创建。	否
`active`	模板在 `expires_at` 之前参与比对。	是，除非 `held_out_of_use` 为 `true` 或 `expires_at` 已过
`expired`	`expires_at` 已过，正在进行自动清除。	否
`held_out_of_use`	适用法律保全。	否
`purge_pending`	清除正在进行中。	否
`purge_failed`	由于某个生物特征存储不可用，清除未能完成。请重复清除操作；在此期间，该模板仍被排除在比对之外。	否
`purged`	模板已被删除。仅在清除响应中显示为 `already_purged`；已清除的模板不会出现在列表中，查询详情时返回 `404`。	否

模板如何用于比对

处于 active 状态的模板会参与与实时会话人脸完全相同的比对：新会话中的自动重复检测、独立的人脸搜索 API、生物识别认证，以及您的人脸名单。命中已保留模板时，结果会以 source: "retained_template"、所属用户的 vendor_user_id 和 vendor_data，以及 biometric_template_id 进行报告。结果中绝不包含会话 ID、比对图像、身份信息或状态，因为产生该人脸的会话已不复存在。参见人脸搜索报告。已保留的模板绝不会被加入黑名单。如果已删除会话中的人脸曾位于人脸黑名单中，该黑名单条目会保有自己独立的生物识别条目和生命周期：移除名单条目会删除黑名单条目，而清除模板不会影响名单。

清除时机

以下所有操作都会将模板移出比对范围，并删除已存储的模板：

清除时机	方式
显式清除	`DELETE /v3/biometric-templates/{uuid}/` 或 `POST /v3/biometric-templates/delete/`，或在控制台中进入 Lists → Biometric templates
用户删除	`POST /v3/users/delete/` 会在删除用户之前，清除所有关联到该用户的模板
隐私擦除	任何以 `deletion_instruction: "privacy_erasure"` 发送的、针对该用户会话的删除操作，都会清除所有关联到该用户的模板，无论应用策略如何
过期	模板的 `expires_at` 到期后，Didit 会自动清除该模板

将应用策略切换回 delete_with_session 会停止创建新模板，但不会清除已有模板。请对它们进行显式清除。清除操作会先删除已存储的模板，然后才将模板标记为已清除。因此，返回 503 的清除操作会使模板处于 purge_failed 状态：该模板已被排除在比对之外，并且可以安全地重复执行。对已清除模板的重复清除会返回 already_purged。

审计追踪

每一次保留和清除尝试，包括失败和不符合条件的结果，都会记录执行主体（retained_by / 清除主体及其类型）、instruction_class、instruction_source、instruction_id、provenance_reference 以及结果。删除时请发送您自己的 instruction_id，以便将 Didit 的审计追踪与您的擦除日志对应起来。审计条目绝不包含图像、向量、身份字段或电子邮件地址。

法律保全

法律保全是一种例外，绝不是一种保留模式。Didit 不会主动设置保全。保全只能依据您的数据处理协议中的书面指令，或主管机关的有约束力的命令而设置。保全生效期间，模板会被标记为 held_out_of_use：它会被排除在所有类型的比对和常规恢复之外，并且永远不可搜索。目前没有用于创建或解除保全的 API。如果您收到影响已保留模板的命令，请联系您的 Didit 客户代表。

权限与认证

生物识别模板端点仅接受应用 API 密钥（x-api-key）。商业控制台用户令牌会被拒绝，并返回 403。控制台用户需具备其 lists 权限，才能通过 Lists → Biometric templates 管理模板。

端点

端点	方法	用途
`/v3/biometric-templates/`	GET	带筛选条件的分页列表
`/v3/biometric-templates/count/`	GET	使用相同筛选条件统计数量
`/v3/biometric-templates/{template_uuid}/`	GET	获取单个模板
`/v3/biometric-templates/{template_uuid}/`	DELETE	清除单个模板
`/v3/biometric-templates/delete/`	POST	按 ID 列表或筛选条件清除

​模板的创建方式

​模板包含的内容

​模板对象

​状态

​模板如何用于比对

​清除时机

​审计追踪

​法律保全

​权限与认证

​端点

​相关内容

模板的创建方式

模板包含的内容

模板对象

状态

模板如何用于比对

清除时机

审计追踪

法律保全

权限与认证

端点

相关内容