做图片编辑类需求时只拿到文字内容往往不够还需要知道每段文字在图片上的位置才能做盖字、换字、打码。OCR 文字坐标识别接口就是在返回文字的同时给出每条文字在原图上的像素坐标。本文从第一次调用讲起要准备什么、最小请求怎么发、返回值怎么看。一、适用场景图片编辑定位文字区域后覆盖、替换文案。打码脱敏按坐标对敏感文字区域做遮挡。版面分析拿到文字外接矩形后做简单的区域划分与排序。翻译叠加把译文渲染回原文字所在位置。需要先区分两个接口接口返回内容OCR 文字识别旧接口只返回文字OCR 文字坐标识别本接口文字 每条文字在原图上的像素坐标两者参数一致仍然是input_typeinput_data。如果你的业务只关心文字内容用旧接口即可需要定位才用本接口。二、接口能力边界与坐标系调用前先记住三条规则坐标系以原图左上角为(0,0)单位为像素。响应中的image.width/image.height是原图宽高画布尺寸必须按这两项对齐不要用你自己缩放后的尺寸。返回的坐标是外接矩形rect加上四点box前者便于快速裁剪后者便于处理倾斜文本。如果前端展示的图片做过缩放渲染前需要按原图宽高 / 展示宽高的比例换算坐标否则框会错位。三、请求参数与鉴权参数只有两个参数说明input_type输入类型具体可选值以文档为准input_data输入数据与input_type对应具体格式以文档为准鉴权方式、请求头字段名与请求体编码素材未给出以文档为准。接入前请先在文档中确认 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}, timeout10, ) 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四点做仿射变换把新文字贴合到原角度上。六、常见错误与排查现象可能原因排查方向鉴权失败API Key 缺失或位置错误核对请求头以文档为准参数错误input_type与input_data不匹配按文档确认取值与数据形式识别为空图片无文字、过小或格式不支持换清晰图片重试确认格式要求坐标错位用了缩放后的画布尺寸以image.width/image.height对齐超时图片过大或网络抖动设置超时必要时压缩图片注意识别结果为空通常不是接口错误而是图片本身没有可用文字不要把它当成异常无限重试。七、工程化注意事项画布基准前端渲染统一以原图宽高为基准缩放只作用于展示层。坐标换算所有裁剪、打码、渲染操作前先做一次比例换算并保留浮点精度。超时与重试只对超时和 5xx 做有限次重试空结果不重试。大图处理图片过大时先压缩再调用但压缩会改变坐标基准需要记录压缩比例并换算。结果缓存同一图片的识别结果可按内容哈希做短时缓存减少重复调用。隐私图片中可能含敏感信息日志中不要落原图与识别文本明文。参考文档接口文档