PennyOCR

https://pennyocr.com/docs
Admin
PennyOCR is an optical character recognition API that converts documents and images into structured...
Tokens:2,635
Snippets:14
Trust Score:4.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### POST /v1/ocr response

Source: https://pennyocr.com/docs

Example JSON response from POST /v1/ocr. Shows the document ID, page count, full text with page breaks, per-page results, cost in USD, and model name.

```json
{
  "id": "ocr_ab12cd34",
  "pages": 3,
  "text": "…full document (pages joined by \f)…",
  "page_results": [{ "page": 1, "text": "…" }],
  "cost_usd": 0.00225,
  "model": "nuextract3"
}
```

--------------------------------

### GET /health

Source: https://pennyocr.com/docs

Check the health of the PennyOCR engine and model status. No authentication required.

```APIDOC
## GET /health

### Description
Check the health of the PennyOCR engine and model status. No authentication required.

### Method
GET

### Endpoint
https://api.pennyocr.com/health

### Authentication
None

### Response
#### Success Response (200)
Health status information.
```

--------------------------------

### POST /v1/chat/completions

Source: https://pennyocr.com/docs

OpenAI-compatible chat completions endpoint. Accepts image_url content parts (data: or https URLs) with model `pennyocr-markdown` or `pennyocr-text`. Works with any OpenAI SDK by changing base_url.

```APIDOC
## POST /v1/chat/completions

### Description
OpenAI-compatible chat completions endpoint. Accepts image_url content parts (data: or https URLs) with model `pennyocr-markdown` or `pennyocr-text`. Works with any OpenAI SDK by changing base_url.

### Method
POST

### Endpoint
https://api.pennyocr.com/v1/chat/completions

### Authentication
Authorization: Bearer pk_live_… (API key from dashboard)

### Parameters
#### Request Body (JSON)
- **model** (string) - Required - Model to use: `pennyocr-markdown` or `pennyocr-text`.
- **messages** (array) - Required - Chat messages, with content parts including `image_url` (data: or https URLs).

### Request Example
```json
{
  "model": "pennyocr-markdown",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,..."
          }
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
OpenAI-compatible chat completion response.
```

--------------------------------

### POST /v1/ocr with curl

Source: https://pennyocr.com/docs

Send a document to the PennyOCR API with curl. Requires a PENNYOCR_API_KEY environment variable. The response is the OCR result; the comment notes the pricing.

```bash
curl https://api.pennyocr.com/v1/ocr \
  -H "Authorization: Bearer $PENNYOCR_API_KEY" \
  -F "file=@receipt.jpg"

# $0.75 per 1,000 pages, first 100 free
```

--------------------------------

### POST /v1/estimate

Source: https://pennyocr.com/docs

Estimate the page count and cost for a document at a given URL. This endpoint is free and does not perform OCR.

```APIDOC
## POST /v1/estimate

### Description
Estimate the page count and cost for a document at a given URL. This endpoint is free and does not perform OCR.

### Method
POST

### Endpoint
https://api.pennyocr.com/v1/estimate

### Authentication
Authorization: Bearer pk_live_… (API key from dashboard)

### Parameters
#### Request Body (JSON)
- **url** (string) - Required - URL of the document.
- **pages** (string) - Optional - Page range, e.g., `1-20,25`.

### Request Example
```json
{
  "url": "https://example.com/document.pdf",
  "pages": "1-20"
}
```

### Response
#### Success Response (200)
- **page_count** (integer) - Number of pages.
- **cost_usd** (number) - Estimated cost in USD.
```

--------------------------------

### POST /v1/ocr

Source: https://pennyocr.com/docs

Upload a document and receive its text contents. Supports PDF, PNG, JPEG, WebP, or TIFF files up to 50 MB and 500 pages. Returns structured markdown or plain text.

```APIDOC
## POST /v1/ocr

### Description
Upload a document and receive its text contents. Supports PDF, PNG, JPEG, WebP, or TIFF files up to 50 MB and 500 pages. Returns structured markdown or plain text.

### Method
POST

### Endpoint
https://api.pennyocr.com/v1/ocr

### Authentication
Authorization: Bearer pk_live_… (API key from dashboard)

### Parameters
#### Request Body (multipart/form-data)
- **file** (file) - Required - The document file to OCR. Supported formats: PDF, PNG, JPEG, WebP, TIFF. Max 50 MB and 500 pages.

#### Query Parameters
- **format** (string) - Optional - Output format: `markdown` (default) or `text`.

### Request Example
```
curl https://api.pennyocr.com/v1/ocr \
  -H "Authorization: Bearer $PENNYOCR_API_KEY" \
  -F "file=@receipt.jpg"
```

### Response
#### Success Response (200)
- **id** (string) - OCR request ID.
- **pages** (integer) - Number of pages processed.
- **text** (string) - Full document text, pages joined by form feed (\f).
- **page_results** (array) - Array of per-page results, each with `page` (integer) and `text` (string).
- **cost_usd** (number) - Cost of the request in USD.
- **model** (string) - Model used (e.g., `nuextract3`).

#### Response Example
```
{
  "id": "ocr_ab12cd34",
  "pages": 3,
  "text": "…full document (pages joined by \f)…",
  "page_results": [{ "page": 1, "text": "…" }],
  "cost_usd": 0.00225,
  "model": "nuextract3"
}
```

### Errors
- **401** - Bad key.
- **402** - Free tier and credits exhausted.
- **413** - Too big.
- **422** - Unreadable file or bad format param.
- **429** - Slow down.
```

--------------------------------

### POST /v1/ocr/url

Source: https://pennyocr.com/docs

Submit a URL to a document for OCR. The service fetches the document and processes it. Supports page ranges and cost caps.

```APIDOC
## POST /v1/ocr/url

### Description
Submit a URL to a document for OCR. The service fetches the document and processes it. Supports page ranges and cost caps.

### Method
POST

### Endpoint
https://api.pennyocr.com/v1/ocr/url

### Authentication
Authorization: Bearer pk_live_… (API key from dashboard)

### Parameters
#### Request Body (JSON)
- **url** (string) - Required - URL of the document to fetch.
- **format** (string) - Optional - Output format: `markdown` (default) or `text`.
- **pages** (string) - Optional - Page range, e.g., `1-20,25`.
- **max_pages** (integer) - Optional - Maximum number of pages to process.
- **max_cost_usd** (number) - Optional - Maximum cost in USD; if exceeded, request is refused with a 413 error.

### Request Example
```json
{
  "url": "https://example.com/document.pdf",
  "format": "markdown",
  "pages": "1-20,25",
  "max_pages": 20,
  "max_cost_usd": 0.10
}
```

### Response
#### Success Response (200)
Same response structure as POST /v1/ocr.

### Errors
- **413** - Request exceeds caps (deterministic, with exact numbers).
```
Tokens:
Raw