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

Conteo de tokens

Obtén conteos precisos de tokens de entrada antes de enviar solicitudes.

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

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

El punto de acceso de conteo de tokens de entrada acepta el mismo formato de entrada que la API Responses. Envía texto, mensajes, imágenes, archivos, herramientas o conversaciones. La API devuelve la cantidad exacta de tokens que recibirá el modelo.

El conteo incluye tokens de formato que se usan para representar la estructura de la solicitud, como los roles y los límites de los mensajes. Es posible que estos tokens no aparezcan en el texto o los campos que tokenizas localmente.

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

Los tokenizadores locales como tiktoken funcionan con texto sin formato, pero tienen limitaciones:

  • No admiten imágenes ni archivos ; las estimaciones como characters / 4 son imprecisas
  • Las herramientas y los esquemas agregan tokens que son difíciles de contar localmente
  • El comportamiento específico del modelo puede cambiar la tokenización (por ejemplo, el razonamiento o el almacenamiento en caché)

La API de conteo de tokens contempla todos estos casos. Usa el mismo cuerpo de solicitud que enviarías a responses.create y obtén un conteo preciso. Luego incorpora el resultado a tu flujo de validación de mensajes o estimación de 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 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 con imágenes

Las imágenes consumen tokens según su tamaño y nivel de detalle. La API de conteo de tokens devuelve el conteo exacto, sin conjeturas.

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 archivos) o image_url (una URL o una URL de datos en base64). Consulta Imágenes y visión para obtener más detalles.

Contar tokens con herramientas

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

Entrada con herramientas de 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 con archivos

Se admiten archivos de entrada (actualmente, archivos PDF). Envía file_id, file_url o file_data como lo harías para responses.create. El conteo de tokens refleja la totalidad de la entrada procesada del modelo.

Entender los conteos de tokens de salida

El uso de tokens de salida reportado incluye todos los tokens generados por el modelo, no solo el texto visible en una respuesta. La API Responses reporta este total como output_tokens, mientras que la API para completar chats lo reporta como completion_tokens.

Algunos modelos, incluidos los modelos GPT-5, generan tokens que se usan para dar formato o delimitar los canales de respuesta, las llamadas a herramientas y otros elementos de la estructura del mensaje. Estos tokens de formato no aparecen en el contenido del mensaje ni en logprobs, y no necesariamente se desglosan por separado en los datos de uso. Por eso, el conteo reportado de tokens de salida o de completado puede ser mayor que la cantidad de tokens visibles o de tokens incluidos en logprobs, incluso cuando el valor reportado de reasoning_tokens es 0.

Los parámetros max_output_tokens y max_completion_tokens limitan todos los tokens generados por el modelo, incluidos los tokens no visibles. La cantidad de tokens no visibles varía según el modelo y la estructura de la respuesta, así que no supongas que hay una diferencia fija entre el uso reportado y la salida visible. Deja un margen en estos límites cuando necesites una cantidad específica de salida visible.

Referencia de la API

Para conocer 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 (entero) y object: "response.input_tokens".