토큰 수 세기

토큰 수 세기 (Count Tokens API)

프롬프트를 실제로 보내기 전에 '이 프롬프트가 토큰 몇 개쯤 되지' 궁금한 적 있으시죠? Vertex AI의 Count Tokens API가 바로 그 추정치를 알려 줘요. 이 글에서는 countTokens 메서드로 프롬프트·비디오 입력의 토큰 수를 세는 방법을 언어별 코드와 REST 엔드포인트로 정리해 드릴게요.

출처: Use the Count Tokens API — Gemini Enterprise Agent Platform | Google Cloud Documentation

주의할 점

멀티모달 입력(이미지·비디오·오디오)의 토큰 수는 추정치예요. 선택한 media_resolution에 따라 계산되기 때문에, countTokens API 결과가 최종 소비 토큰과 정확히 일치하지 않을 수 있어요.
공식 문서에서는 countTokens API 대신 Agent Platform SDK의 통합 토크나이저를 권장해요. SDK 안에서 토큰 목록과 수를 함께 얻을 수 있거든요.

지원 모델

Count Tokens API는 다음 모델들을 지원해요: Gemini Omni Flash preview, Gemini Omni 1.1 Flash preview, Gemini 3.8 Flash, Gemini 3.7 Flash, Gemini 3.6 Flash, Gemini 3.5 Flash-Lite, Gemini 3.5 Flash, Gemini 3.1 Pro preview, Gemini 3.1 Flash-Lite, Gemini 3.1 Flash Image, Gemini 3 Pro Image, Gemini 3 Flash preview, Gemini 2.5 Pro, Gemini 2.5 Flash-Lite, Gemini 2.5 Flash Image, Gemini 2.5 Flash.

프롬프트 토큰 수 세기

CountTokens의 입력 형식은 모델에 따라 달라요. 각 입력 형식은 Predict 입력 형식과 같아요.

Python

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.count_tokens(
    model="gemini-3.5-flash",
    contents="What's the highest mountain in Africa?",
)
print(response)  # 예: total_tokens ...

REST 엔드포인트

HTTP 메서드와 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:countTokens

요청 JSON 본문:

{
  "contents": [{
    "role": "ROLE",
    "parts": [{
      "text": "TEXT"
    }]
  }]
}

입력 텍스트와 함께 systemInstruction, tools, generationConfig 같은 필드도 body에 추가할 수 있어요.

비디오 입력 토큰 수 세기

비디오 입력의 토큰 수를 세려면 파일을 Part로 지정해요.

from google import genai
from google.genai.types import HttpOptions, Part
client = genai.Client(http_options=HttpOptions(api_version="v1"))

contents = [
    Part.from_uri(
        file_uri="gs://cloud-samples-data/generative-ai/video/pixel8.mp4",
        mime_type="video/mp4",
    ),
    "Provide a description of the video.",
]
response = client.models.count_tokens(model="gemini-2.5-flash", contents=contents)

토큰 수 세기