PHP 接入 Gemini Pro API，多模态图片识别功能开发实录-php教程-PHP中文网

根本原因是gemini api的generatecontent接口要求图片必须为带data:image/xxx;base64,前缀的base64字符串并置于inlinedata字段，而非裸二进制或文件路径；常见错误包括误用multipart、mime类型不匹配、json结构错误（如parts未与text同级）、认证头缺失或超时过短。

php 接入 gemini pro api，多模态图片识别功能开发实录

为什么 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 当作纯文本请求，忽略图片。

Ask Gemini/ChatGPT

用于在用户想通过浏览器自动化与 Google Gemini 或 ChatGPT 交互时。触发短语包括“ask Gemini”“ask ChatGPT”“ask GPT”“让...”。

下载

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 结构嵌套、认证头格式、安全拦截兜底——这四点串起来才跑通一次有效识别。少盯住其中任何一个，都会卡在“看着请求发出去了，却没结果”。