企业官网建设流程全解析

适用场景与接口能力边界

在企业供应链合规、平台入驻商户资质审核、餐饮行业监管等场景中，需要快速提取食品经营许可证上的关键字段——许可证编号、经营者名称、法定代表人、经营场所、主体业态、经营项目、有效期等。传统的人工录入效率低且易出错，通过统一的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。

请求参数详解

注意：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-license"

Python 请求示例（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, json=payload, headers=headers) 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, json=payload, headers=headers) data = resp.json() print(data)

返回值字段与解读

接口成功时返回code: 0，data对象包含以下字段：

字段缺失说明

并非所有许可证照片都能完整识别全部13个字段。当某个字段无法识别时，对应值会返回空字符串""。业务侧在消费数据时应做容空处理，例如operator or "未知"。

常见错误码与处理

图片质量建议

• 图片分辨率建议不低于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_kb=500): with Image.open(image_path) as img: img = img.convert("RGB") output = io.BytesIO() quality = 85 while True: output.seek(0) img.save(output, format="JPEG", quality=quality) 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
• 原始接口说明（Markdown）：https://apizero.cn/aidocs/food-license/raw.md