> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# deepseek-ai/deepseek-ocr-2

> Document OCR to Markdown with text grounding from DeepSeek.

Generative document OCR (vLLM). Accepts one `image_url` or a `document_url` PDF;
no text-only input. Default method: `markdown`. Three methods return the page as
a string; `grounding_ocr` instead locates a phrase and returns region boxes.

## Output by method

| Method          | Payload kind | Image `content.object`                 | Payload                                                                                  |
| --------------- | ------------ | -------------------------------------- | ---------------------------------------------------------------------------------------- |
| `markdown`      | markdown     | none                                   | Reading-order Markdown string (default)                                                  |
| `ocr`           | markdown     | none                                   | Markdown via the grounded conversion prompt; grounding tags are stripped from the output |
| `free_ocr`      | markdown     | none                                   | Free-form plain read of the page                                                         |
| `grounding_ocr` | json         | `deepseek_ocr_2.grounding_ocr.regions` | Region items with `bbox_xywh` and the matched `text`                                     |

Text mode emits the string alone for one image, and one `<document>` / `<page>`
block per PDF page. In JSON mode an image `content` is the string, or the region
container for `grounding_ocr`, and a document page `content` is always
`document.page.blocks`. See [Methods & Response Format](/gateway/methods).

The model grounds on a fixed 0-1000 grid; the Gateway normalizes every box to
0-1 against the image or rasterized page, at `precision` decimals (default 4).
Grounding regions carry `bbox_xywh` and `text` only: no polygon and no score.

## Request

<CodeGroup>
  ```python Python [expandable] theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://gateway.vlm.run/v1/openai",
      api_key="<VLMRUN_API_KEY>",
  )

  response = client.chat.completions.create(
      model="deepseek-ai/deepseek-ocr-2",
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "document_url",
                      "document_url": {
                          "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/finance.sec-filings/tsla-8k.pdf"
                      },
                  },
              ],
          }
      ],
      extra_body={"method": "markdown"},
  )

  print(response.choices[0].message.content)
  ```

  ```bash cURL [expandable] theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  curl https://gateway.vlm.run/v1/openai/chat/completions \
    -X POST \
    -H "Authorization: Bearer $VLMRUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek-ai/deepseek-ocr-2",
      "method": "markdown",
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "document_url",
              "document_url": {
                "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/finance.sec-filings/tsla-8k.pdf"
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

## Response

<Tabs>
  <Tab title="Text mode">
    One `<document>` block per PDF, one `<page>` block per page, each carrying
    `format="markdown"`:

    ```text theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    <document file_name="tsla-8k.pdf" file_hash="sha256:1b7f…" file_bytes="182417" mimetype="application/pdf" num_pages="2" dpi="96">
    <page page_index="0" format="markdown" page_width="1700" page_height="2200">
    # Annual Report 2024

    ## Overview

    The company reported revenue of $1.2M.
    </page>
    <page page_index="1" format="markdown" page_width="1700" page_height="2200">
    | Metric | 2023 | 2024 |
    | --- | --- | --- |
    | Revenue | 0.9M | 1.2M |
    </page>
    </document>
    ```

    A single image returns the Markdown string alone, with no wrapper.
  </Tab>

  <Tab title="JSON mode">
    One document entry; each page's `content` is one Markdown block:

    ```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    {
      "model": "deepseek-ai/DeepSeek-OCR-2",
      "method": "markdown",
      "data": [
        {
          "object": "document",
          "file_name": "tsla-8k.pdf",
          "file_hash": "sha256:1b7f...",
          "file_bytes": 182417,
          "mimetype": "application/pdf",
          "num_pages": 2,
          "dpi": 96,
          "pages": [
            {
              "object": "document.page",
              "page_index": 0,
              "page_width": 1700,
              "page_height": 2200,
              "content": {
                "object": "document.page.blocks",
                "items": [
                  {"index": 0, "text": "# Annual Report 2024\n\n## Overview\n\nThe company reported revenue of $1.2M."}
                ]
              }
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Grounding

`grounding_ocr` answers "where does this appear on the page". Pass the full
grounding prompt via `method_params.prompt`, with the phrase to locate wrapped
in the model's ref markers:

```python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
response = client.chat.completions.create(
    model="deepseek-ai/deepseek-ocr-2",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.receipt/playground/2.jpg"
                    },
                },
            ],
        }
    ],
    extra_body={
        "method": "grounding_ocr",
        "method_params": {"prompt": "<image>\nLocate <|ref|>Total Amount<|/ref|> in the image."},
    },
)
```

The reply is the region container, alone in text mode and wrapped in `data` in
JSON mode:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{"object": "deepseek_ocr_2.grounding_ocr.regions", "items": [{"bbox_xywh": [0.102, 0.08, 0.893, 0.06], "text": "Annual Report 2024"}, {"bbox_xywh": [0.102, 0.16, 0.893, 0.08], "text": "Overview"}]}
```

On a PDF each page's `content` is `document.page.blocks`, with one block per
located region carrying the same `bbox_xywh` and `text`.

## Aliases

`deepseek-ai/deepseek-ocr-2` (preferred), `deepseek-ocr-2`, and
[`deepseek-ai/DeepSeek-OCR-2`](https://huggingface.co/deepseek-ai/DeepSeek-OCR-2)
all resolve to this model.