CLOVA Template OCR API
    • PDF

    CLOVA Template OCR API

    • PDF

    記事の要約

    最新のコンテンツが反映されていません。早急にアップデート内容をご提供できるよう努めております。最新のコンテンツ内容は韓国語ページをご参照ください。

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

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

    リクエスト

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

    メソッドURI
    POST/infer

    リクエストヘッダ

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

    リクエストボディ

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

    Content-Type: application/jsonの場合

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

    フィールドタイプ必須の有無説明
    versionStringRequiredバージョン情報
    • V1 | V2(推奨)
      • V1: V1エンジンを呼び出す
      • V2: V2エンジンを呼び出す
    requestIdStringRequired任意の API呼び出し UUID
    timestampIntegerRequired任意の API呼び出し時刻(Timestamp)
    langStringOptionalOCR認識リクエストの言語情報
    • ko | en | ja | zh-TW
      • ko: 韓国語
      • en: 英語
      • ja: 日本語
      • zh-TW: 中国語(繁体字)
    • 入力しないとドメインの言語設定値に自動設定
    • コンマ「,」を利用すると複数の言語の同時呼び出しができる
      • <例> "ko, ja, zh-TW"
    imagesArrayRequiredimagesの詳細情報
    • JSON Arrayで作成
    • 呼び出し1件につき1つの画像 Arrayを作成可能
    • 画像サイズ: 最大50MB
    enableTableDetectionBooleanOptional文書画像内の表(Table)領域を認識して構造化された形で提供するかどうか
    • true | false(デフォルト)
      • true: 表を認識し、その構造を提供
      • false: 表を認識せず、構造を提供しない
    • NAVERクラウドプラットフォームで作成した Domainで「表を抽出するかどうか」トグルボタンをオン(ON)にすると使用可能

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

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

    フィールドタイプ必須の有無説明
    messageObjectRequiredリクエストデータ情報
    message.versionStringRequiredバージョン情報
    • V1 | V2(推奨)
      • V1: V1エンジンを呼び出す
      • V2: V2エンジンを呼び出す
    message.requestIdStringRequired任意の API呼び出し UUID
    message.timestampIntegerRequired任意の API呼び出し時刻(Timestamp)
    message.langStringOptionalOCR認識リクエストの言語情報
    • ko | en | ja | zh-TW
      • ko: 韓国語
      • en: 英語
      • ja: 日本語
      • zh-TW: 中国語(繁体字)
    • 入力しないとドメインの言語設定値に自動設定
    • コンマ「,」を利用すると複数の言語の同時呼び出しができる
      • <例> "ko, ja, zh-TW"
    message.imagesArrayRequiredimagesの詳細情報
    • JSON Arrayで作成
    • 呼び出し1件につき1つの画像 Arrayを作成可能
    • 画像サイズ: 最大50MB
    message.enableTableDetectionBooleanOptional文書画像内の表(Table)領域を認識して構造化された形で提供するかどうか
    • true | false(デフォルト)
      • true: 表を認識し、その構造を提供
      • false: 表を認識せず、構造を提供しない
    • NAVERクラウドプラットフォームで作成した Domainで「表を抽出するかどうか」トグルボタンをオン(ON)にすると使用可能
    fileFileRequiredOCR認識画像ファイル

    images

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

    フィールドタイプ必須の有無説明
    formatStringRequired画像形式
    • jpg | jpeg | png | pdf | tif | tiff
      • pdf: 最大5ページまで認識可能
    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-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]
        }
      ],
      "enableTableDetection": true
    }'
    

    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\"}]}"'
    

    レスポンス

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

    参考

    V2バージョンでリクエストするとレスポンス結果にboundingboundingPolyの情報が表示されます。

    レスポンスボディ

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

    フィールドタイプ必須の有無説明
    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-変換後の画像情報
    • formatpdfまたはtiffの場合
    • 座標は呼び出し画像ファイルを基準に設定
    convertedImageInfo.widthInteger-変換後画像の横長
    convertedImageInfo.heightInteger-変換後画像の縦長
    convertedImageInfo.pageIndexInteger-変換後画像ページインデックス
    convertedImageInfo.longImageBoolean-変換後画像は長さが Longかどうか
    • true | false
      • true: 長い(Long)画像
      • false: 長い(Long)画像ではない
    combineResultObject-画像認識結果の都合情報
    combineResult.nameString-画像結合フィールド名
    combineResult.textString-各画像フィールドごとの出力値と固定テキスト
    tablesArray-Tablesの詳細情報
    fieldsArray-Fieldsの詳細情報
    titleObject-画像のタイトルの詳細情報
    title.nameString-テンプレートの代表サンプルフィールド名
    • 画像の識別とレスポンス結果の確認に使用
    title.boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    title.boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    title.inferTextString-認識結果テキスト
    • typeCHECKBOXの場合、設定で指定したレスポンスに置換
    title.inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    title.subFieldsArray-subFieldsの詳細情報

    tables

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

    フィールドタイプ必須の有無説明
    cellsArray-Cellsの詳細情報
    inferTextString-認識されたテキスト
    inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報

    fields

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

    フィールドタイプ必須の有無説明
    nameString-テンプレートのフィールド名
    • APIの呼び出し時にのみ動作
    • 画像の識別とレスポンス結果の確認に使用
    valueTypeString-入力値のタイプ
    • ALL | NUMERIC
      • ALL: テキストと数字
      • NUMERIC: 数字
    boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    inferTextString-認識結果テキスト
    • typeCHECKBOXの場合、設定で指定したレスポンスに置換
    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情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    inferTextString-認識結果テキスト
    • typeCHECKBOXの場合、設定で指定したレスポンスに置換
    inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    lineBreakBoolean-認識結果テキストの最終行であるかどうかを表示
    • true | false
      • true: 最後のテキスト
      • false: 最後のテキストではない

    cells

    tables.cellsの説明は次の通りです。

    フィールドタイプ必須の有無説明
    boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    cellTextLinesArray-cellTextLinesの詳細情報
    inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    rowSpanInteger-表のセルが占める(Span)横列の数
    rowIndexInteger-表内のその横列の位置値
    columnSpanInteger-表のセルが占める(Span)縦行の数
    columnIndexInteger-表内のその縦行の位置値

    cellTextLines

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

    フィールドタイプ必須の有無説明
    boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    cellWordsArray-セルのテキストの詳細情報

    cellWords

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

    フィールドタイプ必須の有無説明
    boundingPolyObject-Bounding Poly情報
    • versionV2の場合にのみ提供
    boundingPoly.verticesArray-Bounding Poly Verticesの詳細情報
    inferConfidenceFloat-認識結果テキストの信頼度
    • 0~1
    • 信頼度が高いほどテキストの精度が高い
    inferTextString-認識されたテキスト

    vertices

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

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

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

    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"
                }
            }
        ]
    }
    

    この記事は役に立ちましたか?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    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.