调用Gemini_3_Pro_API处理多模态数据方法

本文深入解析了在PHP环境中调用Gemini 3.5 Pro API处理多模态数据（如图文混合输入）时极易踩坑的核心技术要点：必须严格采用multipart/form-data格式上传而非JSON传base64图片，手动构造boundary并正确设置请求头；务必通过服务账号获取可自动刷新的access_token，杜绝硬编码或无效密钥；响应解析需区分非流式结构嵌套与流式SSE分块，精准提取text、inline_data或file_uri；同时彻底厘清GCS权限配置误区——Gemini服务账号需显式拥有storage.objects.get权限，file_uri格式（gs://）与区域一致性不容有失。全文直击生产环境调试痛点，为开发者提供可立即落地的全链路排错指南。

PHP 调用 Gemini 3.5 Pro API 时，multipart/form-data 请求体构造失败

Gemini 3.5 Pro（注意：当前官方无 “Gemini 3 Pro” 或 “3_Pro_API”，实际应为 Gemini 3.5 Pro）API 不支持直接在 JSON body 中传 base64 图片；必须用 multipart/form-data 格式上传文件 + 文本提示。PHP 默认的 curl_setopt($ch, CURLOPT_POSTFIELDS, $arr) 会自动转成 application/x-www-form-urlencoded，导致 400 错误。

正确做法是手动构造 boundary 并设置 Content-Type 头：

• 不要用关联数组传 CURLOPT_POSTFIELDS，改用字符串 + 手动 boundary
• 使用 curl_file_create()（PHP 5.5+）或自行拼接 raw body（兼容旧版）
• 必须显式设置 Content-Type: multipart/form-data; boundary=...，不能依赖 cURL 自动推断

$boundary = '----' . md5(time() . mt_rand());
$data = "--{$boundary}\r\n";
$data .= "Content-Disposition: form-data; name=\"contents\"; filename=\"content.json\"\r\n";
$data .= "Content-Type: application/json\r\n\r\n";
$data .= json_encode([[
    'role' => 'user',
    'parts' => [
        ['text' => '这张图里有什么？'],
        ['file_data' => ['mime_type' => 'image/jpeg', 'file_uri' => 'gs://your-bucket/photo.jpg']] // 注意：Gemini 3.5 Pro 实际不支持 file_uri 直传，需先上传到 Google Cloud Storage 并授权模型访问
    ]
]], JSON_UNESCAPED_UNICODE);
$data .= "\r\n--{$boundary}--\r\n";

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: multipart/form-data; boundary=' . $boundary,
    'x-goog-user-project: your-project-id',
    'Authorization: Bearer ' . $access_token
]);

PHP 获取 Gemini 3.5 Pro 访问令牌（access_token）失败

Google AI Studio 不提供长期有效的 API Key；Gemini 3.5 Pro 的正式生产调用必须走 OAuth 2.0 或服务账号密钥（service-account-key.json），不能用前端密钥或简单 API Key。

• 开发调试可用 gcloud auth application-default login + Google\Auth\ApplicationDefaultCredentials，但服务器部署必须用服务账号
• 服务账号 JSON 文件需启用 roles/aiplatform.user 权限，并在项目中开启 AI Platform Training & Prediction API
• PHP 中推荐用 google/auth 包生成 token：new ApplicationDefaultCredentials('https://www.googleapis.com/auth/cloud-platform')
• token 有效期约 1 小时，务必实现自动刷新逻辑，不能硬编码或单次获取后复用

PHP 处理 Gemini 3.5 Pro 多模态响应中的图片引用与流式输出

响应体不是纯文本，而是包含 content.parts[].inline_data（base64 图片）或 content.parts[].file_data.file_uri（GCS 路径），且流式接口（/streamGenerateContent）返回的是 chunked SSE 数据，不是标准 JSON 数组。

• 非流式调用返回结构为 ['candidates' => [[ 'content' => [ 'parts' => [...] ] ]]]，需逐层解包
• 若响应含图片，parts 中可能混有 text 和 inline_data，不能假设 parts[0]['text'] 存在
• 流式响应需按行解析 data: {...}，跳过空行和 event: 行，用 json_decode(trim($line, "data: \n\r"))
• PHP 的 curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: text/event-stream']) 必须配合 curl_setopt($ch, CURLOPT_BUFFERSIZE, 1) 避免缓冲阻塞

为什么 file_data.file_uri 在 PHP 调用中总是报错 PERMISSION_DENIED: Permission denied on Google Cloud Storage object

这不是 PHP 代码问题，而是权限链断裂：Gemini 服务账号（不是你的个人账号）必须对 GCS 对象有 storage.objects.get 权限，且对象不能设为私有（除非显式授权）。

• GCS bucket 和 object 的 ACL 必须开放给服务账号邮箱（形如 xxx@developer.gserviceaccount.com）
• 更稳妥的做法是使用 signed URL 或将图片先通过 generateContent 的 multipart 方式上传（Gemini 3.5 Pro 当前仅支持 GCS URI，不支持 multipart 图片直传 —— 这点极易误解，实际必须提前上传）
• 检查 file_uri 格式是否正确：gs://bucket-name/path/to/image.jpg，不能带 https:// 前缀，也不能漏掉 gs://
• 确认 GCS bucket 与调用项目在同一区域（虽非强制，但跨区域可能触发隐式拒绝）

多模态链路长、环节多，每个节点权限和格式都得对齐，光看 PHP 代码很难定位问题。建议先用 curl 命令验证 GCS URI 可访问性，再套进 PHP。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。