Claude Platform Docs
MessagesGestión de contexto

Conteo de tokens

Cuenta los tokens de un mensaje antes de enviarlo a Claude. Usa los conteos de tokens para gestionar los límites de velocidad y los costos, tomar decisiones de enrutamiento de modelos y ajustar los prompts a una longitud objetivo.

El "token counting" (conteo de tokens) te permite determinar la cantidad de tokens en un mensaje antes de enviarlo a Claude. Esto te ayuda a tomar decisiones informadas sobre tus prompts y tu uso. Con el conteo de tokens, puedes:

  • Gestionar de forma proactiva los "rate limits" (límites de velocidad) y los costos
  • Tomar decisiones inteligentes de enrutamiento de modelos
  • Optimizar los prompts para una longitud específica

Cómo contar los tokens de un mensaje

El endpoint de conteo de tokens acepta la misma lista estructurada de entradas que se usa para crear un mensaje, incluyendo soporte para "system prompts" (indicaciones del sistema), herramientas, imágenes y PDFs. La respuesta contiene el número total de tokens de entrada.

Este endpoint devuelve un invalid_request_error para algunas entradas que la Messages API sí acepta: las herramientas de servidor, como la búsqueda web, la obtención web, la ejecución de código y la búsqueda de herramientas (todas las herramientas de servidor excepto la herramienta advisor), el conector MCP y los bloques image o document con una fuente url o file. Envía las imágenes y los PDFs en base64 para contarlos. Para las solicitudes que usan herramientas de servidor o servidores MCP, la respuesta de la Messages API informa los tokens usados en su objeto usage.

Modelos compatibles

Todos los modelos activos admiten el conteo de tokens.

Contar tokens en mensajes básicos

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    system="You are a scientist",
    messages=[{"role": "user", "content": "Hello, Claude"}],
)

print(response.json())
Output
{ "input_tokens": 14 }

Contar tokens en mensajes con herramientas

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    }
                },
                "required": ["location"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response.json())
Output
{ "input_tokens": 403 }

Contar tokens en mensajes con imágenes

import base64
import httpx2

image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "Describe this image"},
            ],
        }
    ],
)
print(response.json())
Output
{ "input_tokens": 1028 }

Un bloque de imagen incrustado que establece "oversized_image": "error" se rechaza en el momento del conteo exactamente como lo rechazaría la Messages API.

Contar tokens en mensajes con pensamiento

client = anthropic.Anthropic()

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "thinking",
                    "thinking": "This is a nice number theory question. Let's think about it step by step...",
                    "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",
                },
                {
                    "type": "text",
                    "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",
                },
            ],
        },
        {"role": "user", "content": "Can you write a formal proof?"},
    ],
)

print(response.json())
Output
{ "input_tokens": 88 }

Contar tokens en mensajes con PDFs

import base64
import anthropic

client = anthropic.Anthropic()

with open("/path/to/document.pdf", "rb") as pdf_file:
    pdf_base64 = base64.standard_b64encode(pdf_file.read()).decode("utf-8")

response = client.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                },
                {"type": "text", "text": "Please summarize this document."},
            ],
        }
    ],
)

print(response.json())
Output
{ "input_tokens": 2188 }

Conteos de tokens en los modelos Claude Fable y Claude Mythos

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 y Claude Mythos 5 comparten el tokenizador introducido con Claude Opus 4.7. Un prompt cuenta lo mismo en los cuatro, y aproximadamente un 30 por ciento más que en los modelos anteriores a Claude Opus 4.7 (el aumento exacto depende del contenido). El endpoint de conteo de tokens cuenta según el tokenizador del model que pases. Para medir la diferencia en tu carga de trabajo, cuenta la misma solicitud dos veces, una con tu modelo actual y otra con el modelo al que planeas migrar, y compara los dos valores de input_tokens.


Precios y límites de velocidad

El conteo de tokens es gratuito, pero está sujeto a límites de velocidad de solicitudes por minuto según tu nivel de uso. Si necesitas límites más altos, usa Request rate limit increase en la página de Límites de velocidad.

Nivel de usoSolicitudes por minuto (RPM)
Start5,000
Build10,000
Scale20,000

Preguntas frecuentes


Próximos pasos

Lee la referencia completa de la API para el endpoint de conteo de tokens.

Usa los conteos de tokens para mantener los prompts dentro de la ventana de contexto de un modelo.

Verifica los conteos de tokens antes de enviar una solicitud para mantenerte dentro de tu nivel de uso.

Reduce el costo y la latencia en prompts repetidos almacenando en caché los prefijos de los prompts.

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?