食品经营许可证识别API参数详解与最佳实践
适用场景与接口价值
在企业资质审核、供应链合规验证、食品经营许可自动录入等场景中，手动录入许可证信息效率低且易出错。通过调用食品经营许可证识别API，可将图片中的13个关键字段（许可证编号、经营者名称、法定代表人、经营场所、主体业态、经营项目、有效期等）自动提取为结构化JSON，直接对接后端业务系统。
接口能力边界
- 支持输入：图片URL或Base64编码字符串（最大5MB）
- 返回字段：共13个（详见下方字段表），覆盖证照核心要素
- QPS限制：2次/秒，超出会返回限流错误
- 图片要求：建议清晰、无遮挡、证件四角完整，光照均匀
请求参数详解
Header参数
| 参数名 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| Content-Type | 是 | string | 固定值application/json |
请求体（JSON Object）
| 字段名 | 是否必须 | 类型 | 说明 |
|---|---|---|---|
| key | 否 | string | API密钥（Bearer令牌），也可通过HeaderX-API-Key传递（推荐） |
| input_type | 是 | string | 图片传入方式：url或base64 |
| input_data | 是 | string | 图片URL（input_type=url）或Base64编码字符串（input_type=base64，≤5MB） |
注意：
key参数在请求体中为可选，若已在Header中传入X-API-Key则可省略。建议统一通过Header传递，避免请求体泄露密钥。
鉴权方式与密钥传递
该API支持两种鉴权方式：
- Header方式：添加
X-API-Key请求头，值为您的API密钥。 - 请求体方式：在JSON对象的
key字段中填入密钥。
推荐使用Header方式，因为请求体的key可能会被日志或代理服务器记录，增加泄露风险。
curl请求示例
示例1：通过图片URL识别
curl -sS \ -X POST \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_type": "url", "input_data": "https://example.com/license.jpg" }' \ "https://v1.apizero.cn/api/food-license"示例2：通过Base64编码图片识别
# 先将图片转为base64（不含换行） BASE64=$(base64 -w0 license.jpg) curl -sS \ -X POST \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"input_type\": \"base64\", \"input_data\": \"$BASE64\" }" \ "https://v1.apizero.cn/api/food-license"请将
YOUR_API_KEY替换为实际密钥。若使用请求体传key，则在JSON中添加"key": "YOUR_API_KEY"。
返回字段全解析
成功响应（HTTP 200）示例：
{ "code": 0, "message": "success", "data": { "license_number": "JY14012800001234", "operator": "某某餐饮有限公司", "legal_representative": "张三", "premise": "北京市朝阳区某街道1号", "domicile": "北京市朝阳区某街道1号", "main_body": "餐饮服务经营者", "operating_item": "热食类食品制售", "validity_period": "长期", "issuing_authority": "北京市朝阳区市场监督管理局", "issuer": "李四", "daily_supervisor": "王五", "daily_supervisory_authorities": "北京市朝阳区市场监督管理局", "complaints_hotline": "12315" } }字段含义表
| 字段名 | 说明 | 示例 |
|---|---|---|
| license_number | 许可证编号 | JY14012800001234 |
| operator | 经营者名称 | 某某餐饮有限公司 |
| legal_representative | 法定代表人 | 张三 |
| premise | 经营场所 | 北京市朝阳区某街道1号 |
| domicile | 住所 | 北京市朝阳区某街道1号 |
| main_body | 主体业态 | 餐饮服务经营者 |
| operating_item | 经营项目 | 热食类食品制售 |
| validity_period | 有效期 | 长期 |
| issuing_authority | 发证机关 | 北京市朝阳区市场监督管理局 |
| issuer | 签发人 | 李四 |
| daily_supervisor | 日常监督管理人员 | 王五 |
| daily_supervisory_authorities | 日常监督管理机构 | 北京市朝阳区市场监督管理局 |
| complaints_hotline | 投诉举报电话 | 12315 |
注意：若图片中某字段模糊或不完整，返回的对应值可能为空字符串。建议对必填字段做空值校验。
常见错误码与处理
| HTTP状态码 | code字段 | message | 原因与处理 |
|---|---|---|---|
| 400 | 1001 | 参数错误 | 缺少必填参数input_type或input_data，检查请求体结构 |
| 400 | 1002 | 图片格式不支持 | 图片不是JPEG/PNG/WebP格式，或者Base64编码有误（如含换行） |
| 400 | 1003 | 图片过大 | Base64数据超过5MB限制，建议压缩图片或改用URL方式 |
| 401 | 2001 | 鉴权失败 | API密钥无效或未提供，检查X-API-Key或请求体key是否正确 |
| 429 | 3001 | 请求过于频繁 | QPS超过2次/秒，加入重试退避逻辑（如指数退避，初始等待1秒） |
| 500 | 5000 | 服务内部错误 | 服务端异常，可稍后重试；若持续失败请联系技术支持 |
工程化最佳实践
1. 图片预处理
- 裁剪与压缩：若图片包含多余边框或文字，建议先裁剪证件主体区域；JPEG质量可降至80%以减小体积。
- Base64注意事项：编码时不添加
data:image/jpeg;base64,前缀，仅传原始Base64字符串；确保无换行（base64 -w0）。 - 图片方向：若证件方向不正，识别准确率会下降；可先通过图像旋转纠正。
2. 请求重试与退避
由于QPS限制为2次/秒，高并发场景需加本地限流。推荐使用令牌桶算法控制请求速率。遇到429错误时，建议：
import time import requests def call_api_with_retry(url, headers, payload, max_retries=3): for attempt in range(max_retries): resp = requests.post(url, json=payload, headers=headers) if resp.status_code == 429: wait = 2 ** attempt time.sleep(wait) continue return resp return None3. 字段校验与补录
- 某些字段如
validity_period可能为“长期”，也可能为具体日期（如“2023-01-01至2028-01-01”）。建议统一解析为结束日期，方便做到期提醒。 - 若
license_number为空，说明图片质量差或非目标证件，应记录失败原因并人工审核。
4. 安全与密钥管理
- 将API密钥存储为环境变量或密钥管理服务（如Vault），避免硬编码。
- 日志中过滤掉
X-API-Key或key字段，防止敏感信息泄露。
5. 响应缓存
对于同一张图片重复请求（例如重试时），可利用图片的MD5或URL作为键，缓存识别结果5分钟，减少重复调用。
参考文档
- 官方文档页：https://apizero.cn/aidocs/food-license
- 原始Markdown：https://apizero.cn/aidocs/food-license/raw.md
- 如果对接口有其他疑问，建议查阅文档中的更新日志和FAQ。