MENU
      Login
          Login
          目次 x
          Template OCR
            目次

            Template OCR

              記事の要約

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

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

              リクエスト

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

              メソッドURI
              POST/infer

              リクエストヘッダ

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

              リクエストボディ

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

              Content-Type: application/jsonの場合

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

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

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

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

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

              images

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

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

              リクエスト例

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

              Content-Type: application/jsonの場合

              リクエストヘッダContent-Typeがapplication/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]
    }
}'
              Shell

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

              リクエストヘッダContent-Typeがmultipart/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\"}]}"'
              Shell

              レスポンス

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

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

              レスポンスボディ

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

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

              images

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

              フィールドタイプ必須の有無説明
              uidString-画像の UID
              • API有効性検査とリクエストのトレース時に使用
              nameString-画像名
              • 画像の識別とレスポンス結果の確認に使用
              inferResultString-画像推論の結果
              • SUCCESS | FAILURE | ERROR
                • SUCCESS: 認識成功
                • FAILURE: 認識失敗
                • ERROR: 認識処理例外
              messageString-結果メッセージ
              matchedTemplateObject-テンプレート情報
              • 認識できなかったか、一致するテンプレートが見つからない場合、このフィールドは表示されない
              matchedTemplate.idInteger-テンプレート ID
              matchedTemplate.nameString-テンプレート名
              validationResultObject-有効性検査の結果情報
              validationResult.resultString-有効性検査の結果コード
              • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
                • NO_REQUESTED: 検証をリクエストしていない(有効性検査失敗)
                • UNCHECKED: 検証の有無を確認できない
                • ERROR: 検証中にエラー発生(有効性検査失敗)
                • VALID: 検証結果は有効(有効性検査成功)
                • INVALID: 検証合格失敗
              validationResult.messageString-有効性検査結果の詳細メッセージ
              • 必ずしも返される値ではない
              convertedImageInfoObject-変換後の画像情報
              • formatがpdfまたはtiffの場合
              • 座標は呼び出し画像ファイルを基準に設定
              convertedImageInfo.widthInteger-変換後画像の横長
              convertedImageInfo.heightInteger-変換後画像の縦長
              convertedImageInfo.pageIndexInteger-変換後画像ページインデックス
              convertedImageInfo.longImageBoolean-変換後画像は長さが Longかどうか
              • true | false
                • true: 長い(Long)画像
                • false: 長い(Long)画像ではない
              combineResultObject-画像認識結果の都合情報
              combineResult.nameString-画像結合フィールド名
              combineResult.textString-各画像フィールドごとの出力値と固定テキスト
              fieldsArray-Fieldsの詳細情報
              titleObject-画像のタイトルの詳細情報
              title.nameString-テンプレートの代表サンプルフィールド名
              • 画像の識別とレスポンス結果の確認に使用
              title.boundingPolyObject-Bounding Poly情報
              • versionがV2の場合にのみ提供
              title.boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
              title.inferTextString-認識結果テキスト
              • typeがCHECKBOXの場合、設定で指定したレスポンスに置換
              title.inferConfidenceFloat-認識結果テキストの信頼度
              • 0~1
              • 信頼度が高いほどテキストの精度が高い
              title.subFieldsArray-subFieldsの詳細情報

              fields

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

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

              subFields

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

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

              vertices

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

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

              bounding

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

              フィールドタイプ必須の有無説明
              topFloat-Bounding y軸の座標
              leftFloat-Bounding x軸の座標
              widthFloat-Bounding Poly横
              heightFloat-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
                    }
                ]
            }
        },
    ]
}
              JSON

              失敗

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

              {
    "version": "V1",
    "requestId": "1234",
    "timestamp": 1724833931723,
    "images": [
        {
            "uid": "{uid}",
            "name": "hello",
            "inferResult": "FAILURE",
            "message": "NOT_FOUND: not found matched template",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}
              JSON
              この記事は役に立ちましたか?
              Change password!
              Changing your password will log you out immediately. Use the new password to log back in.
              Change profile
              Success!
              First name must have atleast 2 characters. Numbers and special characters are not allowed.
              Last name must have atleast 1 characters. Numbers and special characters are not allowed.
              Enter a valid email
              Enter a valid password
              Your profile has been successfully updated.
              Logout