<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# OCR 文字识别

> 通用 OCR 文字识别，从图片中提取任意文字内容（中文/英文/数字/符号/手写体等），返回逐行文本列表 + 完整拼接文本。

• 双输入模式：
  - input_type=url：传入公网可访问的图片 URL（http/https）
  - input_type=base64：传入 base64 编码字符串（≤6MB，自动剥离 data:image/...;base64, 前缀）

• 三路输出：
  - text_list：按原图顺序的逐行文本数组
  - full_text：用换行符 \n 拼接的完整文本字符串
  - text_count：识别到的文本行数

• 适用场景：截图转文字、表格识别、身份证/名片文字提取、字幕识别、笔记 OCR 等通用场景。专用发票识别请用 /api/invoice。

• OCR 结果缓存 1 小时（同图同结果），重复调用不消耗上游配额。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `ocr-text` |
| 接口名称 | OCR 文字识别 |
| 接口地址 | `https://v1.apizero.cn/api/ocr-text` |
| 请求方法 | `POST` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 2 req/s |
| 每日免费额度 | 30 次（已认证用户） |
| 匿名每日额度 | 5 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 5 次、QPS 1；登录用户每日 30 次、QPS 2（全部免费）。OCR 结果缓存 1 小时，相同图片只实际调用上游一次。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `input_type` | `string` | 是 | 输入类型：url=图片URL / base64=图片base64编码 | `url` |
| `input_data` | `string` | 是 | 图片数据。input_type=url 时为 http/https 完整 URL；input_type=base64 时为 base64 字符串（最大 6MB，可选 data:image/jpeg;base64, 前缀） | `https://dummyimage.com/400x100/000/fff.png&text=Hello+World` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 5 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |
| `Content-Type` | `string` | 是 | POST 请求体类型，固定 application/x-www-form-urlencoded | `application/x-www-form-urlencoded` |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/ocr-text" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_type": "url",
  "input_data": "https://dummyimage.com/400x100/000/fff.png&text=Hello+World"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `input_type` | `string` | 回传输入类型（url 或 base64） | — |
| `text_count` | `number` | 识别到的文本行数 | — |
| `text_list` | `array` | 按原图顺序的逐行文本数组（字符串数组） | — |
| `full_text` | `string` | 用换行符 \n 拼接的完整文本字符串，便于前端直接展示 | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "input_type": "url",
        "text_count": 3,
        "text_list": [
            "商品名称：无线蓝牙耳机",
            "单价：¥299.00",
            "数量：2"
        ],
        "full_text": "商品名称：无线蓝牙耳机\n单价：¥299.00\n数量：2"
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：input_type/input_data 缺失或非法 / URL 格式错 / base64 含非法字符 / base64 超过 6MB |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 识别失败：图片模糊 / URL 不可达 / 上游服务异常 |

## 9. 变更日志

- **1.0.0** (2026-05-06)
  - 首次上线，对接 alapi.cn /api/ocr/text 通用 OCR 服务
  - 双输入模式：URL 直接抓取 / base64 直传
  - base64 模式自动剥离 data:image/...;base64, 前缀
  - base64 上限 6MB，防止 OOM；URL 模式强制 http/https，防 SSRF
  - OCR 结果缓存 1h（按 sha256 哈希），相同图片不重复调用付费上游
  - 兼容 text_list 两种形式：纯字符串数组 / 含 text 字段的对象数组
  - 额外输出 full_text（换行拼接）+ text_count（行数），便于前端直接使用
  - token 异常转为通用 5021 错误，不暴露内部配置

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/ocr-text`

Source: `https://apizero.cn/aidocs/ocr-text/raw.md`
Last updated: 2026-05-12T14:34:06+08:00