本文详解如何构造符合 roboflow infer api 要求的 base64 图像请求体，解决因格式错误导致的 400 错误，并提供两种可靠实现方式：手动序列化与官方 sdk 封装。
本文详解如何构造符合 roboflow infer api 要求的 base64 图像请求体，解决因格式错误导致的 400 错误，并提供两种可靠实现方式：手动序列化与官方 sdk 封装。
Roboflow 的 Infer API 要求以特定 JSON 结构提交 Base64 编码图像，而非直接发送原始 base64 字符串。常见错误（如 400 Bad Request）往往源于未按规范封装数据——API 期望的是一个包含 "type": "base64" 和 "value" 字段的对象，而非裸字符串。
✅ 正确的请求体结构
必须将 Base64 图像嵌入如下 JSON 对象中：
{
"image": {
"type": "base64",
"value": "your_base64_encoded_string_here"
}
}注意：整个请求体是 JSON，"image" 是顶层键，其值为上述结构对象。若遗漏 image 外层包装或字段名错误（如写成 data 或 img），API 均会拒绝并返回 400。
? 方式一：手动构建 Base64 请求（推荐用于调试/轻量集成）
以下代码使用 OpenCV 读取图像、编码为 JPEG 字节流，再 Base64 编码并组装为合法 JSON：
import base64
import json
import cv2 as cv
import numpy as np
import requests
# 1. 读取并编码图像
cv_image = cv.imread("/path/to/image.jpg", cv.IMREAD_COLOR)
if cv_image is None:
raise ValueError("Failed to load image")
_, img_encoded = cv.imencode(".jpg", cv_image) # 压缩为 JPEG 字节
b64_string = base64.b64encode(img_encoded.tobytes()).decode("utf-8")
# 2. 构造符合 API 规范的 JSON 请求体
payload = {
"image": {
"type": "base64",
"value": b64_string
}
}
# 3. 发送 POST 请求（注意：params 仅用于 query 参数，如 API key；body 必须是 JSON）
roboflow_url = "https://api.roboflow.com/v1/predict/YOUR_MODEL_ID"
params = {"api_key": "YOUR_API_KEY"} # ⚠️ 不要放在 body 中！
response = requests.post(
roboflow_url,
params=params,
json=payload, # ✅ 关键：使用 json= 自动序列化 + 设置 Content-Type: application/json
timeout=30
)
print(response.status_code)
print(response.json())? 提示：务必使用
json=参数（而非data=），否则需手动调用json.dumps()并设置headers={"Content-Type": "application/json"}；json=更安全、不易出错。
? 方式二：使用官方 inference_sdk（生产环境首选）
官方 SDK 已内置鲁棒的图像加载、编码与请求逻辑，自动处理格式、重试、超时等细节：
from inference_sdk import InferenceHTTPClient
from inference_sdk.http.entities import InferenceConfiguration
# 初始化客户端（支持云端或本地部署）
client = InferenceHTTPClient(
api_url="https://api.roboflow.com", # 生产环境 URL
api_key="YOUR_API_KEY"
)
# 可选：配置可视化等参数
client.configure(InferenceConfiguration(
visualize_predictions=True,
visualize_labels=True,
confidence=0.5
))
# 直接传入本地路径，SDK 自动完成读取→编码→请求
result = client.infer("/path/to/image.jpg", model_id="your-model-id/1")
# 解析结果（含可视化图像 Base64）
if "visualization" in result:
import base64, cv2, numpy as np
viz_b64 = result["visualization"]
img_bytes = base64.b64decode(viz_b64)
img_array = np.frombuffer(img_bytes, dtype=np.uint8)
img = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
cv2.imshow("Prediction", img)
cv2.waitKey(0)⚠️ 关键注意事项
-
不要混淆
params与json：api_key等认证参数应通过params（即 URL 查询参数）传递；图像数据必须在json（请求体）中。 - 图像预处理非必需但推荐：Roboflow 模型通常接受任意尺寸，但压缩为 JPEG（而非 PNG）可显著减小 Base64 字符串长度，降低传输延迟与失败率。
-
错误排查优先级：
- 检查
response.status_code == 400时的response.json().get("error")； - 验证 Base64 字符串是否以
"data:image/jpeg;base64,"开头？❌ 不需要——Roboflow 明确要求纯 Base64 字符串（无 data URL 前缀）； - 确保
model_id格式正确：workspace/model-name/version（如my-workspace/my-detector/3）。
- 检查
掌握以上任一方法，即可稳定对接 Roboflow Infer API。对于新项目，强烈建议采用 inference_sdk，它持续同步官方更新，避免自行维护序列化逻辑带来的兼容性风险。
