OCR 文字坐标识别接口接入教程：参数、请求示例与坐标字段解读

做图片编辑类需求时，只拿到文字内容往往不够，还需要知道每段文字在图片上的位置，才能做盖字、换字、打码。OCR 文字坐标识别接口就是在返回文字的同时，给出每条文字在原图上的像素坐标。本文从第一次调用讲起：要准备什么、最小请求怎么发、返回值怎么看。

一、适用场景

• 图片编辑：定位文字区域后覆盖、替换文案。
• 打码脱敏：按坐标对敏感文字区域做遮挡。
• 版面分析：拿到文字外接矩形后做简单的区域划分与排序。
• 翻译叠加：把译文渲染回原文字所在位置。

需要先区分两个接口：

两者参数一致，仍然是input_type+input_data。如果你的业务只关心文字内容，用旧接口即可；需要定位才用本接口。

二、接口能力边界与坐标系

调用前先记住三条规则：

1. 坐标系以原图左上角为(0,0)，单位为像素。
2. 响应中的image.width/image.height是原图宽高，画布尺寸必须按这两项对齐，不要用你自己缩放后的尺寸。
3. 返回的坐标是外接矩形rect加上四点box，前者便于快速裁剪，后者便于处理倾斜文本。

如果前端展示的图片做过缩放，渲染前需要按原图宽高 / 展示宽高的比例换算坐标，否则框会错位。

三、请求参数与鉴权

参数只有两个：

鉴权方式、请求头字段名与请求体编码，素材未给出，以文档为准。接入前请先在文档中确认 API Key 的传递位置。

四、最小请求示例

下面是一个可复制的 curl 模板，YOUR_API_KEY、input_type的取值与input_data的内容都是占位，请按文档替换。

curl -X POST 'https://v1.apizero.cn/api/ocr-text-box' \ -H 'Content-Type: application/json' \ -H 'Authorization: YOUR_API_KEY' \ -d '{ "input_type": "<按文档填写>", "input_data": "<图片地址或 Base64，按 input_type 决定>" }'

如果文档要求表单提交，可改为：

curl -X POST 'https://v1.apizero.cn/api/ocr-text-box' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: YOUR_API_KEY' \ --data-urlencode 'input_type=<按文档填写>' \ --data-urlencode 'input_data=<按 input_type 传入对应数据>'

调用前建议先做本地校验：图片能正常打开、尺寸不为 0、input_type与input_data形式匹配。

五、返回值解读

素材给出的关键返回字段是rect、box、image.width、image.height，其余字段名以文档为准。理解方式如下：

• image.width/image.height：原图像素宽高，是画布与坐标换算的基准。
• rect：每条文字的外接矩形，通常由左上角与宽高或对角点表示，适合直接裁剪与打码。
• box：每条文字的四点坐标，适合倾斜文本，也便于做透视变换后再渲染。

一个防御式解析示例（字段名请按文档实际返回替换）：

import requests def ocr_boxes(input_type: str, input_data: str, api_key: str) -> list: resp = requests.post( "https://v1.apizero.cn/api/ocr-text-box", headers={"Authorization": api_key}, json={"input_type": input_type, "input_data": input_data}, timeout=10, ) resp.raise_for_status() data = resp.json() image = data.get("image") or {} width, height = image.get("width"), image.get("height") if not width or not height: return [] results = [] for item in data.get("items", []): # 数组字段名以文档为准 rect = item.get("rect") box = item.get("box") if not rect and not box: continue results.append({ "text": item.get("text", ""), # 文字字段名以文档为准 "rect": rect, "box": box, }) return results

拿到坐标后，打码的常见做法是用rect直接填充实色矩形；换字的做法是把box四点做仿射变换，把新文字贴合到原角度上。

六、常见错误与排查

注意：识别结果为空通常不是接口错误，而是图片本身没有可用文字，不要把它当成异常无限重试。

七、工程化注意事项

• 画布基准：前端渲染统一以原图宽高为基准，缩放只作用于展示层。
• 坐标换算：所有裁剪、打码、渲染操作前先做一次比例换算，并保留浮点精度。
• 超时与重试：只对超时和 5xx 做有限次重试，空结果不重试。
• 大图处理：图片过大时先压缩再调用，但压缩会改变坐标基准，需要记录压缩比例并换算。
• 结果缓存：同一图片的识别结果可按内容哈希做短时缓存，减少重复调用。
• 隐私：图片中可能含敏感信息，日志中不要落原图与识别文本明文。

参考文档

• 接口文档