General OCR

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

画像全域のテキストを認識・抽出します。

リクエスト

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

メソッド	URI
POST	/general

リクエストヘッダ

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

リクエストボディ

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

`Content-Type: application/json`の場合

リクエストヘッダのContent-Typeがapplication/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
`enableTableDetection`	Boolean	Optional	文書画像内の表(Table)領域を認識して構造化された形で提供するかどうか `true` \| `false`(デフォルト) `true`: 表を認識し、その構造を提供 `false`: 表を認識せず、構造を提供しない NAVERクラウドプラットフォームで作成した Domainで「表を抽出するかどうか」トグルボタンをオン(ON)にすると使用可能

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

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

フィールド	タイプ	必須の有無	説明
`message`	Object	Required	リクエストデータ情報
`file`	File	Required	OCR認識画像ファイル
`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
`message.enableTableDetection`	Boolean	Optional	文書画像内の表(Table)領域を認識して構造化された形で提供するかどうか `true` \| `false`(デフォルト) `true`: 表を認識し、その構造を提供 `false`: 表を認識せず、構造を提供しない NAVERクラウドプラットフォームで作成した Domainで「表を抽出するかどうか」トグルボタンをオン(ON)にすると使用可能

`images`

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

フィールド	タイプ	必須の有無	説明
`format`	String	Required	画像形式 `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` `pdf`: 最大10ページまで認識可能
`name`	String	Required	画像名画像の識別とレスポンス結果の確認に使用
`url`	String	Conditional	画像の URLアドレス画像が取得可能な公開された URL `images.url`または`images.data`のうちどちらかは必ず入力両方入力すると`images.data`が優先
`data`	String	Conditional	Base64でエンコードされた画像データ `images.url`または`images.data`のうちどちらかは必ず入力両方入力すると`images.data`が優先

リクエスト例

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

`Content-Type: application/json`の場合

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

curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33675/8f694ccb00dbd8001e9b0fcbac****************/general' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
    "version": "V2",
    "requestId": "1234",
    "timestamp": "1722225600000",
    "lang": "ko",
    "images": [
        {
        "format": "jpg",
        "name": "demo_2",
        "url": "https://www.ncloud.com/file-img/vol02/000/614/********/********_0001.jpg"
        }
    ],
    "enableTableDetection": false
}'

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

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

curl --location --request POST 'https://*****.apigw.ntruss.com/custom/v1/33675/8f694ccb00dbd8001e9b0fcbac**********************/general' \
--header 'Content-Type: multipart/form-data' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--form 'file=@"{file}.pdf"' \
--form 'message="{\"version\": \"v1\", \"requestId\": \"1234\", \"timestamp\": 1722225600000, \"lang\": \"ko\", \"images\": [{\"format\": \"pdf\", \"name\": \"covid_sample\"}]}"'

レスポンス

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

参考

V1バージョンでリクエストするとレスポンス結果にconvertedImageInfo、type、lineBreak情報が表示されません。

レスポンスボディ

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

フィールド	タイプ	必須の有無	説明
`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	-	結果メッセージ
`validationResult`	Object	-	有効性検査の結果情報
`validationResult.result`	String	-	有効性検査の結果コード `NO_REQUESTED` \| `UNCHECKED` \| `ERROR` \| `VALID` \| `INVALID` `NO_REQUESTED`: 検証をリクエストしていない `UNCHECKED`: 動作レスポンスを確認しなかったか、レスポンスを受諾していない `ERROR`: 検証中にエラーが発生 `VALID`: 検証結果は有効 `INVALID`: 検証結果は有効ではない
`validationResult.message`	String	-	有効性検査結果の詳細メッセージ必ずしも返される値ではない
`convertedImageInfo`	Object	-	変換後の画像情報 `format`が`pdf`または`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	-	各画像フィールドごとの出力値と固定テキスト
`tables`	Array	-	Tablesの詳細情報
`fields`	Array	-	Fieldsの詳細情報

`tables`

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

フィールド	タイプ	必須の有無	説明
`cells`	Array	-	Cellsの詳細情報
`inferText`	String	-	認識されたテキスト
`inferConfidence`	Float	-	認識結果テキストの信頼度 0~1 信頼度が高いほどテキストの精度が高い
`boundingPoly`	Object	-	Bounding Poly情報 `version`が`V2`の場合にのみ提供
`boundingPoly.vertices`	Array	-	Bounding Poly Verticesの詳細情報

`fields`

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

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

`cells`

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

フィールド	タイプ	必須の有無	説明
`boundingPoly`	Object	-	Bounding Poly情報 `version`が`V2`の場合にのみ提供
`boundingPoly.vertices`	Array	-	Bounding Poly Verticesの詳細情報
`cellTextLines`	Array	-	セルのラインの詳細情報
`inferConfidence`	Float	-	認識結果テキストの信頼度 0~1 信頼度が高いほどテキストの精度が高い
`rowSpan`	Integer	-	表のセルが占める(Span)横列の数
`rowIndex`	Integer	-	表内のその横列の位置値
`columnSpan`	Integer	-	表のセルが占める(Span)縦行の数
`columnIndex`	Integer	-	表内のその縦行の位置値

`cellTextLines`

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

フィールド	タイプ	必須の有無	説明
`boundingPoly`	Object	-	Bounding Poly情報 `version`が`V2`の場合にのみ提供
`boundingPoly.vertices`	Array	-	Bounding Poly Verticesの詳細情報
`inferConfidence`	Float	-	認識結果テキストの信頼度 0~1 信頼度が高いほどテキストの精度が高い
`cellWords`	Array	-	セルのテキストの詳細情報

`cellWords`

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

フィールド	タイプ	必須の有無	説明
`boundingPoly`	Object	-	Bounding Poly情報 `version`が`V2`の場合にのみ提供
`boundingPoly.vertices`	Array	-	Bounding Poly Verticesの詳細情報
`inferConfidence`	Float	-	認識結果テキストの信頼度 0~1 信頼度が高いほどテキストの精度が高い
`inferText`	String	-	認識されたテキスト

`vertices`

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

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

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

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

レスポンス例

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

`version`が`V2`の場合

versionがV2の場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1576569034247,
    "images": [{
        "uid": "9fd73a6aacad4025b3099a36ee55aacd",
        "name": "medium",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "validationResult": {
                "result": "NO_REQUESTED"
            },
            "convertedImageInfo": {
                "width": 1224,
                "height": 1584,
                "pageIndex": 0,
                "longImage": false
            },
        "fields": [{
                "valueType": "ALL",
                "inferText": "美しき",
                "inferConfidence": 0.99992156,
                "type": "NORMAL",
                "lineBreak": true,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2713.7295,
                        "y": 1277.0492
                    }, {
                        "x": 2713.7295,
                        "y": 977.7408
                    }, {
                        "x": 2841.4343,
                        "y": 977.7408
                    }, {
                        "x": 2841.4343,
                        "y": 1277.0492
                    }]
                }
            },
            {
                "valueType": "ALL",
                "inferText": "この",
                "inferConfidence": 0.99958915,
                "type": "NORMAL",
                "lineBreak": false,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2314.6516,
                        "y": 1468.6066
                    }, {
                        "x": 2314.6516,
                        "y": 1328.9293
                    }, {
                        "x": 2426.3936,
                        "y": 1328.9293
                    }, {
                        "x": 2426.3936,
                        "y": 1468.6066
                    }]
                }
            },
            {
                "valueType": "ALL",
                "inferText": "世界を",
                "inferConfidence": 0.9998707,
                "type": "NORMAL",
                "lineBreak": false,
                "boundingPoly": {
                    "vertices": [{
                        "x": 2314.6516,
                        "y": 1604.2931
                    }, {
                        "x": 2314.6516,
                        "y": 1460.625
                    }, {
                        "x": 2430.3843,
                        "y": 1460.625
                    }, {
                        "x": 2430.3843,
                        "y": 1604.2931
                    }]
                }
            }
        ]
    }]
}

`version`が`V1`の場合

versionがV1の場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "v1",
    "requestId": "1234",
    "timestamp": 1724821610657,
    "images": [
        {
            "uid": "{uid}",
            "name": "covid_demo",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "fields": [
                {
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 581.0,
                                "y": 123.0
                            },
                            {
                                "x": 650.0,
                                "y": 123.0
                            },
                            {
                                "x": 650.0,
                                "y": 149.0
                            },
                            {
                                "x": 581.0,
                                "y": 149.0
                            }
                        ]
                    },
                    "inferText": "育てていく",
                    "inferConfidence": 0.9985
                },
                {
                    "valueType": "ALL",
                    "boundingPoly": {
                        "vertices": [
                            {
                                "x": 399.0,
                                "y": 1168.0
                            },
                            {
                                "x": 790.0,
                                "y": 1168.0
                            },
                            {
                                "x": 790.0,
                                "y": 1215.0
                            },
                            {
                                "x": 399.0,
                                "y": 1215.0
                            }
                        ]
                    },
                    "inferText": "ソウル特別市小学校長",
                    "inferConfidence": 0.9997
                }
            ]
        }
    ]
}

General OCR

リクエスト

リクエストヘッダ

リクエストボディ

Content-Type: application/jsonの場合

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

images

リクエスト例

Content-Type: application/jsonの場合

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

レスポンス

レスポンスボディ

images

tables

fields

cells

cellTextLines

cellWords

vertices

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

レスポンス例

versionがV2の場合

versionがV1の場合

`Content-Type: application/json`の場合

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

`images`

`Content-Type: application/json`の場合

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

`images`

`tables`

`fields`

`cells`

`cellTextLines`

`cellWords`

`vertices`

`version`が`V2`の場合

`version`が`V1`の場合