> ## 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：ベンダーユーザープロファイル
> vendor_dataでユーザーを作成またはインポートした後、既存のDiditユーザープロファイルにbase64形式の顔画像をアップロードします。
ユーザーの顔画像アップロード用プロンプト
プロンプトをクリップボードにコピー
\
\`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.`
\
貼り付け先
## 概要他のプロバイダーからユーザーをインポートする際に、各人物について信頼できる顔画像をすでに保有している場合は、このエンドポイントを使用します。ユーザーは引き続き`vendor_data`をキーとして管理されますが、このプロフィール添付用エンドポイントでは対象ユーザーを一意に特定できるよう`didit_internal_id`を使用します。> [!NOTE]
>
> これは[リストへの顔画像アップロード](https://docs.didit.me/ja/management-api/lists/upload-face.md)とは異なります。プロフィールへのアップロードは、証拠、重複検知、顔検索のために顔画像をユーザーに添付するものです。リストへのアップロードは、顔タイプのブロックリストに顔画像を追加し、今後のマッチングセッションを却下できるようにするものです。## エンドポイント**`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/ja/management-api/users/create)を、既存のプロフィールの場合は[`GET /v3/users/{vendor_data}/`](https://docs.didit.me/ja/management-api/users/get)を呼び出します。**2. didit\_internal\_idを保存する**ユーザーのレスポンスには`didit_internal_id`が含まれます。データベースでは引き続き`vendor_data`を使用し、`didit_internal_id`はプロフィール添付用エンドポイントでのみ使用してください。**3. 顔画像をアップロードする**`image`フィールドにraw 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,`は含めないでください。デコード後の最大サイズ:2MB。 |
| `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"
}
```## バリデーションと制限- 手動でアップロードできる顔画像は、ユーザー1人あたり最大5件です。
- デコード後の画像サイズは最大2MBです。
- 画像は有効な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"
```プロフィールの顔画像を1件削除する:```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が無効、画像が無効、検出可能な顔がない、画像が2MBを超えている、またはユーザーにすでに5件の顔画像がアップロードされている。
- `401`:認証情報がない、または無効。
- `403`:APIキーは有効だが、このユーザーのプロフィールを管理する権限がない。
- `404`:アプリケーション内に、その`didit_internal_id`のユーザーが存在しない。
- `429`:レート制限中。`Retry-After`に従って間隔を空けてください。## 関連項目- [ユーザーの作成](https://docs.didit.me/ja/management-api/users/create.md)
- [ユーザーの取得](https://docs.didit.me/ja/management-api/users/get.md)
- [ユーザーのインポートとエクスポート](https://docs.didit.me/ja/entities/users/import-export.md)
- [顔と生体情報](https://docs.didit.me/ja/entities/users/faces-and-biometrics.md)
- [ブロックリストに顔画像をアップロード](https://docs.didit.me/ja/management-api/lists/upload-face.md)
## OpenAPI
````yaml ja/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: >-
信頼できるインポート済みの顔画像を既存のUserプロファイルに添付します。`vendor_data`でUserを作成または取得し、その`didit_internal_id`を読み取った後に使用してください。アップロードされた顔はUserプロファイルに保存され、重複検出と顔検索のためにインデックス化されます。顔のブロックリストには追加されません。
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,`プレフィックスは含めないでください。デコード後の最大サイズは2MBです。
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、無効な画像、検出可能な顔がない、画像が2MBを超えている、エンベディングが欠落している、またはユーザーにすでに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のDevelopers -> API
keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください:
https://docs.didit.me/console/api-keys
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.