curl
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"}'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)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);ctx := context.Background()
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
client := didit.NewClient()
result, err := client.Users.UploadFace(ctx, "11111111-2222-3333-4444-555555555555", didit.UsersUploadFaceParams{
Image: "/9j/4AAQSkZJRgABAQEA...",
Comment: didit.String("Imported from previous KYC provider"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)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);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
$didit = new DiditClient();
$result = $didit->users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());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_husing 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));{
"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"
}用户
上传用户人脸 API:供应商用户资料
在 Didit 中为已有用户资料上传 base64 人脸图像。该用户需已通过 vendor_data 创建或导入,才能使用本接口上传。
POST
/
v3
/
organization
/
{organization_id}
/
application
/
{application_id}
/
vendor-users
/
by-id
/
{didit_internal_id}
/
faces
/
upload
/
curl
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"}'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)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);ctx := context.Background()
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
client := didit.NewClient()
result, err := client.Users.UploadFace(ctx, "11111111-2222-3333-4444-555555555555", didit.UsersUploadFaceParams{
Image: "/9j/4AAQSkZJRgABAQEA...",
Comment: didit.String("Imported from previous KYC provider"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)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);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
$didit = new DiditClient();
$result = $didit->users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());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_husing 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));{
"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"
}概述
当你从其他服务商导入用户,并且已经为每个人准备了可信的人脸图片时,请使用此 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 图片。后端会在保存前验证图片是否能够解码、图片大小以及是否检测到人脸。示例
# 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": "<base64-encoded-jpg-or-png>",
"comment": "Imported from previous KYC provider"
}'
请求体
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
image | string | 是 | 原始 base64 编码的 JPG 或 PNG 图片。请勿包含 data:image/...;base64,。解码后的最大大小:2 MB。 |
comment | string | 否 | 显示在用户资料上、供操作员查看的备注。 |
响应
{
"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,并且能够解码为图片。
- 图片中必须包含可检测的人脸。如有可能,请使用正面、光线充足的人脸裁剪图。
- 上传的人脸会被索引,用于之后的重复检测和人脸搜索。
- 上传的人脸不会自动加入黑名单。
列出或删除已上传的人脸
列出资料人脸: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"
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进行退避。
相关内容
授权
您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。
路径参数
拥有该应用的组织 UUID。
拥有该用户资料的应用 UUID。
Didit 内部用户 UUID,由 GET /v3/users/{vendor_data}/ 和 POST /v3/users/create/ 作为 didit_internal_id 返回。
请求体
application/json
最后修改于 2026年11月7日