本文详解如何构造符合 roboflow infer api 要求的 base64 图像请求体，解决因格式错误导致的 400 错误，并提供可直接运行的 python 示例与最佳实践。
本文详解如何构造符合 roboflow infer api 要求的 base64 图像请求体，解决因格式错误导致的 400 错误，并提供可直接运行的 python 示例与最佳实践。
Roboflow 的 Infer API 并不接受原始 Base64 字符串作为 request body（如 data=base64_string），而是要求以 JSON 格式封装图像数据，其中必须包含 "type": "base64" 和 "value": "<base64-encoded-string>"</base64-encoded-string> 两个字段。这是导致 requests.post(..., data=base64_image) 返回 400 错误的根本原因——API 无法解析裸字符串，期望的是结构化 JSON payload。
✅ 正确做法是：将 Base64 图像嵌入标准 JSON 对象，并通过 json 参数发送（自动设置 Content-Type: application/json）：
import base64
import json
import cv2
import numpy as np
import requests
# 1. 读取并编码图像
img = cv2.imread("/path/to/image.jpg", cv2.IMREAD_COLOR)
_, buffer = cv2.imencode(".jpg", img)
b64_string = base64.b64encode(buffer).decode("utf-8") # 注意：.decode() 得到 str，非 bytes
# 2. 构造符合 Roboflow 规范的 JSON payload
payload = {
"image": {
"type": "base64",
"value": b64_string
}
}
# 3. 发送 POST 请求（关键：用 json= 而非 data=）
roboflow_url = "https://detect.roboflow.com/{model_id}"
params = {
"api_key": "your_api_key_here",
"confidence": 0.3
}
response = requests.post(
roboflow_url,
params=params,
json=payload # ✅ 正确方式：自动序列化 + 设置 Content-Type
)
if response.status_code == 200:
result = response.json()
print("Inference successful:", len(result.get("predictions", [])), "objects detected")
else:
print("Error:", response.status_code, response.text)⚠️ 关键注意事项：
-
不要使用
data=参数传 Base64：它会以text/plain或未指定类型发送，API 拒绝解析； -
json=是必需的：确保请求体为合法 JSON，且Content-Type: application/json被正确设置； -
Base64 字符串必须是 UTF-8 解码后的普通字符串（即
base64.b64encode(...).decode()），而非字节对象； - 图像预处理建议：保持合理尺寸（如 ≤ 1280px 边长），避免超载或压缩失真；推荐使用
.jpg编码（兼容性最好），若需透明通道则用.png； - 如需批量推理或本地部署，强烈推荐使用官方 SDK
inference_sdk，它已内置鲁棒的图像序列化逻辑与错误处理：
from inference_sdk import InferenceHTTPClient
client = InferenceHTTPClient(
api_url="https://detect.roboflow.com",
api_key="your_api_key"
)
# 自动处理本地路径、URL 或 PIL/OpenCV 图像
result = client.infer("/path/to/image.jpg", model_id="my-model/1")
print(result["predictions"])总结：Roboflow Infer API 的 Base64 图像必须以 {"image": {"type": "base64", "value": "..."}} 形式通过 json= 参数提交。掌握这一结构化约定，即可稳定调用云端模型，避免 400 错误，大幅提升集成效率。
