> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 人脸搜索 API：1:N 人脸去重与欺诈团伙识别 > Didit 的 POST /v3/face-search/ 支持跨已验证用户的 1:N 人脸搜索，可识别重复账户、欺诈团伙与重新认证。推理时间低于 2 秒，按次计费，无需签约。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/face-search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-search/: post: tags: - Standalone APIs summary: 人脸搜索 description: >- 将人脸图像与您应用的人脸搜索索引进行 1:N 搜索（该索引包含从验证会话中录入的人脸、已保存的独立 API 调用、直接上传的用户资料人脸，以及您的黑名单/白名单），并返回按相似度排序的匹配项以及黑名单和重复警告。 **工作原理。** 系统会对 `user_image` 中检测到的最大人脸提取特征向量，并在您应用专属的索引范围内进行搜索。`matches` 中最多返回 **5 个**高于相似度下限的匹配项，每项均包含 `similarity_percentage`、来源会话（`session_id`、`session_number`、`status`、`vendor_data`）、该会话证件验证期间提取的 `user_details`、`is_blocklisted` / `is_allowlisted` 标志，以及 `source` 区分字段（`session`、`imported` 或 `list_entry`）。 - `search_type=most_similar`（默认）：按相似度对所有已录入人脸进行排序，适用于去重和欺诈团伙排查。 - `search_type=blocklisted_or_approved`：将候选人脸限定为黑名单人脸、白名单人脸、来自已通过会话的人脸以及导入的用户资料人脸，并将黑名单条目排在最前；适用于主要目标为黑名单筛查的场景。 仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时，`status` 才会为 `Declined`；`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`（`information`）和 `MULTIPLE_FACES_DETECTED`（`warning`）绝不会导致拒绝。与静默活体检测（Passive Liveness）不同，该 endpoint **不会**在匹配中排除具有相同 `vendor_data` 的先前会话。内部还会运行静默活体检测分析并随持久化会话一同存储，但其结果不包含在本次响应中。 **计费。** 每次 `200` 响应消耗一个 Face Search API 额度（从您的套餐额度或充值余额中扣除）。余额不足时将在进行任何图像处理之前返回 `403`。 **会话持久化与人脸录入（`save_api_request`，默认为 `true`）。** 为 `true` 时，该调用将作为 API 类型的会话持久化（可在 Business Console 中查看，或通过返回的 `request_id` 调用 `GET /v3/session/{sessionId}/decision/`，并触发 `status.updated` Webhook），且被搜索的人脸会被录入到您的人脸搜索索引中。通过 Face Search 调用录入的人脸将在未来的 Face Search 结果中排除，因此重复搜索绝不会相互匹配。为 `false` 时，该调用为单次调用：不存储任何内容，不录入人脸，且 `match_image_url` 的值为内部存储路径而非可下载的 URL。 **沙盒。** 沙盒 API 密钥将跳过所有处理和计费：在请求验证通过后（格式错误的输入仍会返回 `400`），该 endpoint 返回静态的 `Approved` 模拟 payload，不持久化任何会话，且不消耗额度。 **身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺少凭据或凭据无效将返回 `403`（`{"detail": "You do not have permission to perform this action."}`），此 API 绝不返回 `401`。 **速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 之间共享每分钟 300 次请求的写入配额；超出限制将返回 `429`。 operationId: post_v3face-search parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- 用于搜索的正面人脸图像。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`。最大上传大小：**5 MB**（超出限制的文件将被拒绝并返回 `400`）。图像在处理前会自动压缩至约 0.5 MB，因此极高的分辨率并不会提高准确度。图像必须包含至少一张可检测到的人脸，否则 endpoint 将返回 `400`。如果存在多张人脸，将搜索最大的人脸并添加 `MULTIPLE_FACES_DETECTED` 警告。 search_type: type: string default: most_similar enum: - most_similar - blocklisted_or_approved description: >- 搜索策略。`most_similar`（默认）按相似度对您应用中登记的所有人脸进行排序。`blocklisted_or_approved` 将候选范围限制在黑名单人脸、白名单人脸、已通过会话中的人脸以及导入的用户档案人脸，其中黑名单条目排在最前。 example: most_similar rotate_image: type: boolean default: false description: >- 为 `true` 时，服务会尝试按 90 度旋转输入内容的各个方向，并使用人脸检测效果最佳的方向。在缺少 EXIF 方向信息时非常有用。会增加延迟。 example: false save_api_request: type: boolean default: true description: >- 为 `true`（默认）时，将此次调用持久化为 API 类型会话，发出 `status.updated` Webhook，对 `match_image_url` 值进行预签名，并将搜索的人脸录入到您的人脸搜索索引中（人脸搜索录入项会从未来的搜索中排除）。为 `false` 时，搜索为单次执行，不存储会话，也不录入人脸。 example: true vendor_data: type: string description: >- 可选的不透明标识符（您的用户 ID、邮箱、UUID 等），存储在持久化会话中并予以回显。它不会在搜索结果中排除同一用户的人脸。 example: user-123 metadata: type: object additionalProperties: true description: >- 与会话一同存储（当 `save_api_request=true` 时）并原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送，它将被解析为对象。 example: flow: dedup_check example: user_image: (binary JPEG/PNG selfie) search_type: most_similar rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: dedup_check responses: '200': description: >- 人脸搜索已完成。`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`。 content: application/json: examples: Blocklist hit (Declined): summary: 该人脸与黑名单中的人脸匹配 value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef face_search: status: Declined total_matches: 1 matches: - session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: 323442 similarity_percentage: 99.99 source: session vendor_data: user-1 verification_date: '2025-01-01T00:00:00Z' user_details: full_name: Jane Marie Doe document_type: ID document_number: X1234567 match_image_url: https:///face/3f6a1c2e/reference.jpg status: Approved is_blocklisted: true is_allowlisted: false api_service: null vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: null user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 323442 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Duplicate found (Approved): summary: 该人脸已出现在另一个已通过的会话中：提示信息，不予拒绝 value: request_id: 5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f face_search: status: Approved total_matches: 1 matches: - session_id: 1f2e3d4c-5b6a-7980-1122-334455667788 session_number: 1024 similarity_percentage: 87.42 source: session vendor_data: user-9 verification_date: '2025-11-20T09:15:00Z' user_details: null match_image_url: https:///face/9c8b7a6d/reference.jpg status: Approved is_blocklisted: false is_allowlisted: false api_service: PASSIVE_LIVENESS vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: null user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: - risk: DUPLICATED_FACE feature: LIVENESS additional_data: duplicated_session_id: 1f2e3d4c-5b6a-7980-1122-334455667788 duplicated_session_number: 1024 api_service: PASSIVE_LIVENESS log_type: information short_description: Duplicated face from other approved session long_description: >- The system identified a duplicated face from another approved session, requiring further investigation. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' No matches (Approved): summary: 没有已录入的人脸超过相似度下限 value: request_id: 9d8c7b6a-5f4e-3d2c-1b0a-998877665544 face_search: status: Approved total_matches: 0 matches: [] user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- 当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。 face_search: type: object properties: status: type: string enum: - Approved - Declined description: >- 仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时为 `Declined`。重复匹配和多张人脸警告绝不会导致拒绝。 total_matches: type: integer description: '`matches` 中的条目数量（0–5）。' example: 1 matches: type: array maxItems: 5 description: >- 人脸搜索索引中超过相似度下限的最多 5 张人脸，按相似度排序（当 `search_type=blocklisted_or_approved` 时，黑名单条目排在最前）。当没有已录入的人脸达到足够的相似度时为空。 items: type: object properties: session_id: type: string format: uuid nullable: true description: >- 匹配人脸所属验证会话的 ID。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。 example: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: type: integer nullable: true description: >- 在 Business Console 中显示的便于人类阅读的会话编号。对于非会话匹配项为 `null`。 example: 323442 similarity_percentage: type: number format: float minimum: 0 maximum: 100 description: 提交的人脸与匹配人脸之间的相似度（0–100）。 example: 99.99 source: type: string enum: - session - imported - list_entry - retained_template description: >- 比对人脸的录入来源：`session` — 验证会话或已保存的独立 API 调用；`imported` — 直接上传至用户资料的人脸；`list_entry` — 附加到您某个名单中的人脸；`retained_template` — 存储在用户资料中的无图像生物特征模板，列于 `/v3/biometric-templates/` 下。 vendor_data: type: string nullable: true description: 比对成功的会话或导入及保留模板人脸所关联用户的 `vendor_data`。 example: user-1 vendor_user_id: type: string format: uuid nullable: true description: 关联的用户 ID。名单条目和无用户的会话匹配为 `null`。 example: 2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4 biometric_template_id: type: string format: uuid nullable: true description: >- 保留的生物特征模板 ID。仅在 `source` 为 `retained_template` 时设置；否则为 `null`。 example: null verification_date: type: string format: date-time nullable: true description: >- 匹配的人脸最初被采集的时间，或保留的模板创建的时间（`YYYY-MM-DDThh:mm:ssZ`）。对于 `list_entry` 匹配为 `null`。 example: '2025-01-01T00:00:00Z' user_details: type: object nullable: true description: >- 在匹配会话的证件验证期间提取的身份数据。当匹配会话没有证件数据（例如仅活体检测会话）时为 `null`，且对于 `retained_template` 匹配始终为 `null`。对于 `source: imported` 匹配，该字段改由用户档案填充：设置了 `full_name`，`document_type`/`document_number` 为 null。 properties: full_name: type: string nullable: true example: Jane Marie Doe document_type: type: string nullable: true example: ID document_number: type: string nullable: true example: X1234567 match_image_url: type: string nullable: true description: >- `save_api_request=true` 时匹配人脸参考图像的有时限的 URL（`https:///...`）。当 `save_api_request=false` 时，这是无法直接下载的内部存储路径。对于 `retained_template` 匹配项始终为 `null`，因为保留的模板不包含图像。 example: https:///face/3f6a1c2e/reference.jpg status: type: string nullable: true description: >- 匹配会话的状态（`Approved`、`Declined`、`In Review` 等）。对于 `imported`/`list_entry` 匹配为 `null`。 example: Approved is_blocklisted: type: boolean description: 当比对出的人脸在您的人脸黑名单中时为 `true`。任何足够相似的黑名单匹配都会使搜索被拒绝。 is_allowlisted: type: boolean description: 当比对出的人脸位于您的白名单中时为 `true`。白名单中的匹配会静默重复警告。 api_service: type: string nullable: true description: >- 当比对的人脸是通过独立 API 调用（例如 `PASSIVE_LIVENESS`）录入时设置；对于常规验证会话和导入的人脸，该值为 `null`。 example: null user_image: type: object description: 已提交图像的人脸检测结果。此处的条目仅包含 `bbox` 和 `confidence`。 properties: entities: type: array description: 每张检测到的人脸对应一个条目。以最大的人脸为准进行搜索。 items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: 像素边界框 `[x_min, y_min, x_max, y_max]`。 example: - 40 - 40 - 120 - 120 confidence: type: number format: float minimum: 0 maximum: 1 description: 人脸检测置信度（0–1）。 example: 0.732973 best_angle: type: integer description: >- 产生最佳人脸检测结果的旋转角度（度）；仅当 `rotate_image=true` 纠正了方向时才为非零值。在此 endpoint 上永不为 null（当模型省略该值时默认为 0）。 example: 0 warnings: type: array description: >- 风险信号。`FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`（`error`）将拒绝搜索；`MULTIPLE_FACES_DETECTED`（`warning`）和 `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`（`information`）为参考性提示。 items: type: object properties: risk: type: string enum: - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: 机器可读的风险代码。 feature: type: string enum: - LIVENESS description: 引发该警告的功能。在此 endpoint 上始终为 `LIVENESS`。 additional_data: type: object nullable: true additionalProperties: true description: >- `MULTIPLE_FACES_DETECTED` 时为 `null`。命中黑名单时带有 `{blocklisted_session_id, blocklisted_session_number, api_service}`；命中重复项时带有指向首个匹配会话的 `{duplicated_session_id, duplicated_session_number, api_service}`。 log_type: type: string enum: - error - warning - information description: >- 严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning` 和 `information` 条目仅供参考，本身绝不会导致拒绝。 short_description: type: string description: 易于阅读的单行风险摘要。 long_description: type: string description: 风险的便于人类阅读的说明。 vendor_data: type: string nullable: true description: 您发送的 `vendor_data` 回显，或 `null`。 metadata: type: object nullable: true additionalProperties: true description: 您发送的 `metadata` 对象回显，或 `null`。 created_at: type: string format: date-time description: >- 响应生成时的 ISO 8601 时间戳（UTC），例如 `2026-06-12T01:04:42.763237+00:00`。 '400': description: >- 验证错误。当 `user_image` 缺失、超过 5 MB、扩展名不受支持，或者提交的图像中**未检测到人脸**时返回。字段错误使用 DRF 的 `{field: [messages]}` 响应格式；人脸检测失败使用 `{"error": ...}`。 content: application/json: examples: No face detected: summary: 图像解码正常，但未包含可检测到的人脸 value: error: No face detected in the image Missing image: summary: 表单数据中未包含 `user_image` value: user_image: - No file was submitted. Unsupported file extension: summary: 文件扩展名不在 tiff/jpg/jpeg/png/webp 范围内 value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: 上传内容超过 5 MB 限制 value: user_image: - File size should not exceed 5 MB '403': description: >- 权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{"detail": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{"error": ...}`。 content: application/json: examples: Missing or invalid API key: summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销 value: detail: You do not have permission to perform this action. Not enough credits: summary: 组织余额不足以支付本次调用 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。 content: application/json: examples: Write rate limit exceeded: summary: 当前分钟内的写入请求超过 300 次 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-search/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'search_type=most_similar' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_search.search( user_image=open("user_image.jpg", "rb"), search_type="most_similar", rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "dedup_check"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceSearch.search({ user_image: await fileFromPath("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceSearchSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceSearch().search(FaceSearchSearchParams.builder() .userImage(Path.of("user_image.jpg")) .searchType(FaceSearchSearchParams.SearchType.of("most_similar")) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "dedup_check")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceSearch->search([ 'user_image' => File::fromPath('user_image.jpg'), 'search_type' => 'most_similar', 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'dedup_check'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_search.search( user_image: Pathname("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams { UserImage = FileUpload.FromPath("user_image.jpg"), SearchType = new FaceSearchSearchParamsSearchType("most_similar"), RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "dedup_check" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.