# 이미지 텍스트 추출(OCR) OCR(Optical Character Recognition) 이미지 파일에서 텍스트를 추출합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/ocr 응답 필드 - `data` (object): 조회 데이터 - `data.result` (object): 추출 결과 - `data.result.text_coordinate` (array): 텍스트 좌표 리스트 - `data.result.text_coordinate[].description` (string): 내용 - `data.result.text_coordinate[].vertices` (array): 꼭지점 좌표 리스트 - `data.result.text_coordinate[].vertices[].x` (integer): x 좌표 - `data.result.text_coordinate[].vertices[].y` (integer): y 좌표 - `data.result.full_text` (string): 전체 추출 결과 - `data.success` (integer): 과금 여부0: 실패1: 성공3: 실패(timeout) - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부 - `api.cost` (integer): API 호출 요금 - `api.ms` (integer): API 응답 시간 - `api.pl_id` (integer): API 결제 로그 ID ## API 요청: POST /rest/ocr ### 입력 - `image` (file, 필수): 이미지 파일 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "text_coordinate": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "내용" }, "vertices": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "integer", "description": "x 좌표" }, "y": { "type": "integer", "description": "y 좌표" } } }, "description": "꼭지점 좌표 리스트" } } }, "description": "텍스트 좌표 리스트" }, "full_text": { "type": "string", "description": "전체 추출 결과" } }, "description": "추출 결과" }, "success": { "type": "integer", "description": "과금 여부0: 실패1: 성공3: 실패(timeout)" } }, "description": "조회 데이터" }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 서버 정상 응답 여부" }, "cost": { "type": "integer", "description": "API 호출 요금" }, "ms": { "type": "integer", "description": "API 응답 시간" }, "pl_id": { "type": "integer", "description": "API 결제 로그 ID" } }, "description": "API 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "data": { "result": { "text_coordinate": [ { "description": "주민등록증\n홍길동(洪吉洞)\n800101-2345678\n서울특별시 가산디지털1로\n(대륭테크노타운 18차)\n2020.08.16.\n서울특별시 금천구청장 청바", "vertices": [ { "x": 56, "y": 48 }, { "x": 612, "y": 48 }, { "x": 612, "y": 423 }, { "x": 56, "y": 423 } ] }, { "description": "주민등록증", "vertices": [ { "x": 109, "y": 48 }, { "x": 371, "y": 48 }, { "x": 371, "y": 90 }, { "x": 109, "y": 90 } ] }, { "description": "홍길동", "vertices": [ { "x": 77, "y": 122 }, { "x": 194, "y": 122 }, { "x": 194, "y": 160 }, { "x": 77, "y": 160 } ] }, { "description": "(", "vertices": [ { "x": 204, "y": 122 }, { "x": 214, "y": 122 }, { "x": 214, "y": 160 }, { "x": 204, "y": 160 } ] }, { "description": "洪吉洞", "vertices": [ { "x": 223, "y": 122 }, { "x": 338, "y": 122 }, { "x": 338, "y": 160 }, { "x": 223, "y": 160 } ] }, { "description": ")", "vertices": [ { "x": 349, "y": 122 }, { "x": 358, "y": 122 }, { "x": 358, "y": 160 }, { "x": 349, "y": 160 } ] }, { "description": "800101-2345678", "vertices": [ { "x": 72, "y": 187 }, { "x": 362, "y": 187 }, { "x": 362, "y": 211 }, { "x": 72, "y": 211 } ] }, { "description": "서울", "vertices": [ { "x": 56, "y": 240 }, { "x": 109, "y": 240 }, { "x": 109, "y": 267 }, { "x": 56, "y": 267 } ] }, { "description": "특별시", "vertices": [ { "x": 112, "y": 240 }, { "x": 188, "y": 240 }, { "x": 188, "y": 267 }, { "x": 112, "y": 267 } ] }, { "description": "가산", "vertices": [ { "x": 208, "y": 240 }, { "x": 260, "y": 240 }, { "x": 260, "y": 267 }, { "x": 208, "y": 267 } ] }, { "description": "디지털", "vertices": [ { "x": 264, "y": 240 }, { "x": 339, "y": 240 }, { "x": 339, "y": 267 }, { "x": 264, "y": 267 } ] }, { "description": "1", "vertices": [ { "x": 346, "y": 240 }, { "x": 355, "y": 240 }, { "x": 355, "y": 267 }, { "x": 346, "y": 267 } ] }, { "description": "로", "vertices": [ { "x": 359, "y": 240 }, { "x": 382, "y": 240 }, { "x": 382, "y": 267 }, { "x": 359, "y": 267 } ] }, { "description": "(", "vertices": [ { "x": 60, "y": 272 }, { "x": 67, "y": 272 }, { "x": 67, "y": 298 }, { "x": 60, "y": 298 } ] }, { "description": "대륭", "vertices": [ { "x": 73, "y": 272 }, { "x": 123, "y": 272 }, { "x": 123, "y": 298 }, { "x": 73, "y": 298 } ] }, { "description": "테크노", "vertices": [ { "x": 128, "y": 272 }, { "x": 205, "y": 272 }, { "x": 205, "y": 298 }, { "x": 128, "y": 298 } ] }, { "description": "타운", "vertices": [ { "x": 209, "y": 272 }, { "x": 260, "y": 272 }, { "x": 260, "y": 298 }, { "x": 209, "y": 298 } ] }, { "description": "18", "vertices": [ { "x": 278, "y": 272 }, { "x": 302, "y": 272 }, { "x": 302, "y": 298 }, { "x": 278, "y": 298 } ] }, { "description": "차", "vertices": [ { "x": 304, "y": 272 }, { "x": 329, "y": 272 }, { "x": 329, "y": 298 }, { "x": 304, "y": 298 } ] }, { "description": ")", "vertices": [ { "x": 334, "y": 272 }, { "x": 342, "y": 272 }, { "x": 342, "y": 298 }, { "x": 334, "y": 298 } ] }, { "description": "2020.08.16", "vertices": [ { "x": 248, "y": 354 }, { "x": 405, "y": 355 }, { "x": 405, "y": 376 }, { "x": 248, "y": 375 } ] }, { "description": ".", "vertices": [ { "x": 413, "y": 355 }, { "x": 419, "y": 355 }, { "x": 419, "y": 375 }, { "x": 413, "y": 375 } ] }, { "description": "서울", "vertices": [ { "x": 152, "y": 380 }, { "x": 218, "y": 380 }, { "x": 218, "y": 422 }, { "x": 152, "y": 422 } ] }, { "description": "특별시", "vertices": [ { "x": 223, "y": 380 }, { "x": 321, "y": 380 }, { "x": 321, "y": 422 }, { "x": 223, "y": 422 } ] }, { "description": "금천구", "vertices": [ { "x": 347, "y": 380 }, { "x": 447, "y": 380 }, { "x": 447, "y": 422 }, { "x": 347, "y": 422 } ] }, { "description": "청장", "vertices": [ { "x": 452, "y": 380 }, { "x": 518, "y": 380 }, { "x": 518, "y": 422 }, { "x": 452, "y": 422 } ] }, { "description": "청바", "vertices": [ { "x": 532, "y": 380 }, { "x": 612, "y": 380 }, { "x": 612, "y": 422 }, { "x": 532, "y": 422 } ] } ], "full_text": "주민등록증\n홍길동(洪吉洞)\n800101-2345678\n서울특별시 가산디지털1로\n(대륭테크노타운 18차)\n2020.08.16.\n서울특별시 금천구청장 청바" }, "success": 1 }, "api": { "success": true, "cost": 12, "ms": 608, "pl_id": 4106065 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/ocr' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form 'image=@/C:/Users/user/Desktop/sample_idcard.png' ``` ### Node.js (서버 ESM) ```javascript import { readFile } from "node:fs/promises"; const form = new FormData(); form.append("image", new Blob([await readFile("/C:/Users/user/Desktop/sample_idcard.png")]), "sample_idcard.png"); const response = await fetch("https://apick.app/rest/ocr", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("image", ("sample_idcard.png", open("/C:/Users/user/Desktop/sample_idcard.png", "rb"))), ] response = requests.request("POST", "https://apick.app/rest/ocr", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php new CURLFile('/C:/Users/user/Desktop/sample_idcard.png'), ]; $curl = curl_init('https://apick.app/rest/ocr'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 - OCR_IMAGE_MISSING (400): 이미지 파일을 첨부하세요. - OCR_UNSUPPORTED_IMAGE (400): 지원 이미지 형식을 사용하세요. - OCR_IMAGE_TOO_LARGE (413): 50MB 이하 이미지를 사용하세요. - OCR_NO_TEXT (422): 판독 가능한 글자가 없습니다. 선명한 이미지를 사용하세요. - OCR_TIMEOUT (408): 처리 시간이 초과됐습니다. 이미지 크기와 품질을 확인하세요. - OCR_CREDENTIALS_ERROR (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_CREDENTIALS_MISSING (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_UNAUTHORIZED (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_RATE_LIMITED (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_UPSTREAM_UNAVAILABLE (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_REQUEST_FAILED (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. - OCR_EMPTY_RESPONSE (424): 문서 처리 서비스를 일시적으로 이용할 수 없습니다. 잠시 후 다시 시도하세요. 반복되면 오류코드와 함께 문의하세요. ## 상세 기능·요금 업로드 용량 제한: 50MB 첨부 이미지 합계는 최대 50MB입니다. 서버가 판독 가능한 크기로 최적화하며, 지나치게 큰 해상도는 정확도를 높이지 않고 처리시간만 늘릴 수 있습니다. 제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다. Method URL POST https://apick.app/rest/ocr ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 ## 상세 응답 Body 이름 타입 설명 data Object 조회 데이터 result Object 추출 결과 text_coordinate Array 텍스트 좌표 리스트 {} Object 텍스트 좌표 정보 description String 내용 vertices Array 꼭지점 좌표 리스트 {} Object 꼭지점 좌표 x Integer x 좌표 y Integer y 좌표 full_text String 전체 추출 결과 success Integer 과금 여부0: 실패1: 성공3: 실패(timeout) api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer API 호출 요금 ms Integer API 응답 시간 pl_id Integer API 결제 로그 ID ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "result": { "text_coordinate": [ { "description": "주민등록증\n홍길동(洪吉洞)\n800101-2345678\n서울특별시 가산디지털1로\n(대륭테크노타운 18차)\n2020.08.16.\n서울특별시 금천구청장 청바", "vertices": [ { "x": 56, "y": 48 }, { "x": 612, "y": 48 }, { "x": 612, "y": 423 }, { "x": 56, "y": 423 } ] }, { "description": "주민등록증", "vertices": [ { "x": 109, "y": 48 }, { "x": 371, "y": 48 }, { "x": 371, "y": 90 }, { "x": 109, "y": 90 } ] }, { "description": "홍길동", "vertices": [ { "x": 77, "y": 122 }, { "x": 194, "y": 122 }, { "x": 194, "y": 160 }, { "x": 77, "y": 160 } ] }, { "description": "(", "vertices": [ { "x": 204, "y": 122 }, { "x": 214, "y": 122 }, { "x": 214, "y": 160 }, { "x": 204, "y": 160 } ] }, { "description": "洪吉洞", "vertices": [ { "x": 223, "y": 122 }, { "x": 338, "y": 122 }, { "x": 338, "y": 160 }, { "x": 223, "y": 160 } ] }, { "description": ")", "vertices": [ { "x": 349, "y": 122 }, { "x": 358, "y": 122 }, { "x": 358, "y": 160 }, { "x": 349, "y": 160 } ] }, { "description": "800101-2345678", "vertices": [ { "x": 72, "y": 187 }, { "x": 362, "y": 187 }, { "x": 362, "y": 211 }, { "x": 72, "y": 211 } ] }, { "description": "서울", "vertices": [ { "x": 56, "y": 240 }, { "x": 109, "y": 240 }, { "x": 109, "y": 267 }, { "x": 56, "y": 267 } ] }, { "description": "특별시", "vertices": [ { "x": 112, "y": 240 }, { "x": 188, "y": 240 }, { "x": 188, "y": 267 }, { "x": 112, "y": 267 } ] }, { "description": "가산", "vertices": [ { "x": 208, "y": 240 }, { "x": 260, "y": 240 }, { "x": 260, "y": 267 }, { "x": 208, "y": 267 } ] }, { "description": "디지털", "vertices": [ { "x": 264, "y": 240 }, { "x": 339, "y": 240 }, { "x": 339, "y": 267 }, { "x": 264, "y": 267 } ] }, { "description": "1", "vertices": [ { "x": 346, "y": 240 }, { "x": 355, "y": 240 }, { "x": 355, "y": 267 }, { "x": 346, "y": 267 } ] }, { "description": "로", "vertices": [ { "x": 359, "y": 240 }, { "x": 382, "y": 240 }, { "x": 382, "y": 267 }, { "x": 359, "y": 267 } ] }, { "description": "(", "vertices": [ { "x": 60, "y": 272 }, { "x": 67, "y": 272 }, { "x": 67, "y": 298 }, { "x": 60, "y": 298 } ] }, { "description": "대륭", "vertices": [ { "x": 73, "y": 272 }, { "x": 123, "y": 272 }, { "x": 123, "y": 298 }, { "x": 73, "y": 298 } ] }, { "description": "테크노", "vertices": [ { "x": 128, "y": 272 }, { "x": 205, "y": 272 }, { "x": 205, "y": 298 }, { "x": 128, "y": 298 } ] }, { "description": "타운", "vertices": [ { "x": 209, "y": 272 }, { "x": 260, "y": 272 }, { "x": 260, "y": 298 }, { "x": 209, "y": 298 } ] }, { "description": "18", "vertices": [ { "x": 278, "y": 272 }, { "x": 302, "y": 272 }, { "x": 302, "y": 298 }, { "x": 278, "y": 298 } ] }, { "description": "차", "vertices": [ { "x": 304, "y": 272 }, { "x": 329, "y": 272 }, { "x": 329, "y": 298 }, { "x": 304, "y": 298 } ] }, { "description": ")", "vertices": [ { "x": 334, "y": 272 }, { "x": 342, "y": 272 }, { "x": 342, "y": 298 }, { "x": 334, "y": 298 } ] }, { "description": "2020.08.16", "vertices": [ { "x": 248, "y": 354 }, { "x": 405, "y": 355 }, { "x": 405, "y": 376 }, { "x": 248, "y": 375 } ] }, { "description": ".", "vertices": [ { "x": 413, "y": 355 }, { "x": 419, "y": 355 }, { "x": 419, "y": 375 }, { "x": 413, "y": 375 } ] }, { "description": "서울", "vertices": [ { "x": 152, "y": 380 }, { "x": 218, "y": 380 }, { "x": 218, "y": 422 }, { "x": 152, "y": 422 } ] }, { "description": "특별시", "vertices": [ { "x": 223, "y": 380 }, { "x": 321, "y": 380 }, { "x": 321, "y": 422 }, { "x": 223, "y": 422 } ] }, { "description": "금천구", "vertices": [ { "x": 347, "y": 380 }, { "x": 447, "y": 380 }, { "x": 447, "y": 422 }, { "x": 347, "y": 422 } ] }, { "description": "청장", "vertices": [ { "x": 452, "y": 380 }, { "x": 518, "y": 380 }, { "x": 518, "y": 422 }, { "x": 452, "y": 422 } ] }, { "description": "청바", "vertices": [ { "x": 532, "y": 380 }, { "x": 612, "y": 380 }, { "x": 612, "y": 422 }, { "x": 532, "y": 422 } ] } ], "full_text": "주민등록증\n홍길동(洪吉洞)\n800101-2345678\n서울특별시 가산디지털1로\n(대륭테크노타운 18차)\n2020.08.16.\n서울특별시 금천구청장 청바" }, "success": 1 }, "api": { "success": true, "cost": 12, "ms": 608, "pl_id": 4106065 } }