如何正确将 Base64 图像传递给 Roboflow Infer API-html教程-PHP中文网

如何正确将 Base64 图像传递给 Roboflow Infer API

本文详解如何构造符合 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 字符串长度，降低传输延迟与失败率。
错误排查优先级：
1. 检查 response.status_code == 400 时的 response.json().get("error")；
2. 验证 Base64 字符串是否以 "data:image/jpeg;base64," 开头？❌ 不需要——Roboflow 明确要求纯 Base64 字符串（无 data URL 前缀）；
3. 确保 model_id 格式正确：workspace/model-name/version（如 my-workspace/my-detector/3）。