> ## 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：生物特征名单 > 通过 Didit 将 base64 人脸图片上传至人脸黑名单或白名单。Didit 会提取生物特征，并在之后的人脸比对中使用。 上传人脸至名单 API 提示词 将提示词复制到剪贴板 \

\`Upload a face image directly to a Didit face blocklist or allowlist through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Add a face to a face blocklist or allowlist when I do not have a verification session to reference. Didit detects the faces in the image, keeps the largest one, stores the image and a crop of that face, computes a biometric face template that new sessions are compared against, and creates the entry.
\- A face blocklist entry declines future sessions whose face matches. A face allowlist entry stops a matching face from triggering the duplicated-face action, but does not override blocklist matches or the other checks.

When NOT to use this:
\- If I am listing a face from an existing verification session, use POST /v3/lists/{list_uuid}/entries/ with reference_session_id instead, so the entry links back to the session.

Path parameter:
\- list_uuid: must be a list with entry_type "face" and list_type "blocklist" or "allowlist". Other lists return 400.

Request body (application/json):
\{
"image": "/9j/4AAQSkZ...",        // required: base64-encoded JPEG or PNG, at most 2 MB once decoded. Do not include a "data:image/..." prefix.
"comment": "Known fraud attempt"  // optional
}

Important constraints:
\- The image must show a clearly visible face. If no face is detected, the API returns 400 and no entry is created. If it shows several faces, Didit uses the largest one.
\- In a sandbox application the image is not analysed or stored: the entry has display_label "Sandbox face entry" and metadata.sandbox true, and matches nothing.

Example call:
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"image": "/9j/4AAQSkZ...", "comment": "Known fraud attempt"}'

Example response (201):
\{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"value": "44444444-5555-6666-7777-888888888888",
"display_label": "Manually uploaded face",
"comment": "Known fraud attempt",
"added_by": "api",
"reference_session_id": null,
"reference_session_number": null,
"reference_session_type": null,
"reference_object_uuid": "44444444-5555-6666-7777-888888888888",
"metadata": { "reference_image_url": "https:///face_reference_image.jpg" },
"created_at": "2026-10-12T10:12:18.904467Z"
}

value and reference_object_uuid are the UUID of the new face. metadata.reference_image_url is a short-lived signed URL (null for a scoped key without media: read).

Failure modes:
\- 400: the list is not a face list ({ "detail": "Face upload is only available for face-type lists." }), the list is a custom face list, image is missing, larger than 2 MB, not valid base64, not a readable JPEG or PNG, or shows no face ({ "image": "No face detected in the image. Please upload a clear photo with a visible face." }).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 404: list not found in this application ({ "detail": "List not found." }).
\- 503: face analysis is temporarily unavailable; no entry was created, retry later.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- The face template is added to biometric matching. Future sessions matching a blocklisted face are declined. Future sessions matching an allowlisted face skip the duplicated-face action and include an informational allowlist warning.

For the full integration shape, see /integration/integration-prompt.`

\
粘贴到 通过上传 base64 编码的人脸图像，将其添加到人脸黑名单或白名单中。Didit 会检测图像中的人脸，保留其中最大的人脸，存储图像及该人脸的裁剪图，并计算生物特征模板，新会话将与该模板进行比对。新条目的 `value` 即该人脸的 UUID。仅适用于 `entry_type: face` 且 `list_type: blocklist` 或 `list_type: allowlist` 的名单。> [!TIP] > > 如果您要将**已有会话**中的人脸加入黑名单或白名单，请改用 [创建条目](https://docs.didit.me/zh/management-api/lists/create-entry.md) 并传入 `reference_session_id`：该条目会关联回对应会话。> [!WARNING] > > 图像必须包含清晰可见的人脸，且解码后不超过 2 MB。若未检测到人脸，请求将返回 `400`，且不会创建条目。若人脸分析服务暂时不可用，请求将返回 `503`：请稍后重试。要将人脸从名单中移除，请[删除其条目](https://docs.didit.me/zh/management-api/lists/delete-entry.md)：删除后，该人脸将不再匹配新会话。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/lists/{list_uuid}/entries/face-upload/ 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/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: 将人脸上传至名单 description: >- 通过 Base64 编码的 JPEG 或 PNG 图像向人脸黑名单或人脸白名单添加人脸，适用于您没有可供引用的验证会话的情况。Didit 会检测图像中的人脸，采用最大的一张，并创建一个条目，其 `value` 和 `reference_object_uuid` 为新人脸的 UUID。列入黑名单的人脸将拒绝与其匹配的新会话；列入白名单的人脸将跳过重复人脸操作，且绝不会覆盖黑名单匹配。在沙盒应用中，图像不会被分析，条目也不会匹配任何内容。有作用域限制的 API 密钥需要具备 `workflows: write` 权限。若要从现有会话中将人脸列入名单，请改用带 `reference_session_id` 的[创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry)。 operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: '`entry_type: face` 且 `list_type: blocklist` 或 `allowlist` 的列表的 UUID。' schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Base64 编码的 JPEG 或 PNG，解码后最大 2 MB，展示清晰可见的人脸。请发送纯 Base64 字符串，不要包含 `data:image/...;base64,` 前缀。 comment: type: string default: '' description: 可选的自由文本备注，例如列入名单的原因。 examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: 人脸条目已创建。 content: application/json: schema: $ref: '#/components/schemas/ComplianceListEntry' examples: Uploaded face: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Manually uploaded face comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: reference_image_url: >- https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c created_at: '2026-10-12T10:12:18.904467Z' Sandbox application: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Sandbox face entry comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: sandbox: true created_at: '2026-10-12T10:12:18.904467Z' '400': description: 该名单不接受人脸上传，或者图片缺失、无效、过大或未显示可用的人脸。未创建任何条目。 content: application/json: examples: Not a face list: value: detail: Face upload is only available for face-type lists. Custom face list: value: detail: >- Face upload is only available for face blocklists and allowlists. Missing image: value: image: - This field is required. Invalid base64: value: image: - Invalid base64 encoding. Too large: value: image: - Image exceeds maximum size of 2 MB. Unreadable image: value: image: Invalid image. Provide a valid base64-encoded JPG or PNG. No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. No usable face: value: image: Could not extract face embedding. Try a different image. '401': description: 作用域 API 密钥已过期。其他身份验证失败将返回 `403`。 content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- 缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。 content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '404': description: API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。 content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: 人脸分析暂时不可用。未创建任何条目；请稍后重试。 content: application/json: examples: Unavailable: value: detail: Service temporarily unavailable. Please try again later. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d "{\"image\": \"$(base64 < face.jpg | tr -d '\n')\", \"comment\": \"Known fraud attempt\"}" - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQAAAQABAAD...", comment="Known fraud attempt", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.lists.entries.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.ListsEntriesUploadFaceParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.lists().entries().uploadFace("11111111-2222-3333-4444-555555555555", ListsEntriesUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQAAAQABAAD...") .comment("Known fraud attempt") .build()); System.out.println(result); - lang: php label: PHP source: >- lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...', 'comment' => 'Known fraud attempt', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Lists.Entries.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQAAAQABAAD...", Comment = "Known fraud attempt", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: ComplianceListEntry: type: object description: 列表中的一个值。 required: - uuid - value - display_label - comment - added_by - reference_session_id - reference_session_number - reference_session_type - reference_object_uuid - metadata - created_at properties: uuid: type: string format: uuid description: 条目标识符。在“删除列表条目”中用作 `entry_uuid`。 value: type: string description: >- 列入名单的值：E.164 格式的电话号码、邮箱地址、证件号码、IP 地址或 CIDR 范围、设备指纹、钱包地址、银行账户、ISO 3166-1 alpha-3 国家/地区代码、`vendor_data`、`key` 名单上的任意字符串，或人脸名单上已存储人脸的 UUID。除电话号码和国家/地区代码外，您发送的值均以小写形式存储。匹配不区分大小写。 display_label: type: string nullable: true maxLength: 512 description: 便于人类阅读的标签。当您未提供时，Didit 会为从会话中获取的条目自动填充该标签（例如持有人姓名和证件号码）。 comment: type: string description: 自由文本备注。未设置时为空字符串。 added_by: type: string nullable: true description: >- 添加此条目的主体：`api`（API 密钥）、控制台用户的邮箱地址或 `console`、`system` 或 `migration`（Didit 创建的条目），或者 `rule`（交易或监控规则操作）。 reference_session_id: type: string format: uuid nullable: true description: 该条目来源的验证会话。如果条目是按值添加的，则为 `null`。 reference_session_number: type: integer nullable: true description: 控制台中显示的该会话在应用范围内的编号。 reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: 个人验证会话为 `kyc`，企业验证会话为 `kyb`，不存在会话时为 `null`。 reference_object_uuid: type: string format: uuid nullable: true description: >- 该条目代表的记录：从会话中读取的人脸、证件、电话或邮箱记录，通过“向列表上传人脸”创建的人脸，或您发送的 UUID（例如交易 UUID 或用户的 `didit_internal_id`）。 metadata: type: object nullable: true additionalProperties: true description: >- 额外上下文。包含 Didit 设置的键（在此列出）并合并您在创建条目时发送的任何 `metadata`，按存储原样返回。无内容时为 `null`。 properties: reference_image_url: type: string description: >- 人脸条目：短期有效的签名 URL，每次调用都会重新签发；对于没有 `media: read` 权限的作用域 API 密钥为 `null`。当没有图像属于该条目时不存在。 front_image_url: type: string description: >- 包含证件正面图像的证件条目：短期有效签名 URL，每次调用都会重新签发；对于缺少 `media: read` 权限的有作用域 API 密钥，该值为 `null`。 full_name: type: string description: 从会话中提取的证件条目：持有人姓名。 issuing_state: type: string description: 从会话中提取的证件条目：ISO 3166-1 alpha-3 签发国家/地区。 document_type: type: string description: 从会话中提取的证件条目：证件类型代码，例如 `P`、`ID` 或 `DL`。 region: type: string description: 从会话中提取的证件条目：地方签发证件的签发州或省份，不适用时为空。不会由“将会话条目添加到黑名单”操作设置此项。 document_number: type: string description: 从会话中提取的证件条目：证件号码。 face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: 取自证件拍摄自拍照的人脸条目：具体是哪张自拍照。对于活体检测人脸则不存在。 reference_node_id: type: string nullable: true description: 取自证件拍摄自拍照的人脸条目：该自拍照来源的身份证件验证节点。 fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- 从会话中获取的设备指纹条目：指纹的派生方式。`persistent_id` 用于标识单个设备；同一型号的设备可能会共享 `composite_hash` 和 `legacy_fp`。 sandbox: type: boolean description: 在沙盒应用中上传的人脸条目上为 `true`；此类条目不会匹配任何内容。 reference_type: type: string enum: - transaction - vendor_user - vendor_business description: 由您设置：`reference_object_uuid` 所指向的内容，以便控制台能够反向链接到该对象。 reference_id: type: string description: 由您设置：源记录的标识符。 created_at: type: string format: date-time description: 条目添加的时间。 responses: RateLimitedWrite: description: 已超出每个 API 密钥每分钟 300 次请求的共享写入限制。在重试之前请遵循 `Retry-After`。 content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. 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.