핵심 요약

Google Gemini API v1beta는 긴 텍스트를 전송하기 전 countTokens API로 입력 토큰 수를 확인한다. 생성 요청 후 응답 내부 usageMetadata에서 입력 토큰(promptTokenCount), 출력 토큰(candidatesTokenCount), 전체 사용량(totalTokenCount)을 구분하여 확인할 수 있다.

토큰 수 확인 절차

  1. 입력 토큰 수 사전 측정
  • POST /v1beta/models/{model}:countTokens에 입력 텍스트(JSON 형태)를 보내고
  • 응답 최상위 totalTokens 필드에서 입력 텍스트의 토큰 수를 획득한다.
  • {model}은 생성에 사용할 실제 모델 ID를 지정한다.
  1. 생성 응답에서 토큰 수 확인
  • 동일한 모델과 텍스트로 POST /v1beta/models/{model}:generateContent 호출
  • 응답의 usageMetadata 내 promptTokenCount: 입력(프롬프트) 토큰 수
  • candidatesTokenCount: 생성된 응답 후보들의 토큰 수 총합
  • totalTokenCount: 프롬프트, 응답 후보, 도구 사용 프롬프트, 내부 모델 사고 토큰 등 전체 토큰 사용량
  1. 입력 텍스트 변경 후 재측정
  • 입력에 새로운 문단 추가 시 countTokens를 다시 호출하여 토큰 수 변화를 비교

실무 유의점

  • countTokens는 실제 API 호출 전 입력 토큰 수 예측에 유용하다.
  • 생성 응답 후 usageMetadata의 토큰 수 정보를 참고하면 입력과 출력 각각의 토큰 소비량을 명확히 파악할 수 있다.
  • totalTokenCount는 단순한 입력+출력 토큰 합이 아니며, 내부 처리용 토큰도 포함한다는 점에 유의한다.

1차 출처