适用场景与接口能力边界在企业供应链合规、平台入驻商户资质审核、餐饮行业监管等场景中需要快速提取食品经营许可证上的关键字段——许可证编号、经营者名称、法定代表人、经营场所、主体业态、经营项目、有效期等。传统的人工录入效率低且易出错通过统一的API接口可以实现自动化识别。本接口/api/food-license支持两种图片传入方式URL链接或Base64编码字符串。识别后返回JSON格式的结构化数据共包含13个字段。接口的QPS上限为2次/秒适用于日均数万次调用的中等并发业务。需要特别说明的是接口本身不存储图片调用方需自行保证图片的合法性及传输安全。鉴权方式与请求头接口采用HTTP POST传输请求体为JSON格式。鉴权有两种方式任选其一请求头鉴权在Header中携带X-API-Key: your_api_key推荐避免请求体暴露敏感信息请求体鉴权在JSON body中传入key字段必须设置的Header为Content-Type: application/json。请求参数详解字段类型必填说明keystring否API密钥若已在请求头中传递则无需包含input_typestring是url或base64指定图片传入方式input_datastring是当input_typeurl时为图片直链当input_typebase64时为Base64编码字符串最大5MB注意input_type的值必须与input_data的格式严格对应。若传递Base64时input_type设为url接口将返回400 Bad Request。可复制的请求示例curl 示例推荐在本地验证# 使用URL传入图片 curl -sS -X POST \ -H X-API-Key: YOUR_API_KEY_HERE \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://example.com/license.jpg} \ https://v1.apizero.cn/api/food-license# 使用Base64传入图片 BASE64_DATA$(base64 -w0 /path/to/license.jpg) curl -sS -X POST \ -H X-API-Key: YOUR_API_KEY_HERE \ -H Content-Type: application/json \ -d {input_type: base64, input_data: $BASE64_DATA} \ https://v1.apizero.cn/api/food-licensePython 请求示例requests库import requests import base64 API_URL https://v1.apizero.cn/api/food-license API_KEY your_api_key_here # 方式一使用图片URL payload { input_type: url, input_data: https://example.com/license.jpg } headers { X-API-Key: API_KEY, Content-Type: application/json } resp requests.post(API_URL, jsonpayload, headersheaders) data resp.json() print(data) # 方式二使用本地图片的Base64 with open(license.jpg, rb) as f: b64_data base64.b64encode(f.read()).decode(utf-8) payload[input_type] base64 payload[input_data] b64_data resp requests.post(API_URL, jsonpayload, headersheaders) data resp.json() print(data)返回值字段与解读接口成功时返回code: 0data对象包含以下字段字段类型示例值说明license_numberstringJY14012800001234许可证编号operatorstring某某餐饮有限公司经营者名称legal_representativestring张三法定代表人premisestring北京市朝阳区某街道1号经营场所地址domicilestring北京市朝阳区某街道1号住所企业准备地址main_bodystring餐饮服务经营者主体业态operating_itemstring热食类食品制售经营项目validity_periodstring长期有效期格式可能为长期或2025-01-01issuing_authoritystring北京市朝阳区市场监督管理局发证机关issuerstring李四签发人daily_supervisorstring王五日常监管人员daily_supervisory_authoritiesstring北京市朝阳区市场监督管理局日常监督管理机构complaints_hotlinestring12315投诉举报电话字段缺失说明并非所有许可证照片都能完整识别全部13个字段。当某个字段无法识别时对应值会返回空字符串。业务侧在消费数据时应做容空处理例如operator or 未知。常见错误码与处理HTTP状态码错误信息可能原因解决方案400参数校验失败input_type值不合法或input_data为空检查参数是否正确传递Base64数据是否超过5MB401无效API密钥X-API-Key或key值错误确认密钥是否有效是否已在平台生成413请求体过大Base64图片超过5MB限制压缩图片或使用URL方式URL方式无文件大小限制但需保证图片可公开访问且服务器响应时间5秒429超过QPS限制每秒请求数超过2次请求端增加限流或退避策略500服务内部错误图片无法解析或服务器异常检查图片是否清晰、是否包含完整证件页面可更换图片后重试图片质量建议图片分辨率建议不低于1024×768文字区域清晰无遮挡。避免倾斜过度倾斜角超过45度时识别准确率会明显下降。最好使用扫描件或平整拍摄的照片不要有反光或阴影。工程化注意事项1. QPS 与并发控制接口限频为2次/秒。如果业务场景需要更高的吞吐率常见做法有两种请求队列 节流在应用层用令牌桶或固定窗口限制每秒请求数超出部分放入队列等待下一周期发送。多账户轮询申请多个API Key在请求时随机切换需注意每个Key的独立限频且应遵守平台规则。2. Base64 大小与性能Base64编码会使数据体积增加约1/3。对于5MB的原始图片Base64字符串约7MB。在Python请求中发送超过10MB的请求体可能导致网络超时默认超时通常为10秒。建议在发送前用io.BytesIO和PIL库压缩图片from PIL import Image import io, base64 def compress_image(image_path, max_size_kb500): with Image.open(image_path) as img: img img.convert(RGB) output io.BytesIO() quality 85 while True: output.seek(0) img.save(output, formatJPEG, qualityquality) if output.tell() / 1024 max_size_kb: break quality - 10 return base64.b64encode(output.getvalue()).decode()3. 缓存策略对同一张图片不需要反复调用。建议以图片内容的哈希值如MD5作为缓存键将识别结果缓存至Redis或本地内存TTL设置为24小时或更长。对于每日重复审核的场景如同一张许可证多次上传缓存可大幅降低调用量。4. 错误重试与幂等接口是幂等的——同一张图片多次调用返回结果相同。对于可重试的错误429、500、网络超时建议采用指数退避Exponential Backoff重试最多3次间隔分别为1秒、2秒、4秒。5. 安全注意事项图片可能包含敏感信息如法定代表人姓名、经营地址在传输过程中务必使用HTTPS。不要在日志中完整打印请求体或Base64数据可以只记录图片URL或对Base64截取前100个字符。API Key应存储在环境变量或配置中心不要硬编码在代码仓库中。参考文档接口完整文档https://apizero.cn/aidocs/food-license原始接口说明Markdownhttps://apizero.cn/aidocs/food-license/raw.md