疑難排解指南

您可以參考本指南，診斷並解決呼叫 Gemini API 時發生的常見問題。您可能會遇到 Gemini API 後端服務或用戶端 SDK 的問題。我們的用戶端 SDK 已在下列存放區開放原始碼：

如果遇到 API 金鑰問題，請確認您已按照API 金鑰設定指南正確設定 API 金鑰。

Gemini API 後端服務錯誤代碼

下表列出您可能遇到的常見後端錯誤代碼，並說明其原因和疑難排解步驟：

HTTP 代碼	狀態	說明	範例	解決方案
400	INVALID_ARGUMENT	要求主體格式不正確。	您的要求中出現錯字，或缺少必填欄位。	請參閱 API 參考資料，瞭解要求格式、範例和支援的版本。使用較新 API 版本的功能搭配舊版端點，可能會導致錯誤。
400	FAILED_PRECONDITION	你所在的國家/地區無法使用 Gemini API 免費方案。請在 Google AI 研究室中為專案啟用計費功能。	您在不支援免費方案的區域提出要求，且尚未在 Google AI Studio 中為專案啟用帳單功能。	如要使用 Gemini API，您必須使用 Google AI Studio 設定付費方案。
403	PERMISSION_DENIED	您的 API 金鑰沒有必要的權限。	您使用錯誤的 API 金鑰，且嘗試使用經過調整的模型，但未經過適當的驗證。	請確認 API 金鑰已設定且具有正確的存取權。並確實完成適當的驗證程序，才能使用經過調整的模型。
404	NOT_FOUND	找不到要求的資源。	找不到要求中提及的圖片、音訊或影片檔案。	檢查 API 版本是否支援要求中的所有參數。
429	RESOURCE_EXHAUSTED	您已超過頻率限制。	您使用免費層級的 Gemini API 傳送過多要求，每分鐘超過 100 次。	請確認您符合模型的頻率限制。如有需要，請申請提高配額。
500	INTERNAL	Google 端發生非預期錯誤。	輸入內容太長。	減少輸入內容或暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否可行。或者，請稍候片刻，然後再嘗試提出要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕回報問題。
503	無法使用	這項服務可能暫時超載或關閉。	服務暫時無法負荷。	暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否可正常運作。或者，請稍候片刻，然後再嘗試提出要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕回報問題。
504	DEADLINE_EXCEEDED	服務無法在期限內完成處理作業。	提示 (或內容) 過大，無法及時處理。	請在用戶端要求中設定較長的「逾時」時間，以免發生此錯誤。

檢查 API 呼叫是否有模型參數錯誤

請確認模型參數值符合下列範圍：

模型參數	值 (範圍)
候選人數量	1 到 8 (整數)
溫度	0.0-1.0
輸出詞元數量上限	使用 `get_model` (Python) 判斷所用模型的符記上限。
TopP	0.0-1.0

除了檢查參數值之外，請確認您使用的是正確的 API 版本 (例如 /v1 或 /v1beta) 和支援所需功能的型號。舉例來說，如果某項功能屬於 Beta 版，則僅適用於 /v1beta API 版本。

確認你是否使用正確的模型

請確認您使用的是模型頁面中列出的支援模型。

安全性問題

如果您發現提示訊息因 API 呼叫中的安全設定而遭到封鎖，請根據您在 API 呼叫中設定的篩選條件，查看提示訊息。

如果您看到 BlockedReason.OTHER，表示查詢或回應可能違反服務條款，或不受支援。

引用內容侵權問題

如果您發現模型因「背誦」原因而停止產生輸出內容，表示模型輸出內容可能與特定資料相似。如要修正這個問題，請盡可能讓提示 / 情境保持不重複，並使用較高的溫度。

改善模型輸出

如要獲得品質更高的模型輸出內容，請嘗試編寫結構更明確的提示。提示工程指南頁面會介紹一些基本概念、策略和最佳做法，協助您快速上手。

如果您有數百個良好輸入/輸出組合的範例，也可以考慮調整模型。

瞭解符記限制

詳閱符記指南，進一步瞭解如何計算符記及其限制。

已知問題

這個 API 僅支援部分語言。使用不支援的語言提交提示，可能會產生非預期的回應，甚至遭到封鎖。如需最新資訊，請參閱支援的語言。

回報錯誤

如有任何疑問，歡迎加入 Google AI 開發人員論壇的討論。