## 使用例
身分証の表裏面を含む画像を 1 枚アップロードすると、AI アシスタントが自動的に認識して構造化された JSON を出力します：
```json
{
"document_type": "中華民國國民身分證",
"name": "陳筱玲",
"gender": "女",
"date_of_birth": "民國57年6月5日",
"military_service": null,
"place_of_birth": "臺北市",
"id_number": "A234567890",
"expiry_or_issue_date": "民國94年7月1日",
"address": "臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號"
}
```
{% hint style="warning" %}
認識の精度は画像の品質に左右されます。撮影時は十分な明るさを確保し、反射を避け、証明書を平らに置いて撮影することをおすすめします。表裏面を同時に撮影する場合は、左右または上下に並べることをおすすめします。
{% endhint %}
## JSON 出力項目の説明
| 項目 | 型 | 取得元 | 説明 |
| ---------------------- | ----------- | --- | --------- |
| `document_type` | string | 表面 | 証明書の種類 |
| `name` | string | 表面 | 名義人の氏名 |
| `gender` | string | 表面 | 性別（男／女） |
| `date_of_birth` | string | 表面 | 生年月日（民国年） |
| `military_service` | string/null | 裏面 | 兵役区分 |
| `place_of_birth` | string/null | 裏面 | 出生地 |
| `id_number` | string | 表面 | 身分証統一番号 |
| `expiry_or_issue_date` | string/null | 表面 | 発行日 |
| `address` | string/null | 裏面 | 完全な住所 |
## API 連携
このアシスタントは MaiAgent API を通じて業務システムに連携でき、証明書認識フローを自動化できます。
### 呼び出しフロー
```mermaid
sequenceDiagram
participant Client as 業務システム
participant API as MaiAgent API
participant Bot as OCR 認識アシスタント
Client->>API: POST /attachments-upload/ 証明書画像をアップロード
API-->>Client: 添付ファイル ID を返す
Client->>API: POST /chatbots/{id}/completions/ 添付ファイル ID を渡す
API->>Bot: 画像認識
Bot-->>API: JSON 構造化結果
API-->>Client: OCR JSON を返す
```
### Step 1：画像をアップロードして添付ファイル ID を取得
```bash
curl -X POST \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "file=@/path/to/id_card.jpeg" \
"https://api.maiagent.ai/api/v1/attachments-upload/"
```
返却結果のうち `id`、`type`、`file`、`filename` の各項目を控えておいてください。次のステップで使用します。
### Step 2：アシスタントを呼び出して認識を実行
```bash
curl -X POST \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": {
"content": "請辨識這張證件圖片",
"attachments": [{
"id": "{Step 1 回傳的 id}",
"type": "image",
"file": "{Step 1 回傳的 file URL}",
"filename": "id_card.jpeg"
}]
},
"isStreaming": false
}' \
"https://api.maiagent.ai/api/v1/chatbots/{助理ID}/completions/"
```
### Step 3：返却結果の解析
返却された `content` 項目が、JSON フォーマットの認識結果です：
**Python**
```python
import json
ocr_result = json.loads(response["content"])
print(ocr_result["name"]) # 陳筱玲
print(ocr_result["id_number"]) # A234567890
print(ocr_result["address"]) # 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號
```
**JavaScript**
```javascript
const ocrResult = JSON.parse(response.content);
console.log(ocrResult.name); // 陳筱玲
console.log(ocrResult.id_number); // A234567890
console.log(ocrResult.address); // 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號
```
{% hint style="info" %}
完全なサンプルコードは [Playma-Co-Ltd/maiagent-api-examples](https://github.com/Playma-Co-Ltd/maiagent-api-examples) を参照してください。
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/application/image-vision/id-card-recognition.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.