핵심 요약
Google Gemini API v1beta는 긴 텍스트를 전송하기 전 countTokens API로 입력 토큰 수를 확인한다. 생성 요청 후 응답 내부 usageMetadata에서 입력 토큰(promptTokenCount), 출력 토큰(candidatesTokenCount), 전체 사용량(totalTokenCount)을 구분하여 확인할 수 있다.
토큰 수 확인 절차
- 입력 토큰 수 사전 측정
POST /v1beta/models/{model}:countTokens에 입력 텍스트(JSON 형태)를 보내고- 응답 최상위
totalTokens필드에서 입력 텍스트의 토큰 수를 획득한다. {model}은 생성에 사용할 실제 모델 ID를 지정한다.
- 생성 응답에서 토큰 수 확인
- 동일한 모델과 텍스트로
POST /v1beta/models/{model}:generateContent호출 - 응답의
usageMetadata내promptTokenCount: 입력(프롬프트) 토큰 수 candidatesTokenCount: 생성된 응답 후보들의 토큰 수 총합totalTokenCount: 프롬프트, 응답 후보, 도구 사용 프롬프트, 내부 모델 사고 토큰 등 전체 토큰 사용량
- 입력 텍스트 변경 후 재측정
- 입력에 새로운 문단 추가 시
countTokens를 다시 호출하여 토큰 수 변화를 비교
실무 유의점
countTokens는 실제 API 호출 전 입력 토큰 수 예측에 유용하다.- 생성 응답 후
usageMetadata의 토큰 수 정보를 참고하면 입력과 출력 각각의 토큰 소비량을 명확히 파악할 수 있다. totalTokenCount는 단순한 입력+출력 토큰 합이 아니며, 내부 처리용 토큰도 포함한다는 점에 유의한다.