Classic/VPC環境で利用できます。
特化モデルエンジンを使用して名刺の入力情報(key-value)を認識し、抽出します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST | /name-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/name-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
"version": "V2",
"requestId": "1234",
"timestamp": 0,
"images": [
{
"format": "jpg",
"name": "namecard_test2",
"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/name-card' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"namecard_test\"}]}"' \
--form 'file={file}.jpg"'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
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 | - | 変換後画像ページインデックス |
nameCard |
Object | - | 名刺の詳細情報 |
nameCard.meta |
Object | - | メタ情報 |
nameCard.meta.estimatedLanguage |
String | - | OCR推定言語
|
nameCard.result |
Object | - | 名刺の OCR認識結果 |
result
resultの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
name |
Array | - | 氏名情報
|
nameFurigana |
Array | - | フリガナ情報
|
company |
Array | - | 会社情報
|
address |
Array | - | 住所情報
|
position |
Array | - | 役職連携
|
department |
Array | - | 部署情報
|
mobile |
Array | - | 携帯電話情報
|
tel |
Array | - | 電話情報
|
fax |
Array | - | FAX情報
|
email |
Array | - | メール情報
|
homepage |
Array | - | ホームページ情報
|
共通オブジェクト情報
共通オブジェクトの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果のテキスト |
keyText |
String | - | 認識結果のテキストのキー |
confidenceScore |
Float | - | 認識結果のテキストの信頼度
|
boundingPoly |
Object | - | Bounding Poly情報 |
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
boundingPolys
boundingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
maskingPolys
maskingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
vertices
boundingPolyVerticesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
x |
Float | - | X軸の座標 |
y |
Float | - | Y軸の座標 |
レスポンスステータスコード
CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。
レスポンス例
レスポンスのサンプルコードは次の通りです。
成功
呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235494383,
"images": [
{
"uid": "{uid}",
"name": "namecard_test",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
},
"nameCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"name": [
{
"text": "キム**",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 92.0,
"y": 103.0
},
{
"x": 218.0,
"y": 103.0
},
{
"x": 218.0,
"y": 141.0
},
{
"x": 92.0,
"y": 141.0
}
]
}
],
"maskingPolys": []
}
],
"company": [
{
"text": "** **代理店",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 90.0,
"y": 255.0
},
{
"x": 237.0,
"y": 255.0
},
{
"x": 237.0,
"y": 284.0
},
{
"x": 90.0,
"y": 284.0
}
]
}
],
"maskingPolys": []
}
],
"address": [
{
"text": "ソウル特別市***",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 91.0,
"y": 287.0
},
{
"x": 376.0,
"y": 287.0
},
{
"x": 376.0,
"y": 312.0
},
{
"x": 91.0,
"y": 312.0
}
]
}
],
"maskingPolys": []
}
],
"position": [
{
"text": "****",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 226.0,
"y": 114.0
},
{
"x": 300.0,
"y": 114.0
},
{
"x": 300.0,
"y": 138.0
},
{
"x": 226.0,
"y": 138.0
}
]
}
],
"maskingPolys": []
}
],
"mobile": [
{
"text": "010********",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 88.0,
"y": 145.0
},
{
"x": 300.0,
"y": 145.0
},
{
"x": 300.0,
"y": 175.0
},
{
"x": 88.0,
"y": 175.0
}
]
}
]
}
],
"tel": [
{
"text": "02-****-****",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 89.0,
"y": 311.0
},
{
"x": 264.0,
"y": 311.0
},
{
"x": 264.0,
"y": 333.0
},
{
"x": 89.0,
"y": 333.0
}
]
}
]
}
],
"fax": [
{
"text": "02-****-****",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 89.0,
"y": 334.0
},
{
"x": 264.0,
"y": 334.0
},
{
"x": 264.0,
"y": 358.0
},
{
"x": 89.0,
"y": 358.0
}
]
}
]
}
],
"email": [
{
"text": "****@****.net",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 137.0,
"y": 359.0
},
{
"x": 312.0,
"y": 359.0
},
{
"x": 312.0,
"y": 382.0
},
{
"x": 137.0,
"y": 382.0
}
]
}
],
"maskingPolys": []
}
]
}
}
}
]
}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235840459,
"images": [
{
"uid": "{uid}",
"name": "namecard_test2",
"inferResult": "ERROR",
"message": "Read page:0 error.",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}