根本原因是Gemini API的generateContent接口要求图片必须为带data:image/xxx;base64,前缀的Base64字符串并置于inlineData字段，而非裸二进制或文件路径；常见错误包括误用multipart、MIME类型不匹配、JSON结构错误（如parts未与text同级）、认证头缺失或超时过短。
为什么 Gemini Pro 的图片识别在 PHP 里总是返回 400 错误
根本原因是 Gemini API 的 generateContent 接口不接受裸二进制图片，也不支持直接传本地文件路径——它要求图片必须是 Base64 编码后、带 data:image/xxx;base64, 前缀的字符串，并且要放在 inlineData 字段里，而不是 fileData 或表单字段中。
常见错误现象包括：400 Request contains an invalid argument、Invalid inlineData: data must be base64 encoded、或返回空 content 但无报错。这通常是因为用了 curl_file_create()、multipart/form-data 提交，或者 Base64 编码漏了 MIME 类型前缀。
- 用
file_get_contents($path)读取图片后，必须调用base64_encode()，再拼接如"data:image/jpeg;base64," . $encoded - MIME 类型不能硬写
image/jpeg：用exif_imagetype()或mime_content_type()动态获取，否则 PNG 传成 JPEG 前缀会失败 - 请求头必须设为
Content-Type: application/json，不能用multipart
如何构造符合 Gemini 要求的多模态请求体
PHP 没有官方 SDK，得手动拼 JSON body。关键结构是：外层 contents 是数组，每个元素含 parts（文字 + 图片），图片部分必须是 {"inlineData": {"mimeType": "...", "data": "..."}} 形式。
文字提示（prompt）和图片必须在同一 parts 数组里，顺序无关，但不能分开到不同 contents 条目中——否则 Gemini 当作纯文本请求，忽略图片。
立即学习“PHP免费学习笔记（深入）”；
-
mimeType必须与 Base64 前缀一致，例如image/png对应data:image/png;base64,... - 如果要识别多张图，把多个
{"inlineData": {...}}和文字一起塞进同一个parts数组（Gemini Pro 支持最多 16 张图） - 不要在 JSON 中留 PHP 变量未解析，比如
"data": "= $b64 ?>"—— 必须用json_encode()序列化整个 body，否则引号、反斜杠会出错
$body = [
'contents' => [[
'parts' => [
['text' => '描述这张图，列出所有可见物体'],
[
'inlineData' => [
'mimeType' => 'image/jpeg',
'data' => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($imgPath))
]
]
]
]]
];
$payload = json_encode($body, JSON_UNESCAPED_UNICODE);
PHP cURL 调用时容易漏掉的认证和超时配置
Gemini API 认证只认 Authorization: Bearer YOUR_API_KEY，不支持 API Key 放 query string（会报 API key not valid）。同时，默认 cURL 超时太短，大图 Base64 编码后体积翻 1.3 倍，上传慢，5 秒超时很常见。
- 必须显式设置
CURLOPT_TIMEOUT≥ 30，尤其识别高分辨率图时 -
CURLOPT_SSL_VERIFYPEER设为false仅限调试；生产环境务必保持true并确保系统 CA 证书可用 - 别忘了
CURLOPT_HTTPHEADER包含Content-Type: application/json和Authorization，漏任意一个都 401 或 400 - 响应体要用
json_decode($res, true)解析，直接echo $res看不到结构，容易误判失败
识别结果解析时要注意 content 和 candidates 的嵌套层级
成功响应不是扁平 JSON，而是 response → candidates → 0 → content → parts → 0 → text 这样多层嵌套。直接读 $json['text'] 肯定为空。
更麻烦的是：当模型拒绝回答（比如图太模糊、含敏感内容），candidates 数组可能为空，或 finishReason 为 "SAFETY"，此时 text 字段根本不存在——不判断就 fatal error。
- 先检查
isset($json['candidates']) && !empty($json['candidates']) - 再确认
isset($json['candidates'][0]['content']['parts'][0]['text'])，否则 fallback 到日志记录$json['candidates'][0]['finishReason'] - 如果要兼容多段输出（Gemini 有时分点返回），遍历
parts数组拼接text字段，而非只取[0]
Base64 图片编码、JSON 结构嵌套、认证头格式、安全拦截兜底——这四点串起来才跑通一次有效识别。少盯住其中任何一个，都会卡在“看着请求发出去了，却没结果”。
