> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 身分証人像写真検証 API 接続説明

> Identity Authentication 集成指南 - XHuoAPI

本文では、身分証人像写真検証 API 接続説明を紹介します。これは、身分証の人像面写真を入力し、身分証写真上の情報を認識し、名前、身分証番号、身分証人像写真を権威あるデータベースの証明書写真と照合し、同一人物であるかどうかを確認することで、身分証情報の真実性を検証します。

## 申請プロセス

API を使用するには、まず [身分証人像写真検証 API](https://api.xhuoapi.ai/documents/7a3f14f7-f1eb-41c2-816c-9f18caca6883) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

![](https://cdn.xhuoapi.ai/q6ytrc.png)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料の利用枠が付与され、この API を無料で使用できます。

## 基本使用

まず、基本的な使用方法を理解します。身分証画像のリンクを入力するだけで、処理後の検証結果を得ることができます。最初に `image_url` フィールドを簡単に渡す必要があります。次に、画面上に対応する内容を記入できます。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/zjxg3k.png" width="500" className="m-auto" />
</p>

ここでは、リクエストヘッダーを設定しています。含まれるのは：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまり JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

さらに、リクエストボディを設定しています。含まれるのは：

* `image_url`：処理する身分証画像のリンク。
* `config`：オプションの設定項目、ブール値フィールドで、デフォルトはすべて false です。`copy_warn`、`border_check_warn`、`reshoot_warn`、`detect_ps_warn`、`temp_id_warn`、`quality`（閾値 0-100）をサポートします。

選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/4yh23p.png" width="500" className="m-auto" />
</p>

「Try」ボタンをクリックするとテストができます。上の図のように、以下の結果を得ました：

```json theme={null}
{
  "sim": 99.76,
  "result": "Success",
  "description": "成功",
  "name": "身分証姓名",
  "sex": "身分証性別",
  "nation": "身分証民族",
  "birth": "身分証誕生日",
  "address": "身分証家庭住所",
  "id_num": "身分証番号",
  "portrait": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBA.....DEhE2lbPMcOtG3f/DLT/yX8if7Kxn/AD7h85wdttPifRf1e6//2Q==",
  "warnings": "",
  "quality": 0,
  "encryption": null
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `sim`、類似度、値の範囲は \[0.00, 100.00] です。類似度が70以上であれば同一人物と判断できます。具体的なシーンに応じて閾値を調整できます（閾値70の誤通過率は千分の一、閾値80の誤通過率は万分の一）。
* `result`、業務エラーコード、成功の場合は Success を返し、エラーの場合は下記のエラーコードリストの FailedOperation 部分を参照してください。
* `description`、ここでは名前と身分証番号の検証結果です。
* `name`、身分証に含まれる名前情報。身分証画像がアップロードされていない場合は空です。
* `sex`、身分証に含まれる性別情報。身分証画像がアップロードされていない場合は空です。
* `nation`、身分証に含まれる民族情報。身分証画像がアップロードされていない場合は空です。
* `birth`、身分証に含まれる誕生日情報。身分証画像がアップロードされていない場合は空です。
* `address`、身分証に含まれる家庭住所情報。身分証画像がアップロードされていない場合は空です。
* `id_num`、身分証に含まれる身分証番号情報。身分証画像がアップロードされていない場合は空です。
* `portrait`、身分証の顔写真の base64 コード。切り抜きに失敗した場合は、全体の身分証で照合し、空を返します。
* `warnings`、警告情報。Config で警告情報が設定されている場合、人像照合が停止し、Result がエラー（FailedOperation.OcrWarningOccurred）を返し、この警告情報が表示されます。
* `quality`、画像の品質スコア。リクエスト Config で画像のぼやけ警告が設定されている場合、このパラメータは意味を持ちます。値の範囲は（0～100）で、現在のデフォルト閾値は50点で、50点未満はぼやけ警告を引き起こします。
* `encryption`、機密データの暗号情報。

身分証情報が非常に高い真実性を持っていることがわかります。

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/identity/idcard/check-1e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'
```

Python の接続コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/identity/idcard/check-1e"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": {image_url}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 token_mismatched`：不正なリクエスト、パラメータが欠落または無効である可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが欠落または無効である可能性があります。
* `401 invalid_token`：未承認、無効または欠落した承認トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、身分証人像写真検証 API を使用して身分証人像面写真を入力し、身分証写真上の情報を認識し、名前、身分証番号、身分証人像写真を権威あるデータベースの証明書写真と照合し、同一人物であるかどうかを確認することで、身分証情報の真実性を検証する方法を理解しました。この文書が、API の接続と使用をより良くする手助けとなることを願っています。何か問題があれば、いつでも技術サポートチームにお問い合わせください。