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 月）。
💡 建議：使用常見物品/概念，避免引用未來的產品。