이 가이드를 사용하여 Gemini API를 호출할 때 발생하는 일반적인 문제를 진단하고 해결하세요. API 키 문제가 발생하면 API 키 설정 가이드에 따라 API 키를 올바르게 설정했는지 확인하세요.
오류 코드
다음 표에는 발생할 수 있는 일반적인 오류 코드와 그 원인 및 문제 해결 단계에 관한 설명이 나와 있습니다.
| HTTP 코드 | 상태 | 설명 | 해결 방법 |
| 400 | INVALID_ARGUMENT | 요청 본문의 형식이 잘못되었습니다. | API 참조에서 요청 형식, 예시, 지원되는 버전을 확인하세요. 이전 엔드포인트가 있는 최신 API 버전의 기능을 사용하면 오류가 발생할 수 있습니다. |
| 403 | PERMISSION_DENIED | API 키에 필요한 권한이 없습니다. | API 키가 설정되어 있고 올바른 액세스 권한이 있는지 확인하세요. |
| 404 | NOT_FOUND | 요청한 리소스를 찾을 수 없습니다. | 요청의 모든 매개변수가 API 버전에 유효한지 확인합니다. |
| 429 | RESOURCE_EXHAUSTED | 트래픽 제한을 초과했습니다. | 모델의 비율 한도 내에 있는지 확인합니다. 필요한 경우 할당량 증가를 요청합니다. |
| 500 | 내부 | Google 측에서 예기치 않은 오류가 발생했습니다. | 잠시 후 요청을 다시 시도해 주세요. 다시 시도한 후에도 문제가 지속되면 Google AI 스튜디오의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요. |
| 503 | 현재 구매할 수 없음 | 서비스가 일시적으로 과부하 상태이거나 다운되었을 수 있습니다. | 잠시 후 요청을 다시 시도해 주세요. 다시 시도한 후에도 문제가 지속되면 Google AI 스튜디오의 의견 보내기 버튼을 사용하여 문제를 신고해 주세요. |
API 호출에서 모델 매개변수 오류 확인
모델 매개변수가 다음 값 내에 있는지 확인합니다.
| 모델 매개변수 | 값 (범위) |
| 후보자 수 | 1~8 (정수) |
| 온도 | 0.0~1.0 |
| 최대 출력 토큰 |
get_model (Python)을 사용하여 사용 중인 모델의 최대 토큰 수를 결정합니다.
|
| TopP | 0.0~1.0 |
매개변수 값 확인 외에도 올바른 API 버전 (예: /v1 또는 /v1beta) 및 필요한 기능을 지원하는 모델을 구별합니다. 예를 들어 베타 출시 상태인 기능은 /v1beta API 버전에서만 사용할 수 있습니다.
올바른 모델인지 확인
지원되는 모델을 사용하고 있는지 확인하세요. list_models(Python)을 사용하여 사용 가능한 모든 모델을 가져옵니다.
안전 문제
API 호출의 안전 설정으로 인해 프롬프트가 차단된 경우 API 호출에서 설정한 필터와 관련하여 프롬프트를 검토하세요.
BlockedReason.OTHER가 표시되면 쿼리 또는 응답이 서비스 약관을 위반하거나 지원되지 않는 것일 수 있습니다.
모델 출력 개선
모델 출력을 개선하려면 보다 구조화된 프롬프트를 작성해 보세요. 프롬프트 설계 소개 페이지에서는 시작하는 데 도움이 되는 몇 가지 기본 개념, 전략, 권장사항을 소개합니다.
적절한 입력/출력 쌍의 예가 수백 개 있을 경우 모델 조정을 고려할 수도 있습니다.
토큰 한도 이해
ModelService API를 사용하여 입력 및 출력 토큰 한도를 포함한 모델에 대한 추가 메타데이터를 가져옵니다.
프롬프트에 사용된 토큰을 가져오려면 채팅 모델의 경우 countMessageTokens를, 텍스트 모델의 경우 countTextTokens를 사용합니다.
알려진 문제
- Google AI Studio에 대한 모바일 지원: 모바일에서 웹사이트를 열 수 있지만 작은 화면에 최적화되어 있지는 않습니다.
- API는 영어만 지원합니다. 여러 언어로 프롬프트를 제출하면 예상치 못한 답변이나 차단되는 응답이 발생할 수 있습니다. 업데이트는 사용 가능한 언어를 참고하세요.
버그 신고
GitHub에서 문제를 신고하여 질문을 하거나 기능 요청 또는 버그를 제출하세요.