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개의 이미지 Array 작성 가능 이미지 크기: 최대 50 MB
`enableTableDetection`	Boolean	Optional	문서 이미지 내 표(Table) 영역 인식 및 구조화된 형태 제공 여부 `true` \| `false` (기본값) `true`: 표 인식 및 형태 제공 `false`: 표 미인식 및 형태 미제공 네이버 클라우드 플랫폼에 생성한 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개의 이미지 Array 작성 가능 이미지 크기: 최대 50 MB
`message.enableTableDetection`	Boolean	Optional	문서 이미지 내 표(Table) 영역 인식 및 구조화된 형태 제공 여부 `true` \| `false` (기본값) `true`: 표 인식 및 형태 제공 `false`: 표 미인식 및 형태 미제공 네이버 클라우드 플랫폼에 생성한 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`인 경우