# OCR

识别 PDF、Word、PowerPoint 文档或图片中的文字，按页返回识别结果。文件不会存入 Files API。限制、错误与计费见 [OCR 指南](https://api-docs.deepseek.com/zh-cn/guides/ocr.md)。

## 接口

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

operationId: `ocr`

### 服务地址

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

## 身份验证

### 验证方式 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

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

## 请求体

**必填**

### multipart/form-data

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

## 响应

### 200

OK, 返回每一页的识别结果。

#### application/json

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

**示例**

```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\nDeepSeek API 使用与 OpenAI、Anthropic 兼容的 API 格式。",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 1536,
    "output_tokens": 412,
    "total_tokens": 1948
  }
}
```

## 代码示例

### 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"])
```

## 引用的数据结构

### schema-ocr-request

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

- `type`: `object`

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

- **字段**

  - **`file`** (必填)

    要识别的文件，需带文件名。支持的格式与限制见 [OCR 指南](https://api-docs.deepseek.com/zh-cn/guides/ocr.md)。

    - `type`: `string`

    - `format`: `binary`

  - **`purpose`** (必填)

    `text_recognition`：不含图片的 Word、PowerPoint 直接提取文字，其他文件逐页识别；`rich_layout_recognition`：所有文件都逐页识别。输出见 [OCR 指南](https://api-docs.deepseek.com/zh-cn/guides/ocr.md#response)。

    - `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"]`

- **字段**

  - **`id`** (必填)

    本次识别的 ID，形如 `ocr-...`。

    - `type`: `string`

  - **`object`** (必填)

    对象类型，固定为 `ocr.result`。

    - `type`: `string`

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

  - **`created`** (必填)

    识别创建时的 Unix 时间戳（秒）。

    - `type`: `integer`

  - **`purpose`** (必填)

    请求中的 `purpose`。

    - `type`: `string`

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

  - **`page_count`** (必填)

    页数，等于 `pages` 的长度。

    - `type`: `integer`

  - **`pages`** (必填)

    每一页的识别结果，按页序排列。

    - `type`: `array`

    - **数组元素**

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

  - **`usage`** (必填)

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

### schema-ocr-page

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

- `type`: `object`

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

- **字段**

  - **`index`** (必填)

    页码，从 0 开始。

    - `type`: `integer`

  - **`text`** (必填)

    该页的模型原始输出，不做任何清理。

    - `type`: `string`

  - **`finish_reason`** (必填)

    `stop` 表示该页完整识别；`length` 表示输出达到上限，该页文本不完整。

    - `type`: `string`

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

### schema-ocr-usage

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

所有页的 Token 用量，仅供参考，不用于计费。

- `type`: `object`

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

- **字段**

  - **`input_tokens`** (必填)

    所有页的 OCR 输入 Token，仅供参考，不用于计费。

    - `type`: `integer`

  - **`output_tokens`** (必填)

    所有页的 OCR 输出 Token，仅供参考，不用于计费。

    - `type`: `integer`

  - **`total_tokens`** (必填)

    `input_tokens` 与 `output_tokens` 之和。

    - `type`: `integer`