OCR output formats: JSON, text, Markdown, hOCR and searchable PDF
Every format is a view of the same result: fetch the finished job as json, text, md or hocr, as often as you like, in any order. Which pipeline delivers what?
curl -s "https://api.ocr-software.com/v1/jobs/$JOB_ID/result?format=md" -H "Authorization: Bearer $OCR_KEY"
$JOB_ID comes from the answer to POST /v1/jobs; the whole way from key to result is in the API guide. A page that could not be read is an empty page in text and md; the header X-Pages-Failed on the answer tells you how many.
Which OCR output format for which job
| I want to | Use |
|---|---|
| feed a language model or a search index | md or text |
| keep every word with its place | json |
| archive with selectable text | pdf |
| load into a library tool | hocr |
OCR to JSON: every word with box and confidence
Everything per page: words with box, lines, confidence and origin, as far as the pipeline delivers them.
Strength: The most complete format. The right choice for programs, archives and agents.
Size: Larger than the other formats, made for programs.
Read more: OCR to JSON with bounding boxes: every word, place and confidence
OCR to plain text in reading order
The words in reading order, nothing else.
Strength: Small, no structure, readable in any tool.
Content: The words in reading order; markers for headings and lists are dropped.
OCR to Markdown for language models and RAG
One section per page, headings and lists taken from the markup.
Strength: Good for language models, wikis and notes. People read it without a tool.
Tables: Tables as tables with scan-ctc-tables@2 and scan-vlm-ctc@2; with the other pipelines the cell content stands as text.
hOCR output: HTML with line or word boxes
HTML with a box for every line or word and the confidence value.
Strength: Many archive tools read hOCR already.
Detail: Word boxes with scan-ctc@2 and scan-vlm-ctc@2, otherwise per line. scan-ctc@2 and scan-vlm-ctc@2 give a confidence for every word.
Searchable PDF: your original with a text layer
Your original with an invisible text layer that you can search and copy.
Strength: The image stays as it was. A PDF opens in every common viewer.
Call: You send the original again when you fetch it. A text layer with word boxes with scan-ctc@2 and scan-vlm-ctc@2, otherwise per line. Pages that were not read are noted in the head of the answer.
Read more: Make a scanned PDF searchable: your original, plus a text layer
Call it with the job id and your original:
curl -X POST "https://api.ocr-software.com/v1/jobs/$JOB_ID/result?format=pdf" \
-H "Authorization: Bearer $OCR_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @scan.pdf \
-o scan.searchable.pdf
The call needs the original again: send the same document as in the job. If its page count or page size differs, the answer is 422 source_mismatch (a page-count and page-size check). Pages that were not read carry a visible strip, and their numbers are in the header X-Pages-Unread. All result calls