DeepSeek-OCR 图像识别 API 文档

本接口提供基于 DeepSeek-OCR 模型的图像文字识别（OCR）功能。该 API 采用与 OpenAI 兼容的聊天补全（Chat Completions）格式，支持通过 URL 或 Base64 编码上传图片并转换为文本或 Markdown 格式。

服务域名: https://api.codingplanx.ai
接口路径: /v1/chat/completions
请求方法: POST
接口状态: 已发布 (Released)

1. 请求参数

1.1 请求头 (Headers)

参数名	必选	类型	示例值	说明
Content-Type	是	String	`application/json`	请求体格式
Accept	是	String	`application/json`	响应体格式
Authorization	是	String	`Bearer YOUR_API_KEY`	用于身份验证的 API Key

1.2 请求体 (Request Body)

参数名	必选	类型	说明
model	是	String	使用的模型 ID，OCR 识别请指定为 `deepseek-ocr`
messages	是	Array	包含对话消息的列表。对于 OCR，需在消息中包含图片信息。
stream	否	Boolean	默认为 `false`。若为 `true`，将流式返回响应内容。
temperature	否	Number	采样温度 (0-2)。较低值更集中稳定，较高值更随机。
top_p	否	Number	核采样概率阈值。
max_tokens	否	Integer	生成的最大 Token 数。
response_format	否	Object	指定返回格式，例如 `{"type": "json_object"}` 开启 JSON 模式。
tools	否	Array	模型可调用的工具列表（目前主要支持函数调用）。

2. 请求示例

2.1 OCR 图像识别请求 (JSON)

{
  "model": "deepseek-ocr",
  "stream": false,
  "messages": [
    {
      "role": "system",
      "content": "<image>\r
Free OCR."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://s3.ffire.cc/files/pdf_to_markdown.jpg" 
          }
        }
      ]
    }
  ]
}

注意: image_url.url 字段支持直接传入图片的公共 URL，或传入 Base64 编码的数据字符串（格式如：data:image/jpeg;base64,...）。

3. 响应说明

3.1 响应体结构

字段	类型	说明
id	String	该请求的唯一标识符。
object	String	对象类型，通常为 `chat.completion`。
created	Integer	Unix 时间戳（秒）。
choices	Array	包含生成的多个选项。
└─ message	Object	模型返回的消息内容，包含 `role` 和 `content`。
└─ finish_reason	String	停止原因（如 `stop` 或 `length`）。
usage	Object	Token 使用统计，包含提示、补全及总计 Token。

3.2 响应示例

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "这里是 OCR 识别出的文字内容，通常以 Markdown 格式返回图片中的排版信息。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 512,
        "completion_tokens": 128,
        "total_tokens": 640
    }
}

4. FAQs (常见问题)

Q1: DeepSeek-OCR 支持哪些图片格式？ A: 目前主流的图片格式如 JPEG, PNG, WebP, BMP 均支持。建议图片清晰且分辨率适中，以保证识别准确率。

Q2: 如何使用 Base64 上传图片？ A: 将 image_url.url 的值替换为 Base64 字符串即可。格式示例："url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."。

Q3: 为什么识别结果会被切断？ A: 请检查响应中的 finish_reason。如果为 length，说明生成的内容超过了 max_tokens 的限制，建议调大 max_tokens 参数。

Q4: 这个接口支持批量识别图片吗？ A: 在单次请求的 messages 中，您可以尝试添加多个 image_url 对象，但建议对每张图片进行单独调用，以获得最佳的上下文处理和更稳定的响应。

Q5: 如何获得更精准的排版（如表格或公式）？ A: 可以在 system 或 user 消息中增加提示词，例如：“请使用 Markdown 格式保留图片中的表格布局并识别其中的数学公式”。

Q6: 是否支持流式输出 (Streaming)？ A: 支持。将请求参数中的 stream 设置为 true，模型会实时返回识别出的文字片段，适用于需要降低首字延迟的实时交互场景。