GLM-OCR API接口详解：参数、返回值与错误码全解析

GLM-OCR API接口详解参数、返回值与错误码全解析如果你正在开发一个需要识别图片中文字的应用比如自动录入票据信息、识别商品包装上的文字或者从截图里提取关键内容那么直接调用一个成熟的OCR服务接口无疑是最高效、最可靠的选择。今天我们就来深入聊聊GLM-OCR的API接口我会把每个参数、每项返回值、以及可能遇到的错误码都掰开揉碎了讲清楚让你看完就能上手集成。GLM-OCR的API设计得很简洁核心就是一个HTTP POST请求。你只需要把图片传过去它就能把识别出的文字、位置等信息结构清晰地返回给你。听起来简单但要想用得好、用得稳还得了解其中的一些门道。1. 快速上手你的第一个API调用在深入细节之前我们先跑通一个最简单的例子让你对整个过程有个直观的感受。这里我用Python的requests库来演示因为它足够通用和清晰。首先你需要准备好两样东西API访问凭证通常是一个API Key用于验证你的身份。你需要在GLM-OCR的服务平台上申请获取。待识别的图片一张包含清晰文字的图片文件。假设你的图片叫invoice.jpg下面就是调用代码import requests import json # 替换成你从控制台获取的真实API Key API_KEY your_api_key_here # GLM-OCR的API端点地址 API_URL https://api.example.com/v1/ocr # 示例地址请以官方文档为准 # 准备请求头通常需要包含认证信息和内容类型 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, # 或者根据要求使用 multipart/form-data } # 准备请求体。这里演示以图片Base64编码的方式传递 with open(invoice.jpg, rb) as image_file: image_data image_file.read() import base64 image_base64 base64.b64encode(image_data).decode(utf-8) payload { image: image_base64, # 可以在这里添加其他可选参数比如指定语言 # language: zh } # 发送POST请求 response requests.post(API_URL, headersheaders, jsonpayload) # 检查请求是否成功 if response.status_code 200: result response.json() print(识别成功) print(json.dumps(result, indent2, ensure_asciiFalse)) # 美化打印JSON结果 else: print(f请求失败状态码{response.status_code}) print(f错误信息{response.text})运行这段代码如果一切顺利你会在控制台看到一个结构化的JSON输出里面包含了图片中识别出的所有文字块及其位置信息。恭喜你你已经成功调用了GLM-OCR API接下来我们详细拆解这个过程中的每一个环节。2. 请求详解如何正确地“问”一次成功的API调用始于一个构造正确的请求。这部分我们主要关注请求方法、图片怎么传以及请求头怎么设置。2.1 核心请求方式与端点GLM-OCR的识别接口统一使用HTTP POST方法。这是因为我们需要将图片数据可能比较大作为请求体发送给服务器而POST方法正是为此设计的。API的地址端点通常形如https://api.domain.com/v1/ocr。这里的/v1代表API版本/ocr代表OCR功能路径。请务必以你获取服务的官方文档提供的地址为准。2.2 图片上传的两种姿势怎么把图片交给API常见的有两种方式你可以根据实际情况选择。方式一Base64编码推荐用于小图或编程集成就像上面的示例代码那样将图片文件读取为二进制流然后进行Base64编码得到一个长长的字符串把这个字符串放在JSON请求体的image字段里。这种方式的好处是整个请求就是一个纯粹的JSON对象易于构造和调试。{ image: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5hHgAHggJ/PchI7wAAAABJRU5ErkJggg, language: en }方式二表单文件上传适合大图或直接工具测试这种方式更符合传统的文件上传。你需要将Content-Type设置为multipart/form-data然后以表单字段的形式上传图片文件。使用requests库可以这样实现files {image: open(invoice.jpg, rb)} payload {language: zh} response requests.post(API_URL, headersheaders, filesfiles, datapayload)很多API测试工具如Postman也直接支持这种模式非常方便。关于图片格式GLM-OCR通常支持常见的栅格图像格式如PNG、JPEG/JPG、BMP等。为了保证识别效果建议图片中的文字尽量清晰、端正。图片尺寸不宜过大或过小长宽在1024像素左右通常是个不错的起点。避免过度压缩导致的文字模糊。2.3 请求头设置请求头就像是给请求贴上的“标签”告诉服务器一些关键信息。Authorization这是最重要的请求头用于身份验证。值一般是Bearer {你的API_KEY}。没有有效的API Key服务器会拒绝你的请求。Content-Type这告诉服务器你发送的数据是什么格式。如果你用Base64编码方式就设为application/json。如果你用表单上传方式就设为multipart/form-data。注意在使用requests的files参数时库会自动帮你设置这个请求头你通常不需要手动指定。3. 参数解析告诉API你的具体需求除了必传的图片你还可以通过一些可选参数来微调OCR的行为让识别结果更符合你的预期。这些参数通常作为JSON请求体的字段Base64方式或表单字段文件上传方式传递。下面是一个包含常见可选参数的请求体示例{ image: [Base64字符串], language: zh, detect_direction: false, probability: true }我们来逐一解释language(字符串可选)指定要识别的语言。这能显著提升对应语言的识别准确率。zh或zh-CN简体中文默认值。en英文。ja日文。可能还支持更多语言组合如zh,en表示中英文混合识别。具体支持列表需查阅最新文档。detect_direction(布尔值可选)是否启用文字方向检测。如果设为trueAPI会自动检测图片中文字的方向例如有些图片里的文字可能是90度旋转的并在返回结果中进行校正。对于方向不确定的图片如手机随意拍摄的文档开启这个功能很有用。默认通常是false。probability(布尔值可选)是否返回每个识别文字的置信度概率。如果设为true返回的每个文字旁边会附带一个0到1之间的数值表示模型对这个识别结果的把握程度。这个值对于后续的结果筛选或校验很有帮助。默认可能是false以简化返回数据。4. 响应解读理解API“回答”了什么API调用成功HTTP状态码为200后你会收到一个JSON格式的响应体。这个结构里包含了识别出的所有信息。理解这个结构是你从API中提取有用数据的关键。一个典型的成功响应结构如下{ log_id: 1234567890123456789, words_result: [ { words: 发票号码, location: { top: 100, left: 50, width: 200, height: 30 } }, { words: INV-2023-001, location: { top: 100, left: 280, width: 300, height: 30 }, probability: { average: 0.99, min: 0.95, variance: 0.001 } } ], words_result_num: 2, direction: 0 }我们来拆解每个字段log_id(字符串)本次请求的唯一日志ID。如果识别结果有问题向技术支持反馈这个ID能帮助他们快速定位问题。words_result(数组)这是核心结果一个数组里面的每个元素代表识别到的一个文字块通常是一行或一个词语。每个文字块是一个对象包含words(字符串)识别出的文本内容。location(对象)该文字块在图片中的位置和大小。这是一个包含top左上角纵坐标、left左上角横坐标、width宽度、height高度的对象。坐标原点通常是图片的左上角。probability(对象可选)如果请求时设置了probability: true这里会包含该文字块的置信度统计信息如平均值(average)、最小值(min)和方差(variance)。置信度越高识别结果越可靠。words_result_num(整数)识别出的文字块总数也就是words_result数组的长度。方便你快速知道识别出了多少行文字。direction(整数可选)如果请求时开启了detect_direction这个字段会返回图片的整体方向。例如0代表正常方向1代表顺时针旋转90度以此类推。你可以根据这个值对原图或结果进行旋转校正。拿到这个结构后你就可以轻松地遍历words_result提取出所有的words或者结合location信息知道每段文字在图片的哪个位置。5. 错误处理当API调用不顺利时不是每次调用都会一帆风顺。网络问题、参数错误、额度不足等都可能导致请求失败。一个健壮的集成必须能妥善处理这些错误。API主要通过两种方式告诉你出错了HTTP状态码和响应体中的错误码。5.1 HTTP状态码这是HTTP协议层面的状态最先被看到。200 OK成功。一切正常响应体里就是识别结果。400 Bad Request请求格式有误。比如你的JSON格式不对或者缺少了必填的image字段或者图片数据无法解码。这时你需要检查请求体的构造。401 Unauthorized身份验证失败。通常是API Key无效、过期或没有权限访问该接口。检查你的API Key是否正确以及是否已经启用。403 Forbidden权限不足。身份验证通过了但你的账户没有调用这个接口的权限或者调用次数已超过限额。413 Payload Too Large请求体太大。你上传的图片文件体积超过了服务器的限制。429 Too Many Requests请求频率超限。你在短时间内发送了太多请求被限流了。需要降低调用频率或检查是否触发了配额限制。500 Internal Server Error服务器内部错误。这是服务端的问题通常意味着GLM-OCR服务暂时出现了异常。你可以稍后重试或联系服务提供商。5.2 业务错误码与信息当HTTP状态码是4xx或5xx时响应体通常也是一个JSON对象里面包含了更具体的错误信息。{ error_code: 10001, error_msg: Invalid image format or data. }error_code具体的业务错误码。每个代码对应一类问题。error_msg人类可读的错误描述告诉你具体哪里出了问题。常见的错误码可能包括具体需以官方文档为准10001图片数据无效或格式不支持。10002图片尺寸过大或过小。10003识别引擎处理失败。20001API Key无效。20002API Key已过期。20003调用额度已用尽。30001请求频率超限。5.3 编写健壮的调用代码在代码中我们应该同时检查HTTP状态码和业务错误码。def call_ocr_api(image_path, api_key): # ... 构造请求的代码同上... response requests.post(API_URL, headersheaders, jsonpayload) # 首先检查HTTP状态码 if response.status_code ! 200: print(fHTTP请求失败状态码{response.status_code}) try: # 尝试解析错误响应体 error_result response.json() print(f业务错误码{error_result.get(error_code)}) print(f错误信息{error_result.get(error_msg)}) except: print(f原始错误响应{response.text}) return None # HTTP状态码为200尝试解析成功结果 try: result response.json() # 可以进一步检查结果中是否包含错误码有些API设计可能在200中也会包含错误 if error_code in result and result[error_code] ! 0: print(f业务逻辑错误{result.get(error_msg)}) return None return result except json.JSONDecodeError: print(响应不是有效的JSON格式。) return None # 使用函数 result call_ocr_api(invoice.jpg, API_KEY) if result: # 处理识别结果 for item in result.get(words_result, []): print(item[words])6. 总结好了关于GLM-OCR API接口的方方面面我们就聊到这里。从最基础的发送一个POST请求到如何上传图片、设置可选参数再到完整解析返回的JSON结果以及遇到错误时该如何应对整个过程其实并不复杂。关键是要细心尤其是构造请求和处理响应的时候。在实际集成中我建议你先用一张简单的图片跑通整个流程然后再逐步尝试更复杂的场景比如多语言识别、开启方向检测等。记得多看看返回的location信息它在需要做版式分析或信息提取的应用里会非常有用。如果遇到问题先检查HTTP状态码和错误信息它们能给你最直接的线索。希望这篇详解能帮你顺利地把GLM-OCR的能力集成到你的项目里。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。