OCRRouter

API 문서

핵심 개념에 대한 가이드입니다. 모든 엔드포인트와 파라미터는 API 레퍼런스에 정리되어 있습니다.

빠른 시작

API 키를 생성한 후 파일을 전송하세요. 새 계정에는 50 무료 크레딧이 기본 제공됩니다.

curl https://api.ocrrouter.ai/v1/ocr \
  -H "Authorization: Bearer $OCRROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "file_url": "https://example.com/invoice.pdf",
    "format": "markdown"
  }'

요청

JSON 본문과 Authorization: Bearer 헤더를 포함하여 POST https://api.ocrrouter.ai/v1/ocr로 요청합니다.

modelstringmistral/mistral-ocr과 같은 모델 ID 또는 auto.
file_urlstringPDF 또는 이미지의 공개 URL입니다. file_url, file_base64, file_id 중 하나를 사용하세요.
file_base64stringbase64로 인코딩된 파일입니다 (최대 20 MB).
file_idstring더 큰 파일의 경우 POST /v1/files에서 반환된 ID입니다.
formatstringmarkdown (기본값), json, text, html, csv, docx 또는 xlsx.
pagesstring페이지 범위 (예: 1-5,8). 기본값은 전체 페이지입니다.
fallbacksstring[]첫 번째 모델 실패 시 순서대로 시도할 모델 ID 목록입니다.
routestringmodel이 auto일 때 지정: quality (기본값), cheapest 또는 fastest.
filenamestring활동 로그에 표시할 선택적 파일 이름입니다.

기타 엔드포인트:

  • GET /v1/models는 모든 모델, 가격 및 사용 가능 여부를 조회합니다. 키가 필요하지 않습니다.
  • POST /v1/files는 file 필드를 포함한 multipart 업로드를 받아 24시간 동안 유효한 file_id를 반환합니다.
  • GET /v1/requests/:id는 이전 작업 결과를 조회합니다. 다른 출력 형식을 받으려면 ?format=에 원하는 형식을 추가하세요.
  • GET /v1/credits는 크레딧 잔액과 현재 키의 사용량을 조회합니다.
  • POST /v1/keys/temporary는 50 크레딧이 포함된 임시 키를 반환합니다. 회원가입 없이 1일 1회 발급 가능합니다.

출력 형식

markdown

전체 문서가 Markdown으로 반환됩니다. 표는 GitHub 스타일 테이블로, 수식은 $...$로 감싸지며, 페이지는 <!-- page:N -->으로 구분됩니다.

json

모든 모델에서 통일된 구조로 반환됩니다. 페이지별로 타입이 지정된 블록들로 구성됩니다. 블록 타입은 heading, paragraph, list, table, formula, image, header, footer입니다. 모델이 정보를 제공하지 않는 경우 bbox, confidence, 페이지 크기는 null로 반환되며, 현재 서비스 중인 모델들이 이에 해당합니다.

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "json","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"pages": [{"index": 1,"width": null,"height": null,"blocks": [{"type": "heading","level": 1,"text": "Invoice INV-2041","bbox": null,"confidence": null},{"type": "paragraph","text": "Acme Supply Co.\n14 Harbour Street, Sydney NSW 2…","bbox": null,"confidence": null},{"type": "table","rows": [["Item", "Qty", "Unit price", "Amount"],["A4 paper, 5 reams", "4", "$24.00", "$96.00"]],"markdown": "| Item | Qty | Unit price | Amount |\n|---|---|-…","bbox": null,"confidence": null}]}],"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

text, html, csv, docx, xlsx

Markdown 응답과 함께 파일 데이터를 담은 output 객체(format, filename, mime_type, encoding, data)가 반환됩니다. text, html, csv는 UTF-8 문자열(encoding: "utf8")이며, docx와 xlsx는 base64(encoding: "base64")입니다. csv와 xlsx에는 표 데이터가 포함되며(표마다 시트 1개), 표가 없으면 텍스트 줄 단위로 포함됩니다. text 대신 txt도 사용할 수 있습니다.

200result
{"id": "req_8f2c1a41d0b3c7e9a2","model": "mistral/mistral-ocr","format": "docx","attempts": [{ "model": "mistral/mistral-ocr", "ok": true, "ms": 1180 }],"markdown": "<!-- page:1 -->\n# Invoice INV-2041\n…","pages": [{ "index": 1, "markdown": "# Invoice INV-2041\n…" }],"output": {"format": "docx","filename": "invoice.docx","mime_type": "application/vnd.openxmlformats-officedocument.w…","encoding": "base64","data": "UEsDBBQAAAAIA…"},"usage": {"pages": 1,"credits": 25,"latency_ms": 1180,"cached": false}}

라우팅 및 대체 모델

model을 auto로 설정하면 각 문서에 가장 적합한 모델을 자동으로 선택합니다. route를 통해 우선순위(cheapest, fastest, quality)를 지정하세요.

fallbacks를 지정해 두면 서비스 장애 시에도 중단 없이 처리를 이어갈 수 있습니다. 첫 번째 모델에서 오류가 발생하거나 요청 한도에 걸리면 다음 모델이 실행됩니다. 응답에 실제로 처리한 모델이 표시되며, 해당 모델의 비용만 청구됩니다.

{"model": "mistral/mistral-ocr","fallbacks": ["google/gemini-flash", "tesseract/tesseract"],"file_url": "https://example.com/report.pdf"}

크레딧

각 모델은 페이지당 크레딧으로 가격이 책정됩니다. $1로 1,000 크레딧을 구매할 수 있으며 유효기간은 없습니다. 모든 응답에는 usage.credits가 포함됩니다.

  • 실패하거나 내용이 빈 결과는 무료입니다.
  • 동일한 파일을 동일한 모델로 다시 요청하는 경우 캐시에서 무료로 제공됩니다.
  • 각 API 키마다 개별 크레딧 한도를 설정할 수 있습니다.

오류

400요청 형식이 잘못되었거나 지원하지 않는 파일 형식입니다.
401API 키가 누락되었거나 만료되었습니다.
402크레딧이 부족하거나 키의 크레딧 한도에 도달했습니다.
413해당 모델의 파일 크기 제한을 초과했습니다.
429요청 한도를 초과했습니다. Retry-After 헤더에 지정된 시간 이후에 다시 시도하세요.
502모든 대체 모델(fallback chain) 호출에 실패했습니다. 비용은 청구되지 않습니다.
503요청한 모델이 아직 연결되지 않았습니다.

에이전트, MCP 및 CLI

코딩 에이전트는 회원가입 없이도 OCRRouter를 바로 사용할 수 있습니다. CLI와 MCP 서버는 최초 실행 시 50 크레딧이 포함된 임시 키를 요청하여 ~/.ocrrouter/config.json에 저장합니다. 자체 키를 사용하려면 OCRROUTER_API_KEY를 설정하세요.

# CLI
npx ocrrouter invoice.pdf --format markdown

# MCP server for Claude Code
claude mcp add ocrrouter -- npx ocrrouter mcp

이 페이지의 머신 판독 가능(machine-readable) 요약본은 /llms.txt에서 확인할 수 있습니다.

자주 묻는 질문