> ## 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 人脸图像。该用户需已通过 vendor_data 创建或导入，才能使用本接口上传。 上传用户人脸提示 将提示词复制到剪贴板 \

\`Goal: Attach a trusted imported face image to an existing Didit User profile.

Use case: I am migrating users from another provider. I already have a stable vendor_data and a face image I am allowed to process. I want the User profile to carry that face for evidence, duplicate detection, and face search.

Flow:
1\. Create or retrieve the User by vendor_data:
POST https://verification.didit.me/v3/users/create/
GET  https://verification.didit.me/v3/users/{vendor_data}/
2\. Read didit_internal_id from the User response.
3\. Upload the face to:
POST https://verification.didit.me/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Auth: x-api-key for the same application.
Content-Type: application/json

Request body:
\- image (string, required) — raw base64-encoded JPG or PNG. Do not include a data URL prefix. Max decoded size: 2 MB.
\- comment (string, optional) — operator-visible note, for example "Imported from previous KYC provider".

Response 201:
\{
"uuid": "face-upload-uuid",
"image_url": "https://signed-url.example/...",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}

Limits:
\- Max 5 manually uploaded faces per User.
\- The image must decode as an image and contain a detectable face.
\- This enrolls the face for profile evidence and matching. It does not add the face to a blocklist.

To block a face, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list instead.`

\
粘贴到 ## 概述当你从其他服务商导入用户，并且已经为每个人准备了可信的人脸图片时，请使用此 endpoint。用户仍然以你的 `vendor_data` 作为键，但此资料附件 endpoint 使用 `didit_internal_id` 来明确指定目标用户。> [!NOTE] > > 这与[上传人脸到名单](https://docs.didit.me/zh/management-api/lists/upload-face.md)不同。资料上传会将人脸附加到用户上，用于留存证据、重复检测和人脸搜索。名单上传则会将人脸添加到人脸类型的黑名单中，使之后的匹配会话可以被拒绝。## endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## 迁移流程**1. 创建或查找用户**新建资料时调用 [`POST /v3/users/create/`](https://docs.didit.me/zh/management-api/users/create)，已有资料时调用 [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/zh/management-api/users/get)。**2. 存储 didit\_internal\_id**用户响应中包含 `didit_internal_id`。请继续在您的数据库中使用 `vendor_data`，仅在用户资料附件 endpoint 中使用 `didit_internal_id`。**3. 上传人脸**在 `image` 字段中发送原始 base64 图片。后端会在保存前验证图片是否能够解码、图片大小以及是否检测到人脸。## 示例```bash theme={null} # 1. Create the User keyed by your external id curl -X POST https://verification.didit.me/v3/users/create/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vendor_data": "user-42", "display_name": "Jane Doe", "metadata": { "previous_provider": "legacy-kyc-vendor" } }' # 2. Upload an imported face to the returned didit_internal_id curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image": "", "comment": "Imported from previous KYC provider" }' ```## 请求体| 字段 | 类型 | 是否必填 | 说明 | | - | - | - | - | | `image` | string | 是 | 原始 base64 编码的 JPG 或 PNG 图片。请勿包含 `data:image/...;base64,`。解码后的最大大小：2 MB。 | | `comment` | string | 否 | 显示在用户资料上、供操作员查看的备注。 |## 响应```json theme={null} { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "image_url": "https://signed-url.example/face.jpg", "comment": "Imported from previous KYC provider", "uploaded_by": "api", "created_at": "2026-05-18T12:00:00Z" } ```## 验证与限制- 每个用户最多手动上传 5 张人脸。 - 解码后的图片最大大小为 2 MB。 - 图片必须是有效的 base64，并且能够解码为图片。 - 图片中必须包含可检测的人脸。如有可能，请使用正面、光线充足的人脸裁剪图。 - 上传的人脸会被索引，用于之后的重复检测和人脸搜索。 - 上传的人脸不会自动加入黑名单。## 列出或删除已上传的人脸列出资料人脸：```bash theme={null} curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \ -H "x-api-key: YOUR_API_KEY" ```删除一张资料人脸：```bash theme={null} curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \ -H "x-api-key: YOUR_API_KEY" ```## 权限使用同一应用的 API 密钥。该密钥所属的应用必须有权管理目标用户的资料。## 失败情况- `400`：base64 无效、图片无效、未检测到人脸、图片超过 2 MB，或该用户已上传 5 张人脸。 - `401`：缺少凭证或凭证无效。 - `403`：API 密钥有效，但无权管理该用户资料。 - `404`：应用中不存在该 `didit_internal_id` 对应的用户。 - `429`：请求受到速率限制；请根据 `Retry-After` 进行退避。## 相关内容- [创建用户](https://docs.didit.me/zh/management-api/users/create.md) - [获取用户](https://docs.didit.me/zh/management-api/users/get.md) - [导入与导出用户](https://docs.didit.me/zh/entities/users/import-export.md) - [人脸与生物识别](https://docs.didit.me/zh/entities/users/faces-and-biometrics.md) - [上传人脸到黑名单](https://docs.didit.me/zh/management-api/lists/upload-face.md) ## OpenAPI ````yaml zh/openapi-25.json POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/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/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/: post: tags: - Users summary: 上传用户人脸 description: >- 将受信任的已导入人脸图像关联至现有的用户档案。在通过 `vendor_data` 创建或检索用户并读取其 `didit_internal_id` 后使用此功能。上传的人脸将存储在该用户档案中，并建立索引以用于重复项检测和人脸搜索。它不会被添加到人脸黑名单中。 operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: 拥有该应用的组织 UUID。 - name: application_id in: path required: true schema: type: string format: uuid description: 拥有该用户资料的应用 UUID。 - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- Didit 内部用户 UUID，由 `GET /v3/users/{vendor_data}/` 和 `POST /v3/users/create/` 作为 `didit_internal_id` 返回。 requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- 原始 base64 编码的 JPG 或 PNG 人脸图像。请勿包含 `data:image/...;base64,` 前缀。解码后的最大尺寸：2 MB。 comment: type: string description: 针对所上传人脸的可选备注，操作员可见。 default: '' examples: Imported face: summary: 关联从之前提供商导入的人脸 value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: 人脸已上传并附加到用户个人资料中。 content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: 已上传用户人脸记录的 UUID。 image_url: type: string format: uri nullable: true description: 已上传人脸图像的签名 URL。 comment: type: string nullable: true description: 上传人脸时提供的备注。 uploaded_by: type: string nullable: true description: 上传者的邮箱或操作者标识符（若可用）。 created_at: type: string format: date-time description: 上传时间戳。 examples: Uploaded: value: uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee image_url: https://signed-url.example/face.jpg comment: Imported from previous KYC provider uploaded_by: api created_at: '2026-05-18T12:00:00Z' '400': description: >- 无效的请求体或图像。常见原因：无效的 base64、无效的图像、未检测到人脸、图像超过 2 MB、缺少人脸特征向量，或用户已上传 5 张人脸。 content: application/json: examples: No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. Too many faces: value: detail: Maximum of 5 faces per user reached. Too large: value: image: Image exceeds maximum size of 2 MB. '401': description: API 密钥缺失或无效。 content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: 凭证有效，但无法为此应用写入用户资料。 content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: 该应用中不存在与该 `didit_internal_id` 对应的用户。 content: application/json: examples: Not found: value: detail: Not found. '429': description: 超出速率限制；请退避并重试。 content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID # and DIDIT_APPLICATION_ID. client = Didit() result = client.users.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQEA...", comment="Imported from previous KYC provider", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. const didit = new Didit(); const result = await didit.users.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQEA...", comment: "Imported from previous KYC provider", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\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.UsersUploadFaceParams; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. Didit client = new Didit(); var result = client.users().uploadFace("11111111-2222-3333-4444-555555555555", UsersUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQEA...") .comment("Imported from previous KYC provider") .build()); System.out.println(result); - lang: php label: PHP source: >- users->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQEA...', 'comment' => 'Imported from previous KYC provider', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID # and DIDIT_APPLICATION_ID. didit = Didit::Client.new result = didit.users.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQEA...", comment: "Imported from previous KYC provider" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. using var client = new DiditClient(); var result = await client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new UsersUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQEA...", Comment = "Imported from previous KYC provider", }); 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.