Ya llegó Gemini 3 Flash. Pruébalo gratis en Google AI Studio.

Se usó la API de Cloud Translation para traducir esta página.

Comprender y contar tokens

Gemini y otros modelos de IA generativa procesan la entrada y la salida con una granularidad llamada token.

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

Acerca de los 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 denomina vocabulario, y el proceso de dividir el texto en tokens se denomina tokenización.

Cuando la facturación está habilitada, el costo de una llamada a la API de Gemini se determina, en parte, por la cantidad de tokens de entrada y salida, por lo que saber cómo contarlos puede ser útil.

Prueba a contar tokens en un Colab

Puedes probar el recuento de tokens con un Colab.

Ver en ai.google.dev

Probar un notebook de Colab

Ver el notebook en GitHub

Ventanas de contexto

Los modelos disponibles a través de la API de Gemini tienen ventanas de contexto que se miden en tokens. La ventana de contexto define la cantidad de entrada que puedes proporcionar y la cantidad de salida que puede generar el modelo. Puedes determinar el tamaño de la ventana de contexto llamando al extremo getModels o consultando la documentación de los modelos.

En el siguiente ejemplo, puedes ver que el modelo gemini-2.0-flash tiene un límite de entrada de aproximadamente 1,000,000 de tokens y un límite de salida de aproximadamente 8,000 tokens, lo que significa que una ventana de contexto es de 1,000,000 de tokens.

from google import genai

client = genai.Client()
model_info = client.models.get(model="gemini-2.0-flash")
print(f"{model_info.input_token_limit=}")
print(f"{model_info.output_token_limit=}")
# ( e.g., input_token_limit=30720, output_token_limit=2048 )count_tokens.py

Cuenta tokens

Todas las entradas y salidas de la API de Gemini se tokenizan, incluidos los archivos de texto y de imagen, y otras modalidades que no son de texto.

Puedes contar tokens de las siguientes maneras:

Llama a count_tokens con la entrada de la solicitud.
Esto devuelve la cantidad total de tokens solo en la entrada. Puedes realizar esta llamada antes de enviar la entrada al modelo para verificar el tamaño de tus solicitudes.
Usa el atributo usage_metadata en el objeto response después de llamar a generate_content.
Esto devuelve la cantidad total de tokens en la entrada y la salida: total_token_count.
También devuelve los recuentos de tokens de entrada y salida por separado: prompt_token_count (tokens de entrada) y candidates_token_count (tokens de salida).

Si usas un modelo de pensamiento, como los de la versión 2.5, los tokens que se usan durante el proceso de pensamiento se devuelven en thoughts_token_count. Además, si usas almacenamiento en caché de contexto, el recuento de tokens almacenados en caché estará en cached_content_token_count.

Cómo contar tokens de texto

Si llamas a count_tokens con una entrada solo de texto, se muestra el recuento de tokens del texto solo en la entrada (total_tokens). Puedes realizar esta llamada antes de llamar a generate_content para verificar el tamaño de tus solicitudes.

Otra opción es llamar a generate_content y, luego, usar el atributo usage_metadata en el objeto response para obtener lo siguiente:

Las cantidades de tokens separadas de la entrada (prompt_token_count), el contenido almacenado en caché (cached_content_token_count) y la salida (candidates_token_count)
Recuento de tokens para el proceso de pensamiento (thoughts_token_count)
La cantidad total de tokens en la entrada y la salida (total_token_count)

from google import genai

client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."

# Count tokens using the new client method.
total_tokens = client.models.count_tokens(
    model="gemini-2.0-flash", contents=prompt
)
print("total_tokens: ", total_tokens)
# ( e.g., total_tokens: 10 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=prompt
)

# The usage_metadata provides detailed token counts.
print(response.usage_metadata)
# ( e.g., prompt_token_count: 11, candidates_token_count: 73, total_token_count: 84 )count_tokens.py

Cómo contar tokens de chat de varios turnos

Si llamas a count_tokens con el historial de chat, se muestra el recuento total de tokens del texto de cada rol en el chat (total_tokens).

Otra opción es llamar a send_message y, luego, usar el atributo usage_metadata en el objeto response para obtener lo siguiente:

Las cantidades de tokens separadas de la entrada (prompt_token_count), el contenido almacenado en caché (cached_content_token_count) y la salida (candidates_token_count)
Recuento de tokens para el proceso de pensamiento (thoughts_token_count)
La cantidad total de tokens en la entrada y la salida (total_token_count)

Para comprender qué tan grande será tu próximo turno de conversación, debes agregarlo al historial cuando llames a count_tokens.

from google import genai
from google.genai import types

client = genai.Client()

chat = client.chats.create(
    model="gemini-2.0-flash",
    history=[
        types.Content(
            role="user", parts=[types.Part(text="Hi my name is Bob")]
        ),
        types.Content(role="model", parts=[types.Part(text="Hi Bob!")]),
    ],
)
# Count tokens for the chat history.
print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=chat.get_history()
    )
)
# ( e.g., total_tokens: 10 )

response = chat.send_message(
    message="In one sentence, explain how a computer works to a young child."
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 25, candidates_token_count: 21, total_token_count: 46 )

# You can count tokens for the combined history and a new message.
extra = types.UserContent(
    parts=[
        types.Part(
            text="What is the meaning of life?",
        )
    ]
)
history = chat.get_history()
history.append(extra)
print(client.models.count_tokens(model="gemini-2.0-flash", contents=history))
# ( e.g., total_tokens: 56 )count_tokens.py

Cómo contar tokens multimodales

Todas las entradas a la API de Gemini se tokenizan, lo que incluye texto, archivos de imágenes y otras modalidades que no son de texto. Ten en cuenta los siguientes puntos clave de alto nivel sobre la tokenización de la entrada multimodal durante el procesamiento de la API de Gemini:

Con Gemini 2.0, las entradas de imágenes con ambas dimensiones <=384 píxeles se cuentan como 258 tokens. Las imágenes más grandes en una o ambas dimensiones se recortan y se ajustan según sea necesario en mosaicos de 768 × 768 píxeles, y cada uno se cuenta como 258 tokens. Antes de Gemini 2.0, las imágenes usaban 258 tokens fijos.
Los archivos de audio y video se convierten en tokens a las siguientes tarifas fijas: video a 263 tokens por segundo y audio a 32 tokens por segundo.

Resoluciones de medios

La versión preliminar de Gemini 3 Pro introduce un control detallado sobre el procesamiento de visión multimodal con el parámetro media_resolution. El parámetro media_resolution determina la cantidad máxima de tokens asignados por imagen de entrada o fotograma de video. Las resoluciones más altas mejoran la capacidad del modelo para leer texto pequeño o identificar detalles, pero aumentan el uso de tokens y la latencia.

Para obtener más detalles sobre el parámetro y cómo puede afectar los cálculos de tokens, consulta la guía de resolución de medios.

Archivos de imagen

Si llamas a count_tokens con una entrada de texto y una imagen, se muestra el recuento combinado de tokens del texto y la imagen solo en la entrada (total_tokens). Puedes realizar esta llamada antes de llamar a generate_content para verificar el tamaño de tus solicitudes. También puedes llamar a count_tokens en el texto y el archivo por separado.

Otra opción es llamar a generate_content y, luego, usar el atributo usage_metadata en el objeto response para obtener lo siguiente:

Las cantidades de tokens separadas de la entrada (prompt_token_count), el contenido almacenado en caché (cached_content_token_count) y la salida (candidates_token_count)
Recuento de tokens para el proceso de pensamiento (thoughts_token_count)
La cantidad total de tokens en la entrada y la salida (total_token_count)

Ejemplo que usa una imagen subida desde la API de File:

from google import genai

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = client.files.upload(file=media / "organ.jpg")

print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_image_file]
    )
)
# ( e.g., total_tokens: 263 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 264, candidates_token_count: 80, total_token_count: 345 )count_tokens.py

Ejemplo que proporciona la imagen como datos intercalados:

from google import genai
import PIL.Image

client = genai.Client()
prompt = "Tell me about this image"
your_image_file = PIL.Image.open(media / "organ.jpg")

# Count tokens for combined text and inline image.
print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_image_file]
    )
)
# ( e.g., total_tokens: 263 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_image_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 264, candidates_token_count: 80, total_token_count: 345 )count_tokens.py

Archivos de audio o video

El audio y el video se convierten en tokens a las siguientes tasas fijas:

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

Si llamas a count_tokens con una entrada de texto y video o audio, se devuelve el recuento combinado de tokens del texto y el archivo de video o audio solo en la entrada (total_tokens). Puedes realizar esta llamada antes de llamar a generate_content para verificar el tamaño de tus solicitudes. También puedes llamar a count_tokens en el texto y el archivo por separado de forma opcional.

Otra opción es llamar a generate_content y, luego, usar el atributo usage_metadata en el objeto response para obtener lo siguiente:

Las cantidades de tokens separadas de la entrada (prompt_token_count), el contenido almacenado en caché (cached_content_token_count) y la salida (candidates_token_count)
Recuento de tokens para el proceso de pensamiento (thoughts_token_count)
La cantidad total de tokens en la entrada y la salida (total_token_count)

from google import genai
import time

client = genai.Client()
prompt = "Tell me about this video"
your_file = client.files.upload(file=media / "Big_Buck_Bunny.mp4")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not your_file.state or your_file.state.name != "ACTIVE":
    print("Processing video...")
    print("File state:", your_file.state)
    time.sleep(5)
    your_file = client.files.get(name=your_file.name)

print(
    client.models.count_tokens(
        model="gemini-2.0-flash", contents=[prompt, your_file]
    )
)
# ( e.g., total_tokens: 300 )

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=[prompt, your_file]
)
print(response.usage_metadata)
# ( e.g., prompt_token_count: 301, candidates_token_count: 60, total_token_count: 361 )count_tokens.py

Instrucciones y herramientas del sistema

Las instrucciones y herramientas del sistema también se incluyen en el recuento total de tokens de la entrada.

Si usas instrucciones del sistema, el recuento de total_tokens aumenta para reflejar la adición de system_instruction.

Si usas la llamada a función, el recuento de total_tokens aumenta para reflejar la adición de tools.