토큰 이해 및 계산

Gemini 및 기타 생성형 AI 모델은 토큰이라는 세부사항으로 입력과 출력을 처리합니다.

Gemini 모델의 경우 토큰은 약 4자에 해당합니다. 토큰 100개는 영어 단어 약 60~80개에 해당합니다.

토큰 정보

토큰은 단일 문자(예: z) 또는 전체 단어(예: cat)일 수 있습니다. 긴 단어는 여러 토큰으로 나뉩니다. 모델에서 사용하는 모든 토큰 집합을 어휘라고 하며, 텍스트를 토큰으로 분할하는 프로세스를 토큰화라고 합니다.

결제가 사용 설정된 경우 Gemini API 호출 비용은 입력 및 출력 토큰 수에 따라 결정되므로 토큰 수를 세는 방법을 알아두면 유용합니다.


토큰 집계

텍스트, 이미지 파일, 기타 비텍스트 모달리티를 비롯한 Gemini API의 모든 입력과 출력은 토큰화됩니다.

다음과 같은 방법으로 토큰을 계산할 수 있습니다.

  • 요청의 입력으로 countTokens를 호출합니다.
    입력만의 총 토큰 수를 반환합니다. 모델에 입력을 전송하기 전에 이 호출을 실행하여 요청의 크기를 확인할 수 있습니다.

  • generate_content를 호출한 후 response 객체에서 usageMetadata 속성을 사용합니다.
    입력과 출력 모두의 총 토큰 수를 반환합니다(totalTokenCount).
    또한 입력 및 출력의 토큰 수를 별도로 반환합니다. promptTokenCount (입력 토큰) 및 candidatesTokenCount (출력 토큰) 컨텍스트 캐싱을 사용하는 경우 캐시된 토큰 수는 cachedContentTokenCount에 표시됩니다.

    2.5와 같은 사고 모델을 사용하는 경우 사고 과정에서 사용된 토큰이 thoughtsTokenCount에 반환됩니다.

텍스트 토큰 수 계산

텍스트 전용 입력으로 countTokens를 호출하면 입력만 (totalTokens)의 텍스트 토큰 수가 반환됩니다. generateContent를 호출하기 전에 이 호출을 실행하여 요청의 크기를 확인할 수 있습니다.

또 다른 방법은 generateContent을 호출한 다음 response 객체에서 usageMetadata 속성을 사용하여 다음을 가져오는 것입니다.

  • 입력 (promptTokenCount), 캐시된 콘텐츠 (cachedContentTokenCount), 출력 (candidatesTokenCount)의 별도 토큰 수
  • 사고 과정의 토큰 수 (thoughtsTokenCount)
  • 입력과 출력 모두의 총 토큰 수(totalTokenCount)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "The quick brown fox jumps over the lazy dog.";
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: prompt,
});
console.log(generateResponse.usageMetadata);

멀티턴 (채팅) 토큰 수 계산

채팅 기록과 함께 countTokens를 호출하면 채팅의 각 역할 (totalTokens)에서 텍스트의 총 토큰 수가 반환됩니다.

또 다른 방법은 sendMessage을 호출한 다음 response 객체에서 usageMetadata 속성을 사용하여 다음을 가져오는 것입니다.

  • 입력 (promptTokenCount), 캐시된 콘텐츠 (cachedContentTokenCount), 출력 (candidatesTokenCount)의 별도 토큰 수
  • 사고 과정의 토큰 수 (thoughtsTokenCount)
  • 입력과 출력 모두의 총 토큰 수(totalTokenCount)

다음 대화 턴의 크기를 파악하려면 countTokens를 호출할 때 기록에 추가해야 합니다.

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// Initial chat history.
const history = [
  { role: "user", parts: [{ text: "Hi my name is Bob" }] },
  { role: "model", parts: [{ text: "Hi Bob!" }] },
];
const chat = ai.chats.create({
  model: "gemini-2.0-flash",
  history: history,
});

// Count tokens for the current chat history.
const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: chat.getHistory(),
});
console.log(countTokensResponse.totalTokens);

const chatResponse = await chat.sendMessage({
  message: "In one sentence, explain how a computer works to a young child.",
});
console.log(chatResponse.usageMetadata);

// Add an extra user message to the history.
const extraMessage = {
  role: "user",
  parts: [{ text: "What is the meaning of life?" }],
};
const combinedHistory = chat.getHistory();
combinedHistory.push(extraMessage);
const combinedCountTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: combinedHistory,
});
console.log(
  "Combined history token count:",
  combinedCountTokensResponse.totalTokens,
);

멀티모달 토큰 수

텍스트, 이미지 파일, 기타 텍스트가 아닌 형식을 비롯한 Gemini API의 모든 입력은 토큰화됩니다. Gemini API에서 처리하는 동안 멀티모달 입력의 토큰화에 관한 다음 상위 수준 주요 사항에 유의하세요.

  • Gemini 2.0에서는 두 치수가 모두 384픽셀 이하인 이미지 입력이 258개의 토큰으로 계산됩니다. 한쪽 또는 양쪽 크기가 더 큰 이미지는 필요에 따라 768x768픽셀 타일로 잘리고 크기가 조정되며, 각 타일은 258개의 토큰으로 계산됩니다. Gemini 2.0 이전에는 이미지가 고정된 258개의 토큰을 사용했습니다.

  • 동영상 및 오디오 파일은 다음 고정 요율로 토큰으로 변환됩니다. 동영상은 초당 263개 토큰, 오디오는 초당 32개 토큰입니다.

미디어 해상도

Gemini 3 Pro 미리보기에서는 media_resolution 파라미터를 사용하여 멀티모달 비전 처리를 세부적으로 제어할 수 있습니다. media_resolution 파라미터는 입력 이미지 또는 동영상 프레임당 할당되는 최대 토큰 수를 결정합니다. 해상도가 높을수록 모델이 작은 텍스트를 읽거나 세부 요소를 식별하는 능력을 향상시키지만, 토큰 사용량과 지연 시간이 증가합니다.

파라미터 및 파라미터가 토큰 계산에 미치는 영향에 대한 자세한 내용은 미디어 해상도 가이드를 참고하세요.

이미지 파일

텍스트와 이미지 입력으로 countTokens를 호출하면 입력만 (totalTokens)에 텍스트와 이미지의 결합된 토큰 수가 반환됩니다. generateContent를 호출하기 전에 이 호출을 실행하여 요청의 크기를 확인할 수 있습니다. 선택적으로 텍스트와 파일에서 각각 countTokens을 호출할 수도 있습니다.

또 다른 방법은 generateContent을 호출한 다음 response 객체에서 usageMetadata 속성을 사용하여 다음을 가져오는 것입니다.

  • 입력 (promptTokenCount), 캐시된 콘텐츠 (cachedContentTokenCount), 출력 (candidatesTokenCount)의 별도 토큰 수
  • 사고 과정의 토큰 수 (thoughtsTokenCount)
  • 입력과 출력 모두의 총 토큰 수(totalTokenCount)

File API에서 업로드된 이미지를 사용하는 예:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const organ = await ai.files.upload({
  file: path.join(media, "organ.jpg"),
  config: { mimeType: "image/jpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(organ.uri, organ.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);

이미지를 인라인 데이터로 제공하는 예:

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this image";
const imageBuffer = fs.readFileSync(path.join(media, "organ.jpg"));

// Convert buffer to base64 string.
const imageBase64 = imageBuffer.toString("base64");

// Build contents using createUserContent and createPartFromBase64.
const contents = createUserContent([
  prompt,
  createPartFromBase64(imageBase64, "image/jpeg"),
]);

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(generateResponse.usageMetadata);

동영상 또는 오디오 파일

오디오와 동영상은 각각 다음 고정된 비율로 토큰으로 변환됩니다.

  • 동영상: 초당 토큰 263개
  • 오디오: 초당 토큰 32개

텍스트 및 동영상/오디오 입력으로 countTokens를 호출하면 입력만(totalTokens)에 있는 텍스트와 동영상/오디오 파일의 결합된 토큰 수가 반환됩니다. generateContent를 호출하기 전에 이 호출을 실행하여 요청의 크기를 확인할 수 있습니다. 선택적으로 텍스트와 파일에서 countTokens를 별도로 호출할 수도 있습니다.

또 다른 방법은 generateContent을 호출한 다음 response 객체에서 usageMetadata 속성을 사용하여 다음을 가져오는 것입니다.

  • 입력 (promptTokenCount), 캐시된 콘텐츠 (cachedContentTokenCount), 출력 (candidatesTokenCount)의 별도 토큰 수
  • 사고 과정의 토큰 수 (thoughtsTokenCount)
  • 입력과 출력 모두의 총 토큰 수(totalTokenCount)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const prompt = "Tell me about this video";
let videoFile = await ai.files.upload({
  file: path.join(media, "Big_Buck_Bunny.mp4"),
  config: { mimeType: "video/mp4" },
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!videoFile.state || videoFile.state.toString() !== "ACTIVE") {
  console.log("Processing video...");
  console.log("File state: ", videoFile.state);
  await sleep(5000);
  videoFile = await ai.files.get({ name: videoFile.name });
}

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);

const generateResponse = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    prompt,
    createPartFromUri(videoFile.uri, videoFile.mimeType),
  ]),
});
console.log(generateResponse.usageMetadata);

시스템 요청 사항 및 도구

시스템 안내와 도구도 입력의 총 토큰 수에 포함됩니다.

시스템 안내를 사용하면 systemInstruction 추가를 반영하여 totalTokens 수가 증가합니다.

함수 호출을 사용하는 경우 tools 추가를 반영하기 위해 totalTokens 수가 증가합니다.