--- title: "General OCR" slug: "ai-application-service-ocr-ocr" tags: ["CLOVA OCR"] updated: 2026-04-23T08:55:36Z published: 2026-04-23T09:02:17Z --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # General OCR Classic/VPC 환경에서 이용 가능합니다. 이미지 내 모든 영역의 텍스트를 인식하고 추출합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /general | ### 요청 헤더 CLOVA OCR API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA OCR 요청 헤더](/docs/ai-application-service-ocr#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오. ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. #### `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 호출 시각(밀리초) - Unix Timestamp 형식 | | `lang` | String | Optional | OCR 인식 요청 언어 정보 - `ko` \| `ja` \| `zh-TW` - `ko`: 한국어 - `ja`: 일본어 - `zh-TW`: 중국어(번체) - 미입력 시 도메인의 언어 설정값으로 자동 설정 - 콤마(,)를 통해 여러 언어 동시 호출 가능 - <예시> `"ko, ja, zh-TW"` | | `images` | Array | Required | images 세부 정보: [images](/docs/ai-application-service-ocr-ocr#images1) - 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`인 경우의 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `file` | File | Required | OCR 인식 이미지 파일 | | `message` | Object | Required | 요청 데이터 정보 | | `message.version` | String | Required | 버전 정보 - `V1` \| `V2` (권장값) - `V1`: V1 엔진 호출 - `V2`: V2 엔진 호출 | | `message.requestId` | String | Required | 임의의 API 호출 UUID | | `message.timestamp` | Integer | Required | 임의의 API 호출 시각(밀리초) - Unix Timestamp 형식 | | `message.lang` | String | Optional | OCR 인식 요청 언어 정보 - `ko` \| `ja` \| `zh-TW` - `ko`: 한국어 - `ja`: 일본어 - `zh-TW`: 중국어(번체) - 미입력 시 도메인의 언어 설정값으로 자동 설정 - 콤마(,)를 통해 여러 언어 동시 호출 가능 - <예시> `"ko, ja, zh-TW"` | | `message.images` | Array | Required | images 세부 정보: [images](/docs/ai-application-service-ocr-ocr#images1) - 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](/docs/ai-application-service-ocr-ocr#images2) | #### `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 세부 정보: [tables](/docs/ai-application-service-ocr-ocr#tables) | | `fields` | Array | - | Fields 세부 정보: [fields](/docs/ai-application-service-ocr-ocr#fields) | #### `tables` `tables`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `cells` | Array | - | Cells 세부 정보: [cells](/docs/ai-application-service-ocr-ocr#cells) | | `inferText` | String | - | 인식된 텍스트 | | `inferConfidence` | Float | - | 인식된 텍스트의 신뢰도 - 0~1 - 신뢰도 값이 클수록 텍스트의 정확도가 높음 | | `boundingPoly` | Object | - | Bounding Poly 정보 - `version`이 `V2`일 경우에만 제공 | | `boundingPoly.vertices` | Array | - | Bounding Poly Vertices 세부 정보: [vertices](/docs/ai-application-service-ocr-ocr#boundingpolyvertices) | #### `fields` `fields`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `name` | String | - | 이미지 이름 - 이미지 식별 및 응답 결과 확인 시 사용 - API 호출 시에만 작동 | | `valueType` | String | - | 입력값 유형 - `ALL` \| `NUMERIC` - `ALL`: 텍스트와 숫자 - `NUMERIC`: 숫자 | | `boundingPoly` | Object | - | Bounding Poly 정보 - `version`이 `V2`일 경우에만 제공 | | `boundingPoly.vertices` | Array | - | Bounding Poly Vertices 세부 정보: [vertices](/docs/ai-application-service-ocr-ocr#boundingpolyvertices) | | `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 세부 정보: [vertices](/docs/ai-application-service-ocr-ocr#boundingpolyvertices) | | `cellTextLines` | Array | - | 셀의 라인 세부 정보: [cellTextLines](/docs/ai-application-service-ocr-ocr#cellTextLines) | | `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 세부 정보: [vertices](/docs/ai-application-service-ocr-ocr#boundingpolyvertices) | | `inferConfidence` | Float | - | 인식된 텍스트의 신뢰도 - 0~1 - 신뢰도 값이 클수록 텍스트의 정확도가 높음 | | `cellWords` | Array | - | 셀의 텍스트 세부 정보: [cellWords](/docs/ai-application-service-ocr-ocr#cellWords) | #### `cellWords` `cellWords`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `boundingPoly` | Object | - | Bounding Poly 정보 - `version`이 `V2`일 경우에만 제공 | | `boundingPoly.vertices` | Array | - | Bounding Poly Vertices 세부 정보: [vertices](/docs/ai-application-service-ocr-ocr#boundingpolyvertices) | | `inferConfidence` | Float | - | 인식된 텍스트의 신뢰도 - 0~1 - 신뢰도 값이 클수록 텍스트의 정확도가 높음 | | `inferText` | String | - | 인식된 텍스트 | #### `vertices` `vertices`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `x` | Float | - | Bounding Poly X축 좌표 값 | | `y` | Float | - | Bounding Poly Y축 좌표 값 | ### 응답 상태 코드 CLOVA OCR API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA OCR 공통 응답 상태 코드](/docs/ai-application-service-ocr#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. ### 응답 예시 응답 예시는 다음과 같습니다. #### `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 } ] } ] } ```