Cómo contar tokens para los modelos de Gemini

Los modelos de Gemini procesan la entrada y la salida en unidades llamadas tokens.

Los tokens pueden ser caracteres individuales, como z, o palabras completas, como cat. Las palabras largas se dividen en varios tokens. El conjunto de todos los tokens que usa el modelo se llama vocabulario, y el proceso de dividir el texto en tokens se llama tokenización.

En el caso de los modelos de Gemini, un token equivale a cerca de 4 caracteres. 100 tokens equivalen a entre 60 y 80 palabras en inglés.

Cada modelo tiene una cantidad máxima de tokens que puede manejar en una instrucción y una respuesta. Conocer el recuento de tokens de tu instrucción te permite saber si superaste este límite. Además, el costo de una solicitud se determina, en parte, por la cantidad de tokens de entrada y salida, por lo que puede ser útil saber cómo contar tokens.

Modelos compatibles

  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (y la versión anterior gemini-3.1-flash-lite)
  • gemini-nano-banana-2.1 (Nano Banana 2.1)
  • gemini-3.1-flash-image (Nano Banana 2)
  • gemini-3.1-flash-lite-image (Nano Banana 2 Lite)
  • gemini-3-pro-image (Nano Banana Pro)
  • gemini-3.1-flash-tts-preview

Los modelos Gemini 3.x Flash y Gemini 2.5 de uso general más antiguos admiten esta capacidad, pero ya no se recomienda su uso debido a las próximas fechas de cierre o al enrutamiento automático a modelos más nuevos.

Opciones para contar tokens

Todas las entradas y salidas de Gemini API se asignan con token, incluidos el texto, los archivos de imagen y otras modalidades que no son de texto. Estas son las opciones para contar tokens:

Verifica el recuento de tokens solo para tus solicitudes (antes de enviarlas al modelo).
Llama a countTokens con la entrada de la solicitud antes de enviarla al modelo. Esto devuelve lo siguiente:
  • total_tokens: recuento de tokens de la entrada únicamente
Verifica el recuento de tokens tanto para tus solicitudes como para tus respuestas.
Accede al atributo usageMetadata en el objeto de respuesta. Esto incluye lo siguiente:
  • prompt_token_count: Recuento de tokens solo de la entrada
  • candidates_token_count: Es el recuento de tokens solo de la salida (no incluye los tokens de razonamiento).
  • thoughts_token_count: Es el recuento de tokens de razonamiento que se usaron para generar la respuesta.
  • total_token_count: Es el recuento total de tokens para ambos, la entrada y la salida (incluye los tokens de razonamiento).

Cuando se transmite el resultado, el atributo usageMetadata solo aparece en el último fragmento de la transmisión. Es nil para los fragmentos intermedios.

Ten en cuenta los siguientes puntos sobre las opciones anteriores:

  • No contarán la cantidad de imágenes de entrada ni la cantidad de segundos en los archivos de entrada de video o audio. Sin embargo, el recuento de tokens para cada una de estas modalidades se correlacionará con estos valores.
  • El recuento de tokens de entrada incluye la instrucción (texto y cualquier archivo de entrada), así como las instrucciones y herramientas del sistema.
  • El recuento de tokens de salida no incluye ningún token de razonamiento, ya que estos se proporcionan en un campo separado.
  • Revisa la información adicional específica para cada tipo de solicitud más adelante en esta página.
  • Los modelos Gemini Live API no admiten countTokens. Además, Firebase AI Logic todavía no admite ese atributo usageMetadata en la respuesta de los modelos de Live API, ¡pero próximamente!

Precios de estas opciones

  • Llamadas a countTokens: No se aplican cargos por llamar a countTokens (la API de Count Tokens). La cuota máxima para la API de Count Tokens es de 3,000 solicitudes por minuto (RPM).

  • Usa el atributo usageMetadata: Este atributo siempre se devuelve como parte de la respuesta y no genera tokens ni cargos por sí mismo.

Información adicional

Aquí encontrarás información adicional para trabajar con tipos específicos de solicitudes.

Cuenta los tokens de entrada de texto

No hay información adicional.

Cuenta tokens de varios turnos (chat)

Ten en cuenta lo siguiente para llamar a countTokens cuando uses el chat:

  • Si llamas a countTokens con el historial de chat, se devuelve el recuento total de tokens de ambos roles en el chat (total_tokens).
  • Para comprender qué tan grande será tu próximo turno de conversación, debes adjuntarlo al historial cuando llames a countTokens.

Cuenta los tokens de entrada multimodales

Ten en cuenta los siguientes puntos sobre el recuento de tokens con entrada multimodal:

  • De manera opcional, puedes llamar a countTokens en el texto y el archivo por separado.
  • Para ambas opciones de recuento de tokens, obtendrás el mismo recuento de tokens, ya sea que proporciones el archivo como datos intercalados o con su URL.

Archivos de entrada de imágenes

Los archivos de entrada de imagen se convierten en tokens según sus dimensiones:

  • Entradas de imagen con ambas dimensiones menores o iguales que 384 píxeles: cada imagen se cuenta como 258 tokens.
  • Entradas de imagen que son más grandes en una o ambas dimensiones: cada imagen se recorta y escala según sea necesario en mosaicos de 768 × 768 píxeles, y, luego, cada mosaico se cuenta como 258 tokens.

Archivos de entrada de video y audio

Los archivos de entrada de video y audio se convierten en tokens con las siguientes tasas fijas:

  • Video: 263 tokens por segundo
  • Audio: 32 tokens por segundo

Archivos de entrada de documentos (como PDFs)

Los archivos de entrada en formato PDF se tratan como imágenes, por lo que cada página de un PDF se asigna con tokens de la misma manera que una imagen.