Template OCR

Prev Next

Classic/VPC環境で利用できます。

NAVERクラウドプラットフォームコンソールで、画像の判読領域を直接指定したテンプレート(Template)に基づいてテキストを認識・抽出します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド URI
POST /infer

リクエストヘッダ

CLOVA OCR APIで共通して使用されるヘッダの詳細は、CLOVA OCRのリクエストヘッダをご参照ください。

リクエストボディ

リクエストボディの説明は次の通りです。

Content-Type: application/jsonの場合

リクエストヘッダのContent-Typeapplication/jsonの場合のリクエストボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
version String Required バージョン情報
  • V1 | V2(推奨)
    • V1: V1エンジンを呼び出す
    • V2: V2エンジンを呼び出す
requestId String Required 任意の API呼び出し UUID
timestamp Integer Required 任意の API呼び出し時刻(Timestamp)
lang String Optional OCR認識リクエストの言語情報
  • ko | ja | zh-TW
    • ko: 韓国語
    • ja: 日本語
    • zh-TW: 中国語(繁体字)
  • 入力しないとドメインの言語設定値に自動設定
  • コンマ「,」を利用すると複数の言語の同時呼び出しができる
    • <例> "ko, ja, zh-TW"
images Array Required imagesの詳細情報
  • JSON Arrayで作成
  • 呼び出し1件につき1つの画像 Arrayを作成可能
  • 画像サイズ: 最大50MB

Content-Type: multipart/form-dataの場合

リクエストヘッダContent-Typemultipart/form-dataの場合のリクエストボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
message Object Required リクエストデータ情報
message.version String Required バージョン情報
  • V1 | V2(推奨)
    • V1: V1エンジンを呼び出す
    • V2: V2エンジンを呼び出す
message.requestId String Required 任意の API呼び出し UUID
message.timestamp Integer Required 任意の API呼び出し時刻(Timestamp)
message.lang String Optional OCR認識リクエストの言語情報
  • ko | ja | zh-TW
    • ko: 韓国語
    • ja: 日本語
    • zh-TW: 中国語(繁体字)
  • 入力しないとドメインの言語設定値に自動設定
  • コンマ「,」を利用すると複数の言語の同時呼び出しができる
    • <例> "ko, ja, zh-TW"
message.images Array Required imagesの詳細情報
  • JSON Arrayで作成
  • 呼び出し1件につき1つの画像 Arrayを作成可能
  • 画像サイズ: 最大50MB
file File Required OCR認識画像ファイル

images

imagesの説明は次の通りです。

フィールド タイプ 必須の有無 説明
format String Required 画像形式
  • jpg | jpeg | png | pdf | tif | tiff
    • pdf: 最大5ページまで認識可能
name String Required 画像名
  • 画像の識別とレスポンス結果の確認に使用
url String Conditional 画像の URLアドレス
  • 画像が取得可能な公開された URL
  • Content-Type: application/jsonの場合に入力可能
  • images.urlまたはimages.dataのうちどちらかは必ず入力
    • 両方入力するとimages.dataが優先
data String Conditional Base64でエンコードされた画像データ
  • Content-Type: application/jsonの場合に入力可能
  • images.urlまたはimages.dataのうちどちらかは必ず入力
    • 両方入力するとimages.dataが優先
templateIds Integer Optional テンプレート ID
  • 入力しないとデプロイされたすべてのサービステンプレートに自動分類

リクエスト例

リクエストのサンプルコードは次の通りです。

Content-Type: application/jsonの場合

リクエストヘッダContent-Typeapplication/jsonの場合のリクエストのサンプルコードは次の通りです。

curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33661/f5d739754b0ed5bdaa51365b7d**********a5bbdd069e0db430d5f5adb490b/infer' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
  "version": "V2",
  "requestId": "string",
  "timestamp": 0,
  "lang":"ko",
  "images": [
    {
      "format": "pdf",
      "name": "test 1",
      "url": "{url}",
      "templateIds":[31677]
    }
}'

Content-Type: multipart/form-dataの場合

リクエストヘッダContent-Typemultipart/form-dataの場合のリクエストのサンプルコードは次の通りです。

curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33661/f5d739754b0ed5bdaa51365b7d**********bbdd069e0db430d5f5adb490b/infer' \
--header 'Content-Type: multipart/form-data' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--form '{file}.jpg"' \
--form 'message="{\"version\": \"V1\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"hello\"}]}"'

レスポンス

レスポンス形式を説明します。

参考
  • V1バージョンでリクエストするとレスポンス結果のboundingに座標情報が表示されます。
  • V1バージョンでリクエストするとレスポンス結果にconvertedImageInfovalueTypetypesubFields情報が表示されません。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
version String - バージョン情報
  • V1 | V2
    • V1: V1エンジンを呼び出す
    • V2: V2エンジンを呼び出す
requestId String - API呼び出し UUID
timestamp Integer - API呼び出し時刻(Timestamp)
images Array - imagesの詳細情報

images

imagesの説明は次の通りです。

フィールド タイプ 必須の有無 説明
uid String - 画像の UID
  • API有効性検査とリクエストのトレース時に使用
name String - 画像名
  • 画像の識別とレスポンス結果の確認に使用
inferResult String - 画像推論の結果
  • SUCCESS | FAILURE | ERROR
    • SUCCESS: 認識成功
    • FAILURE: 認識失敗
    • ERROR: 認識処理例外
message String - 結果メッセージ
matchedTemplate Object - テンプレート情報
  • 認識できなかったか、一致するテンプレートが見つからない場合、このフィールドは表示されない
matchedTemplate.id Integer - テンプレート ID
matchedTemplate.name String - テンプレート名
validationResult Object - 有効性検査の結果情報
validationResult.result String - 有効性検査の結果コード
  • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
    • NO_REQUESTED: 検証をリクエストしていない(有効性検査失敗)
    • UNCHECKED: 検証の有無を確認できない
    • ERROR: 検証中にエラー発生(有効性検査失敗)
    • VALID: 検証結果は有効(有効性検査成功)
    • INVALID: 検証合格失敗
validationResult.message String - 有効性検査結果の詳細メッセージ
  • 必ずしも返される値ではない
convertedImageInfo Object - 変換後の画像情報
  • formatpdfまたはtiffの場合
  • 座標は呼び出し画像ファイルを基準に設定
convertedImageInfo.width Integer - 変換後画像の横長
convertedImageInfo.height Integer - 変換後画像の縦長
convertedImageInfo.pageIndex Integer - 変換後画像ページインデックス
convertedImageInfo.longImage Boolean - 変換後画像は長さが Longかどうか
  • true | false
    • true: 長い(Long)画像
    • false: 長い(Long)画像ではない
combineResult Object - 画像認識結果の都合情報
combineResult.name String - 画像結合フィールド名
combineResult.text String - 各画像フィールドごとの出力値と固定テキスト
fields Array - Fieldsの詳細情報
title Object - 画像のタイトルの詳細情報
title.name String - テンプレートの代表サンプルフィールド名
  • 画像の識別とレスポンス結果の確認に使用
title.boundingPoly Object - Bounding Poly情報
  • versionV2の場合にのみ提供
title.boundingPoly.vertices Array - Bounding Poly Verticesの詳細情報
title.inferText String - 認識結果テキスト
  • typeCHECKBOXの場合、設定で指定したレスポンスに置換
title.inferConfidence Float - 認識結果テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
title.subFields Array - subFieldsの詳細情報

fields

fieldsの説明は次の通りです。

フィールド タイプ 必須の有無 説明
name String - テンプレートのフィールド名
  • APIの呼び出し時にのみ動作
  • 画像の識別とレスポンス結果の確認に使用
valueType String - 入力値のタイプ
  • ALL | NUMERIC
    • ALL: テキストと数字
    • NUMERIC: 数字
boundingPoly Object - Bounding Poly情報
  • versionV2の場合にのみ提供
boundingPoly.vertices Array - Bounding Poly Verticesの詳細情報
inferText String - 認識結果テキスト
  • typeCHECKBOXの場合、設定で指定したレスポンスに置換
inferConfidence Float - 認識結果テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
type String - 認識結果画像タイプ
  • NORMAL | MULTI_BOX | CHECKBOX
    • NORMAL: 一般
    • MULTI_BOX: マルチボックス
    • CHECKBOX: チェックボックス
subFields Array - subFieldsの詳細情報
checked Boolean - チェックボックスは選択されているかどうか
  • true | false
    • true: 選択されている
    • false: 選択されていない

subFields

fields.subFieldsの説明は次の通りです。

フィールド タイプ 必須の有無 説明
boundingPoly Object - Bounding Poly情報
  • versionV2の場合にのみ提供
boundingPoly.vertices Array - Bounding Poly Verticesの詳細情報
inferText String - 認識結果テキスト
  • typeCHECKBOXの場合、設定で指定したレスポンスに置換
inferConfidence Float - 認識結果テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
lineBreak Boolean - 認識結果テキストの最終行であるかどうかを表示
  • true | false
    • true: 最後のテキスト
    • false: 最後のテキストではない

vertices

boundingPoly.verticesの説明は次の通りです。

フィールド タイプ 必須の有無 説明
x Float - Bounding Poly X軸の座標
y Float - Bounding Poly Y軸の座標

bounding

boundingの説明は次の通りです。

フィールド タイプ 必須の有無 説明
top Float - Bounding y軸の座標
left Float - Bounding x軸の座標
width Float - Bounding Poly横
height Float - Bounding Poly縦

レスポンスステータスコード

CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1724831491715,
    "images": [
        {
            "uid": "{uid}",
            "name": "test 1",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "matchedTemplate": {
                "id": 31677,
                "name": "事業者登録証"
            },
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "convertedImageInfo": {
                "width": 1190,
                "height": 1682,
                "pageIndex": 0,
                "longImage": false
            },
            "fields": [
                {
                    "name": "登録番号",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 551.0,
                                "y": 310.0
                            },
                            {
                                "x": 775.0,
                                "y": 310.0
                            },
                            {
                                "x": 775.0,
                                "y": 350.0
                            },
                            {
                                "x": 551.0,
                                "y": 350.0
                            }
                        ]
                    },
                    "inferText": "***-**-*****",
                    "inferConfidence": 1.0,
                    "type": "NORMAL",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 551.0,
                                        "y": 310.0
                                    },
                                    {
                                        "x": 775.0,
                                        "y": 310.0
                                    },
                                    {
                                        "x": 775.0,
                                        "y": 350.0
                                    },
                                    {
                                        "x": 551.0,
                                        "y": 350.0
                                    }
                                ]
                            },
                            "inferText": "***-**-*****",
                            "inferConfidence": 1.0,
                            "lineBreak": true
                        }
                    ]
                },
                {
                    "name": "法人名_団体名",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 317.0,
                                "y": 369.0
                            },
                            {
                                "x": 511.0,
                                "y": 369.0
                            },
                            {
                                "x": 511.0,
                                "y": 402.0
                            },
                            {
                                "x": 317.0,
                                "y": 402.0
                            }
                        ]
                    },
                    "inferText": "***** (株)",
                    "inferConfidence": 0.9999,
                    "type": "NORMAL",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 317.0,
                                        "y": 369.0
                                    },
                                    {
                                        "x": 451.0,
                                        "y": 369.0
                                    },
                                    {
                                        "x": 451.0,
                                        "y": 402.0
                                    },
                                    {
                                        "x": 317.0,
                                        "y": 402.0
                                    }
                                ]
                            },
                            "inferText": "*****",
                            "inferConfidence": 0.9998,
                            "lineBreak": false
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 459.0,
                                        "y": 371.0
                                    },
                                    {
                                        "x": 511.0,
                                        "y": 371.0
                                    },
                                    {
                                        "x": 511.0,
                                        "y": 399.0
                                    },
                                    {
                                        "x": 459.0,
                                        "y": 399.0
                                    }
                                ]
                            },
                            "inferText": "(株)",
                            "inferConfidence": 1.0,
                            "lineBreak": true
                        }
                    ]
                },
                {
                    "name": "開業年月日",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 316.0,
                                "y": 493.0
                            },
                            {
                                "x": 564.0,
                                "y": 495.0
                            },
                            {
                                "x": 564.0,
                                "y": 526.0
                            },
                            {
                                "x": 314.0,
                                "y": 526.0
                            }
                        ]
                    },
                    "inferText": "1975年06月01日",
                    "inferConfidence": 0.99796,
                    "type": "NORMAL",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 316.0,
                                        "y": 493.0
                                    },
                                    {
                                        "x": 374.0,
                                        "y": 496.0
                                    },
                                    {
                                        "x": 373.0,
                                        "y": 525.0
                                    },
                                    {
                                        "x": 314.0,
                                        "y": 522.0
                                    }
                                ]
                            },
                            "inferText": "1975",
                            "inferConfidence": 1.0,
                            "lineBreak": false
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 380.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 410.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 410.0,
                                        "y": 526.0
                                    },
                                    {
                                        "x": 380.0,
                                        "y": 526.0
                                    }
                                ]
                            },
                            "inferText": "年",
                            "inferConfidence": 0.9999,
                            "lineBreak": false
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 417.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 451.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 451.0,
                                        "y": 523.0
                                    },
                                    {
                                        "x": 417.0,
                                        "y": 523.0
                                    }
                                ]
                            },
                            "inferText": "06",
                            "inferConfidence": 1.0,
                            "lineBreak": false
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 457.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 490.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 490.0,
                                        "y": 524.0
                                    },
                                    {
                                        "x": 457.0,
                                        "y": 524.0
                                    }
                                ]
                            },
                            "inferText": "月",
                            "inferConfidence": 0.9997,
                            "lineBreak": false
                        },
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 494.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 564.0,
                                        "y": 495.0
                                    },
                                    {
                                        "x": 564.0,
                                        "y": 523.0
                                    },
                                    {
                                        "x": 494.0,
                                        "y": 523.0
                                    }
                                ]
                            },
                            "inferText": "01日",
                            "inferConfidence": 0.9902,
                            "lineBreak": false
                        }
                    ]
                },
                {
                    "name": "事業場の所在地",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 315.0,
                                "y": 534.0
                            },
                            {
                                "x": 852.0,
                                "y": 534.0
                            },
                            {
                                "x": 852.0,
                                "y": 568.0
                            },
                            {
                                "x": 315.0,
                                "y": 568.0
                            }
                        ]
                    },
                    "inferText": "京畿道 ******",
                    "inferConfidence": 0.99223995,
                    "type": "NORMAL",
                    "subFields": [
                        {
                            "boundingPoly": {
                                "vertices": [
                                    {
                                        "x": 315.0,
                                        "y": 535.0
                                    },
                                    {
                                        "x": 397.0,
                                        "y": 535.0
                                    },
                                    {
                                        "x": 397.0,
                                        "y": 568.0
                                    },
                                    {
                                        "x": 315.0,
                                        "y": 568.0
                                    }
                                ]
                            },
                            "inferText": "京畿道",
                            "inferConfidence": 1.0,
                            "lineBreak": false
                        }
                    ]
                },
                {
                    "name": "代表者",
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 300.66458,
                                "y": 404.66934
                            },
                            {
                                "x": 910.0876,
                                "y": 400.79553
                            },
                            {
                                "x": 909.6188,
                                "y": 478.17303
                            },
                            {
                                "x": 300.49875,
                                "y": 481.97482
                            }
                        ]
                    },
                    "inferText": "",
                    "inferConfidence": 0.0,
                    "type": "NORMAL"
                }
            ],
            "title": {
                "name": "事業者登録証",
                "boundingPoly": {
                    "vertices": [
                        {
                            "x": 330.0,
                            "y": 188.0
                        },
                        {
                            "x": 795.0,
                            "y": 186.0
                        },
                        {
                            "x": 795.0,
                            "y": 252.0
                        },
                        {
                            "x": 330.0,
                            "y": 253.0
                        }
                    ]
                },
                "inferText": "事業者登録証",
                "inferConfidence": 0.9998,
                "subFields": [
                    {
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 330.0,
                                    "y": 188.0
                                },
                                {
                                    "x": 795.0,
                                    "y": 186.0
                                },
                                {
                                    "x": 795.0,
                                    "y": 252.0
                                },
                                {
                                    "x": 330.0,
                                    "y": 253.0
                                }
                            ]
                        },
                        "inferText": "事業者登録証",
                        "inferConfidence": 0.9998,
                        "lineBreak": true
                    }
                ]
            }
        },
    ]
}

失敗

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "V1",
    "requestId": "1234",
    "timestamp": 1724833931723,
    "images": [
        {
            "uid": "{uid}",
            "name": "hello",
            "inferResult": "FAILURE",
            "message": "NOT_FOUND: not found matched template",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}