Gemini API 시작 전 점검: 모델·프로젝트 한도·오류별 대응

먼저 내 프로젝트에서 쓸 수 있는 모델 확인

Gemini API를 붙일 때 모델 이름과 호출 간격을 예전 글에서 그대로 복사하면 시작부터 오류가 날 수 있습니다. 이 글은 2026-09-23 공식 문서 확인을 바탕으로, 짧은 문장 정리 기능을 연결하기 전에 확인할 순서를 정리합니다. 특정 모델의 무료 제공이나 고정 호출 횟수를 보장하는 안내는 아닙니다.

Google AI Studio에서 사용할 프로젝트와 키를 확인한 뒤, 모델별 가격 안내에서 해당 모델의 입력·출력·추가 기능 비용과 무료 제공 여부를 확인합니다. Flash라는 이름만으로 모든 모델이 같은 가격·기능·한도를 가진다고 가정하지 않습니다.

모델과 키를 코드에서 분리한 예제

아래는 google-genai Python SDK의 models.generate_content를 사용하는 예제입니다. SDK 설치 후 실행 환경에 GEMINI_API_KEY와 GEMINI_MODEL을 설정합니다. 모델 값은 현재 프로젝트에서 사용할 수 있는 실제 식별자를 넣어야 합니다. 키는 소스에 쓰거나 공개 저장소에 올리지 않습니다.

python -m pip install google-genai

import os
from google import genai

api_key = os.environ.get("GEMINI_API_KEY", "").strip()
model_id = os.environ.get("GEMINI_MODEL", "").strip()
if not api_key or not model_id:
    raise SystemExit("API 키와 사용 가능한 모델 설정을 확인하세요.")

prompt = "다음 문장을 사실 추가 없이 한 문장으로 줄여줘: 회의는 수요일 오후 2시에 시작한다."
with genai.Client(api_key=api_key) as client:
    response = client.models.generate_content(
        model=model_id,
        contents=prompt,
    )
    result = response.text
    if not result or not result.strip():
        raise RuntimeError("텍스트 응답이 없습니다. 응답 상태를 확인하세요.")
    print(result.strip())

환경 변수를 바꾼 뒤에는 실행 중인 터미널이나 서비스를 새로 시작해야 반영되는 환경도 있습니다. 키가 설정됐는지 확인하려고 키 자체를 출력하지 않습니다. 위 코드는 설정 누락과 빈 텍스트를 구분하는 연결 예제이며, 실제 키를 사용한 호출 결과나 특정 SDK 버전의 동작을 보증하는 테스트 보고서는 아닙니다. 메서드 사용법은 공식 Python SDK를 기준으로 했습니다.

결과 문장은 매번 같을 필요가 없습니다. 대신 수요일, 오후 2시가 유지되고 원문에 없는 장소가 추가되지 않았는지 확인합니다. 최신 뉴스처럼 입력에 없는 사실을 모델이 알아서 확인했다고 간주하지 않습니다.

요청 수와 토큰 한도를 나누어 보기

프로젝트에는 분당 요청 수, 분당 토큰 수, 일일 요청 수처럼 서로 다른 한도가 적용될 수 있습니다. 키를 새로 만드는 것과 프로젝트의 사용 한도가 늘어나는 것은 다릅니다. 실제 적용값은 요청 제한 안내와 계정의 현재 사용량 화면에서 확인합니다.

예를 들어 짧은 요청을 여러 사용자가 동시에 보내는 경우와 긴 문서를 한 번 보내는 경우는 부딪히는 한도가 다를 수 있습니다. 고정적으로 3초나 5초 간격을 두면 항상 통과한다는 규칙은 없습니다. 요청 간격만 늘려도 일일 한도가 이미 소진된 상황은 바로 해결되지 않습니다.

실서비스에서는 같은 작업의 중복 전송을 막고, 요청 대기열과 사용자별 사용 제한을 둡니다. 입력 길이와 출력 한도도 작업에 맞게 정하되, 토큰 수를 정확한 한국어 글자 수와 동일하게 계산하지 않습니다.

오류별로 다음 행동 정하기

상태 코드만으로 원인을 단정하지 말고 구조화된 오류의 상태와 메시지를 확인합니다. SDK 자체 재시도가 적용되는 버전도 있으므로 앱에서 다시 반복문을 붙일 때는 전체 시도 횟수가 늘어나지 않게 점검합니다. 재시도 가능한 오류에는 대기 시간을 늘리되 최대 횟수를 두고, 잘못된 입력이나 권한 문제를 같은 요청으로 무한 반복하지 않습니다. 공식 오류 처리 안내를 함께 확인하세요.

전송할 데이터도 설정의 일부

무료·유료 구분만 보고 모든 입력이 같은 방식으로 처리된다고 생각하면 안 됩니다. Gemini API 추가 약관은 무료 서비스의 입력·응답 활용, 사람의 검토 가능성, 유료 서비스와 일부 지역의 다른 조건을 설명합니다. 결제 연결 상태와 적용 지역을 포함해 자신의 조건을 확인하고, 실습에는 공개 가능한 가상 문장을 사용합니다.

이 사이트의 글 초안에 활용할 때도 API 성공과 발행 가능한 글은 별도입니다. 요청이 성공했는지 확인한 다음 원문과 결과를 비교하고 사실을 검토합니다. 요청·응답을 직접 살펴보는 연습은 Postman 실습, 상품 정보와 작성자의 경험을 분리하는 방법은 상품 글 작성 보조 도구 기록에서 이어집니다.