For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal
Theme

Conteo de tokens

Obtén el número exacto de tokens de entrada antes de enviar tus solicitudes.

El conteo de tokens te permite saber cuántos tokens de entrada usará una solicitud antes de enviarla al modelo. Úsalo para:

  • Optimizar los prompts para que se ajusten a los límites de contexto
  • Estimar los costos antes de hacer llamadas a la API
  • Dirigir las solicitudes según su tamaño (por ejemplo, enviar los prompts más cortos a modelos más rápidos)
  • Evitar sorpresas con las imágenes y los archivos sin tener que hacer estimaciones basadas en el número de caracteres

El punto de acceso para contar tokens de entrada acepta el mismo formato de entrada que la API de Responses. Envía texto, mensajes, imágenes, archivos, herramientas o conversaciones. La API devuelve el número exacto de tokens que recibirá el modelo.

El conteo incluye los tokens de formato que representan la estructura de la solicitud, como los roles de los mensajes y los límites entre ellos. Es posible que estos tokens no aparezcan en el texto ni en los campos que tokenizas localmente.

¿Por qué usar la API de conteo de tokens?

Los tokenizadores locales como tiktoken funcionan con texto plano, pero tienen algunas limitaciones:

  • Imágenes y archivos: los tokenizadores locales no los admiten y las estimaciones como characters / 4 son imprecisas
  • Herramientas y esquemas: agregan tokens que son difíciles de contar localmente
  • Comportamiento específico de cada modelo: funciones como el razonamiento o el almacenamiento en caché pueden cambiar la tokenización

La API de conteo de tokens tiene en cuenta todos estos casos. Envía los mismos datos que enviarías a responses.create para obtener un conteo exacto. Luego usa el resultado para validar mensajes o estimar costos.

Contar tokens en mensajes básicos

Entrada de texto simple
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra", input="Tell me a joke."
)
print(response.input_tokens)

Contar tokens en conversaciones

Conversación de varios turnos
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {"role": "user", "content": "What is 2 + 2?"},
        {"role": "assistant", "content": "2 + 2 equals 4."},
        {"role": "user", "content": "What about 3 + 3?"},
    ],
)
print(response.input_tokens)

Contar tokens en entradas con instrucciones

Entrada con instrucciones del sistema
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    instructions="You are a helpful assistant that explains concepts simply.",
    input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)

Contar tokens en entradas con imágenes

La cantidad de tokens que consume una imagen depende de su tamaño y nivel de detalle. La API de conteo de tokens devuelve la cantidad exacta sin necesidad de estimarla.

Entrada con una imagen
from openai import OpenAI

client = OpenAI()

# Use file_id from uploaded file, or image_url for a URL
response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": "https://example.com/chart.png",
                },
                {"type": "input_text", "text": "Summarize this chart."},
            ],
        }
    ],
)
print(response.input_tokens)

Puedes usar file_id (de la API de Files) o image_url (una URL o una URL de datos en base64). Para obtener más información, consulta la guía de imágenes y visión.

Contar tokens en entradas con herramientas

Las definiciones de herramientas (esquemas de funciones, servidores MCP, etc.) agregan tokens al contexto. Cuéntalos junto con los tokens de tu entrada:

Entrada con herramientas de tipo función
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)
print(response.input_tokens)

Contar tokens en entradas con archivos

La API admite archivos como entrada (por el momento, solo PDF). Envía file_id, file_url o file_data como lo harías con responses.create. El conteo de tokens refleja toda la entrada que procesa el modelo.

Interpretar el conteo de tokens de salida

El uso de tokens de salida que informa la API incluye todos los tokens que genera el modelo, incluso los que no aparecen en el texto visible de la respuesta. La API de Responses informa este total en output_tokens y la API para completar chats lo informa en completion_tokens.

Algunos modelos, entre ellos los de la familia GPT-5, generan tokens para dar formato a los canales de respuesta, las llamadas a herramientas y otros elementos de la estructura del mensaje, o para delimitarlos. Estos tokens de formato no aparecen en el contenido del mensaje ni en logprobs, y el informe de uso no siempre los desglosa por separado. Por eso, el total de tokens de salida que informa cada API puede superar la cantidad de tokens visibles o la de tokens incluidos en logprobs, incluso cuando el valor informado de reasoning_tokens es 0.

Los parámetros max_output_tokens y max_completion_tokens limitan el total de tokens que genera el modelo, incluidos los que no son visibles. La cantidad de tokens no visibles varía según el modelo y la estructura de la respuesta, así que no supongas que la diferencia entre el uso informado y la salida visible es fija. Deja un margen al configurar estos límites cuando necesites una cantidad específica de salida visible.

Referencia de la API

Para ver todos los parámetros y la estructura de la respuesta, consulta la referencia de la API para contar tokens de entrada. El punto de acceso es:

POST /v1/responses/input_tokens

La respuesta incluye input_tokens (un número entero) y object: "response.input_tokens".