模型专属问题排查

本页汇总各模型在调用过程中常见的专属问题及解决方案。

Gemini：modalities 设为 image 时返回空响应但仍计费

问题现象：在请求体中设置 "modalities": ["image"] 时，可能返回的 choices 中没有内容（或 message 为空），但 usage 中 completion_tokens 仍有数值（产生计费）。

核心原因：modalities 是输出过滤器，只筛选指定类型的内容。如果模型因指令理解偏差或安全策略截断，只生成了文本而没有生成图片，接口过滤掉文本后返回的就是空响应；而模型生成这些文字所消耗的算力依然计费。

解决方案：

1. 优化 Prompt 指令：明确要求模型仅输出图像，禁止开场白与解释。
   • 错误示例：「请帮我画一个 Logo，并告诉我你的设计灵感。」
   • 正确示例：Generate a professional logo for a tech startup. Image only, no text explanation.
2. 检查安全过滤：若 Prompt 触发安全审核，模型会返回一段拒绝文本，该文本会被 modalities 过滤掉而表现为空响应，请确保 Prompt 符合内容合规要求。
3. 调试建议：开发阶段可暂时改为 "modalities": ["text", "image"]，观察模型实际输出了什么，调整稳定后再去掉 "text"。

Gemini：GCS 混合权限模式导致的访问差异（ACL vs IAM）

问题现象：使用 curl 或浏览器访问 GCS 文件成功，但 Vertex AI（代码 / 服务账号）访问报 403 Forbidden。

核心原因：存储桶配置了 uniform_bucket_level_access: false，存在两套并行的权限系统——curl 命中 ACL（文件设为 Public，通过），Vertex AI 命中 IAM（服务账号未授权，拒绝）。

sequenceDiagram
    autonumber
    participant U as Client (curl/Browser)
    participant V as Vertex AI (Service Account)
    participant G as GCS Bucket (Hybrid Mode)

    Note over G: ⚠️ 配置现状<br/>ACL: Public-Read (公开)<br/>IAM: Deny All (默认)

    U->>G: HTTP 请求 (Public URL)
    G->>G: 优先检查对象级 ACL
    Note right of G: ✅ ACL 允许 Public 读取
    G-->>U: 200 OK (成功)

    V->>G: API 调用 (Google SDK)
    G->>G: 强制检查 IAM 策略
    Note right of G: ❌ 服务账号无 IAM 角色 (忽略 ACL)
    G-->>V: 403 Forbidden (失败)

解决方案：

可运行 gcloud storage buckets describe gs://xxx 查看 uniform_bucket_level_access 是否为 false，并确认 Vertex AI 使用的服务账号在存储桶的 IAM 权限列表中。

Gemini：Vertex AI 图片抓取失败（URL_REJECTED）

问题现象：调用 Vertex AI 多模态接口时报错 URL_REJECTED-REJECTED_FC_TOO_MANY_PENDING 或 URL_ERROR-ERROR_NOT_FOUND。

核心原因：跨区域回源超时。Vertex AI 的全球计算节点（如美洲）在请求 CDN 图片时，因该区域 CDN 未预热（Cold Cache），强制跨洋回源至国内源站，导致网络延迟过高或连接被阻断，最终触发获取内容失败。

解决方案：

排查时确认：报错是否包含 REJECTED_FC_TOO_MANY_PENDING 或 FetchError、图片 URL 源站是否位于中国大陆、能否在该 URL 所在区域（如海外 VPS）成功下载。

Sora：视频生成触发合规拦截

问题现象：任务状态为 failed，错误代码 moderation_blocked，提示 Possible reasons: violence, sexual。

核心原因：语义误判。Prompt 中的物理动作描述（如「锁链」「拖拽」）被安全系统识别为暴力冲突或受限制等高风险特征，而非用户意图表达的神话 / 玄幻场景。

解决方案：语义降噪与重构：

排查时确认：Prompt 是否包含「身体接触」与「限制自由」组合的词汇、是否使用带强烈主观情绪的动词（强迫、虐待、殴打）、玄幻场景是否忘记添加 Fantasy/Magic 等风格限定词。

Sora：输入图片尺寸不匹配

问题现象：调用编辑或图生视频接口时报错 Inpaint image must match the requested width and height。

核心原因：请求参数中设定的 size 与上传参考图片的实际分辨率不一致。Sora 要求输入图片的像素尺寸必须严格等于请求参数中的 width 和 height。例如上传 1024×1024 的图片却设置 size: 1280x720，会校验失败。

解决方案（二选一）：

• 以图片为准：先获取源图实际宽高，将请求中的 size 修改为对应数值。
• 以需求为准：使用图像处理工具（Photoshop、PIL 等）将源图裁剪或缩放至目标分辨率后再上传。

Gemini 生图接口报错「没有图片」

问题现象：调用 Gemini 生图模型（如 gemini-3.1-flash-image-preview）时报错「响应中没有图片」，具体表现随接口而异：

同步 Images 接口的报错示例：

{
  "error": {
    "message": "There are no images in the model's response. Please optimize your prompt to ensure a clear intention for generating images.",
    "type": "invalid_request_error"
  }
}

核心原因：Gemini 生图模型是图文双模态模型——它既能生成图片，也能只输出纯文本。而上述接口都是「图片专用」链路，只能处理图片输出、无法解析纯文本响应。当模型这次没有生成图片时，图片专用接口拿不到图片，就会报「没有图片」。典型触发场景：Prompt 生图意图不明确被当成普通对话，或模型认为信息不足而发起追问（最常见，例如「你要什么品种的狗？」）。

解决方案：

1. 切换到 Chat 接口（推荐）：改用 /v1/chat/completions（https://api.modelink.ai/v1/chat/completions）。该接口本身就是图文双模态返回，无论模型返回图片还是追问文本都能正常承接，无需额外声明输出类型：

   curl --location --request POST 'https://api.modelink.ai/v1/chat/completions' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "model": "gemini-3.1-flash-image-preview",
       "messages": [
           { "role": "user", "content": "生成一张金毛犬在草地上奔跑的照片" }
       ]
   }'

   复制

   模型正常生图时，图片以 Base64 data URI 形式放在 choices[].message.images 中返回；若模型这次只回了文本（如发起追问），则文本会正常出现在 choices[].message.content 中，不会再报错：

   {
     "choices": [
       {
         "message": {
           "role": "assistant",
           "content": "",
           "images": [
             {
               "type": "image_url",
               "image_url": { "url": "data:image/png;base64,iVBORw0KG..." },
               "index": 0
             }
           ]
         },
         "finish_reason": "stop"
       }
     ]
   }

   复制

2. 优化 Prompt：如必须使用图片专用接口，强制要求模型直接输出图片，例如「生成一张金毛犬在草地上奔跑的照片，不要文字描述，直接输出图片。」

各接口的完整参数见 API Reference：Chat 接口 · Gemini、Gemini 3.0 Pro（异步）、Gemini 3.1 Flash（异步）、Gemini 3.1 Flash Lite（异步）。