Gemini API 토큰 수 확인하는 법

Gemini API에 보낼 입력의 크기는 client.models.count_tokens로 먼저 확인할 수 있습니다. 반환값은 입력 토큰 수이므로, 답변 생성 뒤의 전체 사용량과 구분하세요.

입력 크기 확인과 답변 생성을 나눈 AI 생성 개념도입니다. 실제 실행 화면이나 측정 결과가 아닙니다.

텍스트 요청부터 세기

아래는 Google Gen AI Python SDK를 사용하는 예시입니다. 현재 공식 가이드가 안내하는 2.0.0보다 최신 버전과 API 키가 설정된 환경을 전제로 합니다. 키는 코드에 적지 않고 GEMINI_API_KEY 환경변수로 준비합니다. 처음 설정한다면 공식 시작 가이드를 참고하세요.

from google import genai

client = genai.Client()
model = "gemini-3.8-flash"
prompt = "다음 회의록에서 결정 사항만 정리해 주세요."

count = client.models.count_tokens(
    model=model,
    contents=prompt,
)
print(count.total_tokens)

model은 실제 사용할 모델로, prompt는 실제 보낼 텍스트로 맞추세요. 예시는 현재 공식 문서의 모델명을 사용했습니다. 답변 생성 호출은 넣지 않았으며, 출력 숫자를 직접 측정한 예제는 아닙니다. 토큰 계산도 API 요청이므로 전송해도 되는 자료로 확인하세요.

Google 공식 문서의 토큰 집계 안내. 입력 사전 계산과 응답 사용량을 구분합니다.

출처: Google, 토큰 이해 및 계산. 텍스트 영역 일부 크롭, CC BY 4.0, 2026년 10월 24일 확인.

실제 요청과 같은 범위로 확인하기

위 코드는 텍스트만 셉니다. 나중에 이미지나 대화 기록을 더한다면 짧은 질문 한 줄을 센 값으로 전체 입력 크기를 판단하면 안 됩니다.

시스템 지침이나 도구 선언까지 포함하는 요청은 countTokens API 문서의 generateContentRequest 형식을 확인하세요. 이 경로와 model·contents를 함께 보내는 형식은 허용되지 않습니다. 같은 모델과 같은 입력 범위를 맞추는 것이 먼저입니다.

생성 후에는 응답의 사용량 보기

사용 중인 호출에 따라 읽을 필드가 다릅니다.

• interactions.create를 썼다면 반환된 interaction의 usage를 봅니다.
• models.generate_content를 썼다면 반환된 response의 usage_metadata를 봅니다.

앞의 count.total_tokens는 생성 전 입력만 센 값입니다. 생성 후 사용량에는 출력 등 다른 항목도 있으므로, 두 숫자를 같은 총량으로 놓고 비교하지 마세요. 새 코드의 필드명을 예전 호출에 그대로 붙이기보다 자신이 호출한 API의 응답 구조부터 확인하면 됩니다.

2026년 10월 24일 공식 문서 대조 기준입니다. 실제 API 호출·속도·비용 실험은 하지 않았습니다.