OCR 识别 API 文档 - 数字先锋API文档

#OCR 识别 API 文档
---
推荐使用模型：qwen3-vl-plus、qwen3-vl-235b-a22b

---

## 1) 接口说明
使用多模态模型识别图片文字，返回按阅读顺序排列的纯文本结果。

- **Base URL**: `https://api.cxsee.com`
- **Endpoint**: `POST /v1/chat/completions`
- **Model**: `qwen3-vl-plus`
- **Content-Type**: `application/json`
- **Auth**: `Authorization: Bearer YOUR_API_KEY`

---

## 2) 请求参数

### Header
| 参数 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | `Bearer YOUR_API_KEY` |
| Content-Type | 是 | `application/json` |

### Body
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 固定：`qwen3-vl-plus` |
| messages | array | 是 | OpenAI 兼容消息格式 |
| temperature | number | 否 | 建议 `0`，输出稳定 |
| max_tokens | number | 否 | 结果较长时可设置，如 `2000` |

`messages[0].content` 中包含：
- 一段文本提示（约束只返回 OCR 文字）
- 一张图片 URL（公网可访问）

---

## 3) 请求示例（curl）

```bash
curl -sS -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-plus",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请做OCR识别。只输出图片中的文字，按自然阅读顺序逐行输出；不要坐标、不要置信度、不要解释。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://img.cxhao.com/images/5/2026/02/fVHMc8XJJmx1xaQNH8j4H4v1xVjE11.png"
            }
          }
        ]
      }
    ],
    "temperature": 0
  }'
```
对应解析图片
![](https://img.cxhao.com/images/5/2026/02/fVHMc8XJJmx1xaQNH8j4H4v1xVjE11.png)
输出结果如下
![](https://img.cxhao.com/2026/03/20260317042220700.png)

只取识别文本：
```bash
... | jq -r '.choices[0].message.content'
```

---

## 4) 响应示例

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "基本信息\n设置令牌的基本信息\n..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "model": "qwen3-vl-plus",
  "usage": {
    "prompt_tokens": 363,
    "completion_tokens": 261,
    "total_tokens": 624
  }
}
```

---

## 5) 错误码建议（对外约定）
> 平台原始错误可透传，这里是你对外网关建议统一格式。

| HTTP码 | code | 说明 |
|---|---|---|
| 400 | INVALID_REQUEST | 参数错误/图片URL无效 |
| 401 | UNAUTHORIZED | API Key 无效 |
| 403 | FORBIDDEN | 无模型权限 |
| 429 | RATE_LIMITED | 触发限流 |
| 500 | INTERNAL_ERROR | 服务内部异常 |
| 504 | TIMEOUT | 上游超时 |

建议返回结构：
```json
{
  "code": "INVALID_REQUEST",
  "message": "image_url is required",
  "request_id": "xxxx"
}
```

---

## 6) 最佳实践（给用户）
1. `temperature=0`，避免 OCR 文本抖动。
2. 图片需公网可访问、清晰、尽量正向。
3. 长图可分段识别再拼接。
4. 对账单/证件场景建议加业务后处理（字段提取、纠错）。
5. 不要在前端暴露 API Key，统一走服务端转发。

---

# Node.js 对接示例（开发者）

```js
import fetch from "node-fetch";

const apiKey = process.env.CXSEE_API_KEY;
const url = "https://api.cxsee.com/v1/chat/completions";

const body = {
  model: "qwen3-vl-plus",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "请做OCR识别。只输出图片中的文字，按自然阅读顺序逐行输出；不要坐标、不要置信度、不要解释。"
        },
        {
          type: "image_url",
          image_url: {
            url: "https://img.cxhao.com/images/5/2026/02/fVHMc8XJJmx1xaQNH8j4H4v1xVjE11.png"
          }
        }
      ]
    }
  ],
  temperature: 0
};

const resp = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(body)
});

const data = await resp.json();
console.log(data?.choices?.[0]?.message?.content || "");
```

---

上一篇：千问Qwen 对话（OpenAI 兼容）下一篇：兑换码充值使用指南