Classic/VPC環境で利用できます。
特化モデルエンジンを使用してパスポート(韓国内)の入力情報(key-value)を認識し、抽出します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST | /id-card |
リクエストヘッダ
CLOVA OCR APIで共通して使用されるヘッダの詳細は、CLOVA OCRのリクエストヘッダをご参照ください。
リクエストボディ
リクエストボディの説明は次の通りです。
Content-Type: application/jsonの場合
リクエストヘッダのContent-Typeがapplication/jsonの場合のリクエストボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
version |
String | - | バージョン情報
|
requestId |
String | Required | 任意の API呼び出しの UUID |
timestamp |
Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
images |
Array | Required | imagesの詳細情報 |
Content-Type: multipart/form-dataの場合
リクエストヘッダのContent-Typeがmultipart/form-dataの場合のリクエストボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
message |
Object | Required | リクエストデータ情報 |
message.version |
String | Required | バージョン情報
|
message.requestId |
String | Required | 任意の API呼び出しの UUID |
message.timestamp |
Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
message.images |
Array | Required | imagesの詳細情報 |
file |
File | Required | OCR認識画像ファイル |
images
imagesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
format |
String | Required | 画像の形式
|
name |
String | Required | 任意の画像名
|
data |
String | Required | Base64でエンコードされた画像データ
|
リクエスト例
リクエストのサンプルコードは次の通りです。
Content-Type: application/jsonの場合
リクエストヘッダのContent-Typeがapplication/jsonの場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
"version": "V2",
"requestId": "string",
"timestamp": 0,
"images": [
{
"format": "png",
"name": "passport_test",
"data":"{Base64でエンコードされた画像データ}"
}
]
}'
Content-Type: multipart/form-dataの場合
リクエストヘッダのContent-Typeがmultipart/form-dataの場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 0, \"images\": [{\"format\": \"png\", \"name\": \"passport_test\"}]}"' \
--form 'file=@"{file}"'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
version |
String | - | バージョン情報
|
requestId |
String | - | API呼び出し UUID |
timestamp |
Integer | - | APIの呼び出し時刻(Timestamp) |
images |
Array | - | imagesの詳細情報 |
images
imagesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
uid |
String | - | パスポート画像の UID
|
name |
String | - | パスポートの画像名
|
inferResult |
String | - | パスポートの画像認識結果
|
message |
String | - | 結果メッセージ |
validationResult |
Object | - | 有効性検査の結果情報 |
validationResult.result |
String | - | 有効性検査の結果コード
|
validationResult.message |
String | - | 有効性検査結果の詳細メッセージ
|
convertedImageInfo |
Object | - | 変換後の画像情報
|
convertedImageInfo.width |
Integer | - | 変換後画像の横長 |
convertedImageInfo.height |
Integer | - | 変換後画像の縦長 |
convertedImageInfo.pageIndex |
Integer | - | 変換後画像ページインデックス |
idCard |
Object | - | 身分証明書の詳細情報 |
idCard.meta |
Object | - | メタ情報 |
idCard.meta.estimatedLanguage |
String | - | OCR推定言語
|
idCard.result |
Object | - | 身分証明書の OCR認識結果 |
result
resultの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
isConfident |
Boolean | - | 各タイプの詳細情報を保有するかどうか
|
pp |
Object | - | パスポート情報 |
pp.type |
Array | - | パスポートタイプの詳細情報 |
pp.issueCountry |
Array | - | パスワード発行国の詳細情報 |
pp.num |
Array | - | パスポート番号の詳細情報 |
pp.surName |
Array | - | 名前(姓)の詳細情報 |
pp.givenName |
Array | - | 名前(名)の詳細情報 |
pp.nationality |
Array | - | 国籍の詳細情報 |
pp.birthDate |
Array | - | 生年月日の詳細情報 |
pp.name |
Array | - | 性別の詳細情報 |
pp.issueDate |
Array | - | 発行日の詳細情報 |
pp.expireDate |
Array | - | 有効期限の詳細情報 |
pp.authority |
Array | - | 発行機関の詳細情報 |
pp.fullNameKor |
Array | - | フルネームの詳細情報 |
pp.mrz1 |
Array | - | 機械判読ゾーン1の詳細情報 |
pp.mrz2 |
Array | - | 機械判読ゾーン2の詳細情報 |
rois |
Array | - | オブジェクト枠線の位置情報 |
idType |
String | - | 身分証明書タイプ
|
type
pp.typeの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果のタイプテキスト |
formatted |
Object | - | 認識結果のタイプテキスト情報 |
formatted.value |
String | - | 認識結果のタイプテキストの値 |
keyText |
String | - | 認識結果のタイプテキストのキー |
confidenceScore |
Float | - | 認識結果のタイプテキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
issueCountry
pp.issueCountryの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の発行国テキスト |
keyText |
String | - | 認識結果の発行国テキストのキー |
confidenceScore |
Float | - | 認識結果の発行国テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
num
pp.numの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の番号テキスト |
formatted |
Object | - | 認識結果の番号テキスト情報 |
formatted.value |
String | - | 認識結果の番号テキストの値 |
keyText |
String | - | 認識結果の番号テキストのキー |
confidenceScore |
Float | - | 認識結果の番号テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
name
pp.surName、pp.GivenNameの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の名前テキスト |
formatted |
Object | - | 認識結果の名前テキスト情報 |
formatted.value |
String | - | 認識結果の名前テキストの値 |
keyText |
String | - | 認識結果の名前テキストのキー |
confidenceScore |
Float | - | 認識結果の名前テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
nationality
pp.nationalityの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の国籍テキスト |
formatted |
Object | - | 認識結果の国籍テキスト情報 |
formatted.value |
String | - | 認識結果の国籍テキストの値 |
keyText |
String | - | 認識結果の国籍テキストのキー |
confidenceScore |
Float | - | 認識結果の国籍テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
日付オブジェクト情報
日付オブジェクトの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の日付テキスト |
formatted |
Object | - | 認識結果の日付テキスト情報 |
formatted.year |
String | - | 認識結果の日付の年度(yyyy) |
formatted.month |
String | - | 認識結果の日付の月(MM) |
formatted.day |
String | - | 認識結果の日付の日(dd) |
keyText |
String | - | 認識結果の発行テキストのキー |
confidenceScore |
Float | - | 認識結果の日付テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
condition
pp.conditionの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の条件テキスト |
keyText |
String | - | 認識結果の条件テキストのキー |
confidenceScore |
Float | - | 認識結果の条件テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
sex
pp.sexの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の性別テキスト |
formatted |
Object | - | 認識結果の性別テキスト情報 |
formatted.value |
String | - | 認識結果の性別テキストの値 |
keyText |
String | - | 認識結果の性別テキストのキー |
confidenceScore |
Float | - | 認識結果の性別テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
organDonation
pp.organDonationの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の臓器・組織提供テキスト |
keyText |
String | - | 認識結果の臓器・組織提供テキストのキー |
confidenceScore |
Float | - | 認識結果の臓器・組織提供テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
authority
pp.authorityの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の発行機関テキスト |
keyText |
String | - | 認識結果の発行機関テキストのキー |
confidenceScore |
Float | - | 認識結果の発行機関テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
fullNameKor
pp.fullNameKorの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果のフルネームテキスト |
formatted |
Object | - | 認識結果のフルネームテキスト情報 |
formatted.value |
String | - | 認識結果のフルネームテキストの値 |
keyText |
String | - | 認識結果のフルネームテキストのキー |
confidenceScore |
Float | - | 認識結果のフルネームテキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
mrz
mrzの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の MRZテキスト |
formatted |
Object | - | 認識結果の MRZテキスト情報 |
formatted.value |
String | - | 認識結果の MRZテキストの値 |
keyText |
String | - | 認識結果の MRZテキストのキー |
confidenceScore |
Float | - | 認識結果の MRZテキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
rois
roisの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
x |
Float | - | オブジェクト枠線の位置 X軸の座標 |
y |
Float | - | オブジェクト枠線の位置 Y軸の座標 |
boundingPolys
boundingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
maskingPolys
maskingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
boundingPolyVertices
boundingPolyVerticesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
x |
Float | - | X軸の座標 |
y |
Float | - | Y軸の座標 |
レスポンスステータスコード
CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。
レスポンス例
レスポンスのサンプルコードは次の通りです。
成功
呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725412120101,
"images": [
{
"uid": "{uid}",
"name": "passport_test",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
},
"idCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"isConfident": true,
"pp": {
"type": [
{
"text": "PM",
"formatted": {
"value": "PM"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 428.7616
},
{
"x": 206.57947,
"y": 428.7616
},
{
"x": 206.57947,
"y": 439.99554
},
{
"x": 187.23215,
"y": 439.99554
}
]
}
],
"maskingPolys": []
}
],
"issueCountry": [
{
"text": "KOR",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 234.04018,
"y": 428.7616
},
{
"x": 260.8768,
"y": 428.7616
},
{
"x": 260.8768,
"y": 439.99554
},
{
"x": 234.04018,
"y": 439.99554
}
]
}
]
}
],
"num": [
{
"text": "M123A****",
"formatted": {
"value": "M123A****"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 327.65625,
"y": 428.7616
},
{
"x": 395.68393,
"y": 428.7616
},
{
"x": 395.68393,
"y": 439.99554
},
{
"x": 327.65625,
"y": 439.99554
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 326.53287,
"y": 427.6382
},
{
"x": 396.8073,
"y": 427.6382
},
{
"x": 396.8073,
"y": 441.11893
},
{
"x": 326.53287,
"y": 441.11893
}
]
}
]
}
],
"surName": [
{
"text": "HONG",
"formatted": {
"value": "HONG"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 454.97412
},
{
"x": 224.05446,
"y": 454.97412
},
{
"x": 224.05446,
"y": 466.83215
},
{
"x": 187.23215,
"y": 466.83215
}
]
}
],
"maskingPolys": []
}
],
"givenName": [
{
"text": "GIL****",
"formatted": {
"value": "GIL****"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 481.8107
},
{
"x": 241.52946,
"y": 481.8107
},
{
"x": 241.52946,
"y": 493.66876
},
{
"x": 187.23215,
"y": 493.66876
}
]
}
],
"maskingPolys": []
}
],
"nationality": [
{
"text": "REPUBLIC OF KOREA",
"formatted": {
"value": "REPUBLIC OF KOREA"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.74973,
"y": 569.2035
},
{
"x": 244.59932,
"y": 568.4555
},
{
"x": 244.73523,
"y": 578.78436
},
{
"x": 187.88564,
"y": 579.53235
}
]
}
],
"maskingPolys": []
}
],
"birthDate": [
{
"text": "01 2月/FEB 1987",
"formatted": {
"year": "1987",
"month": "02",
"day": "01"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 186.60803,
"y": 534.8598
},
{
"x": 204.70714,
"y": 534.8598
},
{
"x": 204.70714,
"y": 547.96606
},
{
"x": 186.60803,
"y": 547.96606
}
]
}
],
"maskingPolys": []
}
],
"sex": [
{
"text": "F んだ",
"formatted": {
"value": "F"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 558.57587
},
{
"x": 204.08304,
"y": 558.57587
},
{
"x": 204.08304,
"y": 565.4411
},
{
"x": 187.23215,
"y": 565.4411
}
]
}
],
"maskingPolys": []
}
],
"issueDate": [
{
"text": "15 8月/AUG 2020",
"formatted": {
"year": "2020",
"month": "08",
"day": "15"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 187.23215,
"y": 594.7741
},
{
"x": 202.83482,
"y": 594.7741
},
{
"x": 202.83482,
"y": 605.3839
},
{
"x": 187.23215,
"y": 605.3839
}
]
}
],
"maskingPolys": []
}
],
"expireDate": [
{
"text": "15 8月/AUG 2030",
"formatted": {
"year": "2030",
"month": "08",
"day": "15"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 328.28036,
"y": 594.15
},
{
"x": 343.25894,
"y": 594.15
},
{
"x": 343.25894,
"y": 605.3839
},
{
"x": 328.28036,
"y": 605.3839
}
]
}
],
"maskingPolys": []
}
],
"authority": [
{
"text": "MINISTRY OF FOREIGN AFFAIRS",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 328.28036,
"y": 569.8098
},
{
"x": 373.84018,
"y": 569.8098
},
{
"x": 373.84018,
"y": 577.9232
},
{
"x": 328.28036,
"y": 577.9232
}
]
}
]
}
],
"fullNameKor": [
{
"text": "ホン**",
"formatted": {
"value": "ホン**"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 186.60803,
"y": 506.775
},
{
"x": 223.43036,
"y": 506.775
},
{
"x": 223.43036,
"y": 522.3777
},
{
"x": 186.60803,
"y": 522.3777
}
]
}
],
"maskingPolys": []
}
],
"mrz1": [
{
"text": "PMKORHONG<<GIL****<<<<<<<<<<<<<<<<<<<<<<<<<<<<",
"formatted": {
"value": "PMKORHONG<<GIL****<<<<<<<<<<<<<<<<<<<<<<<<<<"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 32.45357,
"y": 638.4616
},
{
"x": 484.93124,
"y": 638.4616
},
{
"x": 484.93124,
"y": 650.9437
},
{
"x": 32.45357,
"y": 650.9437
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 31.20536,
"y": 637.2134
},
{
"x": 486.17944,
"y": 637.2134
},
{
"x": 486.17944,
"y": 652.19196
},
{
"x": 31.20536,
"y": 652.19196
}
]
}
]
}
],
"mrz2": [
{
"text": "M123A45670K0R*****0000000000000000",
"formatted": {
"value": "M123A45670K0R*****00000000000000"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 31.829464,
"y": 663.42584
},
{
"x": 486.17938,
"y": 663.42584
},
{
"x": 486.17938,
"y": 677.7803
},
{
"x": 31.829464,
"y": 677.7803
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 30.39402,
"y": 661.9904
},
{
"x": 487.61484,
"y": 661.9904
},
{
"x": 487.61484,
"y": 679.2157
},
{
"x": 30.39402,
"y": 679.2157
}
]
}
]
}
]
},
"rois": [
{
"vertices": [
{
"x": 10.000834,
"y": 364.93756
},
{
"x": 500.2946,
"y": 364.6102
},
{
"x": 501.1391,
"y": 692.69543
},
{
"x": 6.990344,
"y": 694.3484
}
]
}
],
"idtype": "Passport"
}
}
}
]
}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235840459,
"images": [
{
"uid": "{uid}",
"name": "passport_test",
"inferResult": "ERROR",
"message": "Read page:0 error.",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}