OCR API Reference

Complete reference for the OCR endpoint — request parameters, response schema, code examples, and supported options.

Endpoint

POST /api/v1/ocr

Scope required: ocr

Request

Headers

Header	Required	Description
`Authorization: Bearer <key>`	Yes*	API key with `ocr` scope
`x-api-key: <key>`	Yes*	Alternative to Bearer token
`Idempotency-Key`	No	Safe retry key (max 191 chars, alphanumeric + `._:-`)
`Content-Type`	Yes	`multipart/form-data` or `application/json`

*Exactly one authentication header required.

Input Source (choose one)

Field	Type	Source
`file`	Binary	File upload via multipart
`image_url`	String (URI)	Public HTTP/HTTPS URL
`base64`	String	Base64-encoded file content

When using base64, also provide mime_type (e.g., image/png, application/pdf).

Mode

Field	Type	Default	Values
`mode`	String	`formatted`	`simple`, `formatted`

simple — plain text output (lower cost, 1 credit/page)
formatted — Markdown with headings, tables, lists, code blocks preserved (10 credits/page)

Multipart Example

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "mode=formatted"

JSON Example

curl -X POST https://image-to-text.org/api/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/page.png", "mode": "simple"}'

Response

Success (200)

{
  "success": true,
  "request_id": "req_abc123...",
  "elapsed_ms": 2340,
  "data": {
    "markdown": "# Invoice\n\n| Item | Qty | Price |\n|------|-----|-------|\n...",
    "text": "Invoice\nItem Qty Price\n...",
    "pages": [
      {
        "pageNumber": 1,
        "markdown": "# Invoice\n\n...",
        "text": "Invoice\n...",
        "blocks": [
          {
            "type": "heading",
            "markdown": "# Invoice",
            "bbox": [72, 100, 540, 130],
            "confidence": 0.98
          },
          {
            "type": "table",
            "markdown": "| Item | Qty | Price |\n|------|-----|-------|",
            "bbox": [72, 200, 540, 400],
            "confidence": 0.95
          }
        ]
      }
    ],
    "usage": {
      "credits": 10,
      "pages": 1,
      "mode": "formatted"
    }
  }
}

Response Fields

Field	Type	Description
`success`	Boolean	Always `true` for successful requests
`request_id`	String	Unique identifier for this request
`elapsed_ms`	Integer	Processing time in milliseconds
`data.markdown`	String	Full document Markdown (all pages concatenated)
`data.text`	String	Plain text version of the document
`data.pages`	Array	Per-page results (see below)
`data.usage`	Object	Billing summary

Page Object

Field	Type	Description
`pageNumber`	Integer	1-based page index
`markdown`	String	Page Markdown content
`text`	String	Page plain text
`blocks`	Array	Recognized text blocks

Block Object

Field	Type	Description
`type`	String	`heading`, `paragraph`, `list`, `table`, `code`
`markdown`	String	Block content in Markdown
`bbox`	[Number]	`[x1, y1, x2, y2]` bounding box coordinates
`confidence`	Number	Recognition confidence (0–1)

Error Responses

All errors follow the standard error contract.

{
  "success": false,
  "request_id": "req_abc123...",
  "error": {
    "code": "empty_result",
    "message": "No readable text was found in this file.",
    "retryable": false
  }
}

Limits

Limit	Value
Max file size	20 MB
Max pages per request	Configurable (default ~50)
Supported image formats	JPEG, PNG, GIF, WebP, BMP, TIFF
Supported document format	PDF

Code Examples

Python

import requests

response = requests.post(
    "https://image-to-text.org/api/v1/ocr",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "ocr-2024-001",
    },
    json={
        "image_url": "https://example.com/document.png",
        "mode": "formatted",
    },
)

data = response.json()
if data["success"]:
    print(data["data"]["markdown"])
else:
    print(f"Error: {data['error']['message']}")

Node.js

const response = await fetch("https://image-to-text.org/api/v1/ocr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image_url: "https://example.com/document.png",
    mode: "formatted",
  }),
});

const data = await response.json();
if (data.success) {
  console.log(data.data.markdown);
}

OCR API Reference

On this page