무료 여권 OCR API 사용하기

계정 없이 첫 인식 실행하기

문서에서 키를 복사하고 이미지를 POST로 보내세요. 연동은 이것이 전부입니다.

IMG=$(base64 -i passport.jpg | tr -d '\n')

curl -s https://api.doc.cheap/v1/scans \
  -H "Authorization: Bearer sk_sandbox_public" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-call-1" \
  -d '{"image":"'"$IMG"'","options":{"mode":"full"}}'

공개 sandbox 키는 sk_sandbox_public입니다. 일부러 공개한 키이며, 비밀이 아니고, 요청 한도가 있습니다. Idempotency-Key를 사용하면 재시도한 요청이 두 번 과금되지 않습니다. 대기열을 다시 처리해야 하는 날에 중요해지는 부분입니다.

돌려받는 것

응답 구조는 하나, 그룹은 여덟 개이며, 모든 키가 항상 포함됩니다. 필드 탐색기에서 모든 키와 그 타입을 볼 수 있고, API 레퍼런스(영문)가 곧 계약 그 자체입니다.

{
  "meta": { "schema_version": "1.0", "status": "recognized", "billed": true,
            "confidence": "high",
            "timing": { "upload_ms": 118, "processing_ms": 684, "total_ms": 826 } },
  "document": { "kind": "passport", "country": "GRC", "country_name": "Greece",
                "number": "AM7304518", "series": null,
                "issue_date": "2022-03-10", "expiry_date": "2032-03-10",
                "is_expired": false, "days_remaining": 2001 },
  "holder": { "given_names": "ELENI SOFIA", "surname": "PARADEIGMA",
              "birth_date": "1994-03-08", "sex": "F", "nationality": "GRC" },
  "mrz": { "status": "passed", "reason": null, "lines": ["…", "…"] },
  "fields": [ "…" ], "images": { "…": null },
  "quality": { "overall": "pass" },
  "authenticity": { "overall": "not_checked", "checks": [] }
}

• meta.status는 정확히 다섯 가지 문자열 중 하나입니다: recognized, no_document_found, unreadable, unsupported_document, rejected.
• 날짜는 항상 ISO-8601 형식입니다. 값이 없으면 null이며, 키가 빠지는 일은 없습니다.
• meta.billed는 모든 응답에 있으며, 그 호출에 비용이 들었는지를 알려 줍니다.
• fields[]에는 문서에 담긴 모든 필드가 들어 있습니다. 부호화된 영역과 인쇄된 영역에서 각각 따로 읽으며, 각자의 신뢰도가 있어 두 판독 결과를 비교할 수 있습니다. 원래 문자로 된 값은 라틴 문자 음역과 나란히 제공되며, 언어 태그가 붙습니다.

예제의 소지자는 합성된 견본입니다. 가상의 인물이며, 가상의 값에 실제 체크 디지트 계산을 적용했습니다. 이 인물이 가진 영역은 MRZ 형식 페이지에서 설명합니다.

무료 호출 이후의 비용

이미지는 어떻게 되나요

sandbox 키에서는 아무것도 보관하지 않습니다. 이미지는 디스크에 기록되지 않으며 요청이 처리되는 동안에만 메모리에 존재하고, 결과도 저장되지 않습니다. 본인의 live 키에서는 나중에 다시 읽을 수 있도록 결과가 보관됩니다. 기간은 요청에 지정한 retain_hours이며, 지정하지 않으면 계정의 보관 기간 설정을 따르고, 바꾸기 전까지는 1년(8760시간)입니다.

아무것도 보관하지 않으려면 retain_hours: 0을 보내세요. 저장되는 결과도, 나중에 다시 가져올 것도 없습니다. 호출마다 직접 선택합니다.

사진을 읽을 수 없을 때

응답이 그 사실을 알려 주며, 무료입니다. meta.status로 경우를 구분하며, 세 경우 모두 meta.billed는 false입니다.

• no_document_found – 화면 안에 문서 형태의 대상이 없음.
• unreadable – 찾았지만 읽을 수 없음 – 빛 반사, 흐림, 해상도.
• unsupported_document – 읽었지만 지원하지 않는 유형.

모든 응답에는 자체 소요 시간 내역이 포함되며, 실시간 중앙값은 여기서 약속하는 대신 상태 페이지에 공개됩니다.

키가 전혀 필요 없는 무료 도구

• MRZ 파서 – TD1, TD2 또는 TD3 영역을 붙여 넣으면 모든 필드와 체크 디지트를 볼 수 있습니다. 브라우저에서 실행됩니다.
• MRZ 생성기 – 테스트용으로 유효한 영역을 만듭니다.
• 문서 필드 탐색기 – API가 응답에 사용하는 필드 어휘를 살펴봅니다.

코드 대신 어시스턴트에서 호출하시나요? MCP 서버가 같은 인식 기능을 세 가지 도구로 제공합니다.