Gemini 3.5 Pro API 调用需用 multipart/form-data 上传，禁用关联数组传参；必须用服务账号获取带自动刷新的 access_token；响应含 inline_data 或 file_uri，流式需按 SSE 解析；GCS 权限与 URI 格式须严格匹配。
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 数组。
立即学习“PHP免费学习笔记（深入）”；
- 非流式调用返回结构为
['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。
