Gemini 生图 API 错误处理指南

{
  "candidates": null,
  "usageMetadata": {
    "promptTokenCount": 271,
    "candidatesTokenCount": 0,
    "totalTokenCount": 271
  }
}

我不能为你创建带有色情、不雅或冒犯性内容的图像。这违反了我们的安全政策。
I can't generate images that are sexually explicit.

收到 API 响应
  ├─ ① candidatesTokenCount === 0 ─→ 内容审核拒绝
  ├─ ② candidates 为空 ───────────→ API 格式错误（系统问题）
  ├─ ③ finishReason !== 'STOP' ───→ 生成过程拒绝（查映射表）
  ├─ ④ content.parts 为空 ────────→ 内容为空（同 finishReason 处理）
  ├─ ⑤ 遍历 parts 收集 text 与图片
  ├─ ⑥ 有图片 ────────────────────→ ✅ 成功返回
  └─ ⑦ 无图片但有 text ──────────→ 展示拒绝说明（可选关键词识别）
        └─ 无 text ──────────────→ 通用错误 + 保留完整响应

async function processGeminiResponse(data) {
  // ① 最高优先级：内容审核阶段直接拒绝
  if (data.usageMetadata?.candidatesTokenCount === 0) {
    return {
      success: false,
      errorType: 'ZERO_CANDIDATES_TOKEN',
      userMessage: '您的请求在内容审核阶段被拒绝，请修改后重试',
      devMessage: 'candidatesTokenCount: 0 - 谷歌内容审核拒绝',
      rawResponse: data,
    };
  }

  // ② candidates 为空 —— 通常是系统/格式问题
  if (!data.candidates || !data.candidates.length) {
    return {
      success: false,
      errorType: 'NO_CANDIDATES',
      userMessage: '系统出错，请稍后重试',
      devMessage: 'candidates 为 null 或空数组',
      rawResponse: data,
    };
  }

  const candidate = data.candidates[0];

  // ③ finishReason 非 STOP —— 生成过程被拒
  if (candidate.finishReason && candidate.finishReason !== 'STOP') {
    const reasonMessages = {
      PROHIBITED_CONTENT: '内容违反安全策略，已被拒绝处理',
      IMAGE_PROHIBITED_CONTENT: '内容违反安全策略，已被拒绝处理',
      SAFETY: '内容触发了安全过滤器',
      IMAGE_SAFETY: '内容触发了图片安全策略',
      RECITATION: '内容可能涉及版权问题',
      IMAGE_RECITATION: '内容可能涉及版权问题',
      NO_IMAGE: '未能生成图片，请调整提示词后重试',
      IMAGE_OTHER: '未能生成图片，请调整提示词后重试',
      MAX_TOKENS: '内容长度超出限制',
    };
    return {
      success: false,
      errorType: 'FINISH_REASON',
      finishReason: candidate.finishReason,
      userMessage: reasonMessages[candidate.finishReason] || `请求被拒绝：${candidate.finishReason}`,
      devMessage: `finishReason: ${candidate.finishReason}`,
      rawResponse: data,
    };
  }

  // ④ content.parts 为空
  if (!candidate.content?.parts) {
    return {
      success: false,
      errorType: 'NO_PARTS',
      userMessage: '生成失败，请重试',
      devMessage: 'candidate.content.parts 为空',
      rawResponse: data,
    };
  }

  // ⑤ 遍历 parts：⚠️ 务必先收集 text，再判断 thoughtSignature
  const images = [];
  const texts = [];
  for (const part of candidate.content.parts) {
    if (part.text && !part.text.startsWith('data:image/')) {
      texts.push(part.text);
    }
    if (part.inlineData?.data) {
      images.push(`data:${part.inlineData.mimeType};base64,${part.inlineData.data}`);
    }
  }

  // ⑥ 有图片即成功
  if (images.length > 0) {
    return { success: true, images, texts };
  }

  // ⑦ 无图片但有文本 —— 展示拒绝说明
  if (texts.length > 0) {
    const textContent = texts.join('\n');
    return {
      success: false,
      errorType: 'TEXT_RESPONSE',
      userMessage: textContent,          // 直接使用 API 返回的文本
      detectedType: detectContentType(textContent),
      apiText: textContent,
      rawResponse: data,
    };
  }

  // ⑧ 兜底：永远不要只说「未知错误」
  return {
    success: false,
    errorType: 'UNKNOWN',
    userMessage: '生成失败，请检查提示词后重试',
    devMessage: '未找到图片数据或文本响应',
    rawResponse: data,
  };
}

function detectContentType(text) {
  const t = text.toLowerCase();
  const isRejection =
    t.includes("i can't generate") || t.includes('i cannot create') ||
    t.includes("i'm just a language model") || t.includes('我不能') || t.includes('无法生成');
  if (!isRejection) return null;

  if (t.includes('watermark')) return 'watermark_removal';
  if (t.includes('faceswap') || t.includes('face swap')) return 'faceswap';
  if (t.includes('sexually') || t.includes('explicit') || t.includes('色情') || t.includes('不雅')) return 'nsfw';
  return 'general_rejection';
}

❌ 内容不符合要求
您的请求包含不适当内容，无法生成图片。
💡 建议：使用健康、正面的描述；避免敏感话题；重新调整提示词后再试。

❌ 功能暂不支持
该功能（如去水印/换脸）暂不支持，请尝试其他编辑方式。

❌ 内容超出范围
您提到的内容可能超出了 AI 的知识范围（更新至 2025 年 1 月）。
💡 建议：使用常见物品/概念，避免引用未来的产品。