# OCR

Recognize the text in a PDF, Word or PowerPoint document or in an image, and return the result page by page. The file is not stored in the Files API. See the [OCR guide](https://api-docs.deepseek.com/guides/ocr.md) for the limits, errors and billing.

## Endpoint

```http
POST /v1/tools/ocr
```

operationId: `ocr`

### Servers

- `https://api.deepseek.com`

## Authentication

### Alternative 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## Request body

**required**

### multipart/form-data

- Reference: [OcrRequest](#schema-ocr-request) (`#/components/schemas/OcrRequest`)

## Responses

### 200

OK, returns the recognition result of every page.

#### application/json

- Reference: [OcrResponse](#schema-ocr-response) (`#/components/schemas/OcrResponse`)

**Example**

```json
{
  "id": "ocr-9b2f4c1e-5d7a-4e3b-8f21-6c0a9d4e7b12",
  "object": "ocr.result",
  "created": 1762790000,
  "purpose": "text_recognition",
  "page_count": 1,
  "pages": [
    {
      "index": 0,
      "text": "DeepSeek API\n\nThe DeepSeek API uses an API format compatible with OpenAI and Anthropic.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 1536,
    "output_tokens": 412,
    "total_tokens": 1948
  }
}
```

## Code samples

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
curl --silent --show-error --max-time 300 "https://api.deepseek.com/v1/tools/ocr" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  --form "purpose=text_recognition" \
  --form "file=@document.pdf"
```

### Python — requests

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
import os
import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://api.deepseek.com/v1/tools/ocr",
        headers={"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"},
        data={"purpose": "text_recognition"},
        files={"file": f},
        timeout=300,
    )
response.raise_for_status()
result = response.json()
if "error" in result:
    raise RuntimeError(result["error"]["message"])
for page in result["pages"]:
    print(page["index"], page["text"])
```

## Referenced schemas

### schema-ocr-request

**OcrRequest** — `#/components/schemas/OcrRequest`

- `type`: `object`

- `required`: `["file","purpose"]`

- **Properties**

  - **`file`** (required)

    The file to recognize, sent with a file name. See the [OCR guide](https://api-docs.deepseek.com/guides/ocr.md) for the supported formats and limits.

    - `type`: `string`

    - `format`: `binary`

  - **`purpose`** (required)

    `text_recognition` extracts text directly from Word and PowerPoint files without images and recognizes other files page by page. `rich_layout_recognition` recognizes every file page by page. See the [OCR guide](https://api-docs.deepseek.com/guides/ocr.md#response) for the output.

    - `type`: `string`

    - `enum`: `["text_recognition","rich_layout_recognition"]`

### schema-ocr-response

**OcrResponse** — `#/components/schemas/OcrResponse`

- `type`: `object`

- `required`: `["id","object","created","purpose","page_count","pages","usage"]`

- **Properties**

  - **`id`** (required)

    The recognition ID, of the form `ocr-...`.

    - `type`: `string`

  - **`object`** (required)

    The object type, which is always `ocr.result`.

    - `type`: `string`

    - `enum`: `["ocr.result"]`

  - **`created`** (required)

    The Unix timestamp (in seconds) of when the recognition was created.

    - `type`: `integer`

  - **`purpose`** (required)

    The `purpose` of the request.

    - `type`: `string`

    - `enum`: `["text_recognition","rich_layout_recognition"]`

  - **`page_count`** (required)

    The number of pages, equal to the length of `pages`.

    - `type`: `integer`

  - **`pages`** (required)

    The recognition result of every page, in page order.

    - `type`: `array`

    - **Array items**

      - Reference: [OcrPage](#schema-ocr-page) (`#/components/schemas/OcrPage`)

  - **`usage`** (required)

    - Reference: [OcrUsage](#schema-ocr-usage) (`#/components/schemas/OcrUsage`)

### schema-ocr-page

**OcrPage** — `#/components/schemas/OcrPage`

- `type`: `object`

- `required`: `["index","text","finish_reason"]`

- **Properties**

  - **`index`** (required)

    The page number, starting from 0.

    - `type`: `integer`

  - **`text`** (required)

    The raw model output for the page, without any cleanup.

    - `type`: `string`

  - **`finish_reason`** (required)

    `stop` when the page was recognized completely; `length` when the output reached the limit and the page text is incomplete.

    - `type`: `string`

    - `enum`: `["stop","length"]`

### schema-ocr-usage

**OcrUsage** — `#/components/schemas/OcrUsage`

The token usage of all pages. For reference only; not used for billing.

- `type`: `object`

- `required`: `["input_tokens","output_tokens","total_tokens"]`

- **Properties**

  - **`input_tokens`** (required)

    The OCR input tokens of all pages. For reference only; not used for billing.

    - `type`: `integer`

  - **`output_tokens`** (required)

    The OCR output tokens of all pages. For reference only; not used for billing.

    - `type`: `integer`

  - **`total_tokens`** (required)

    The sum of `input_tokens` and `output_tokens`.

    - `type`: `integer`