Endpoint de tokenización y herramientas
En esta página
Cuenta los tokens antes de enviar
Antes de cada llamada seria a la API surgen tres preguntas: ¿Cabe mi prompt en la ventana de contexto? ¿Cuánto costará? ¿Dónde corto si el documento es demasiado largo? Responder a esto después de enviar la solicitud, cuando ya ves un error o recibes la factura, siempre sale más caro que hacerlo con antelación. La API de Grok ofrece exactamente la herramienta para ello: un endpoint de tokenización, gratuito y desacoplado de las completaciones.
El endpoint /v1/tokenize-text
POST /v1/tokenize-text acepta texto sin formato y devuelve el recuento correspondiente de tokens. La característica clave se resume en una frase: a diferencia de una llamada de completación, este endpoint no consume tokens facturables. Cuenta; no genera.
curl -X POST "https://api.x.ai/v1/tokenize-text" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Tu texto para tokenizar aquí."
}'
La respuesta te ofrece el recuento total de tokens y, según la versión, el desglose de los tokens individuales. De esto se derivan directamente tres usos. Primero, la validación: verificas que la suma del prompt del sistema, el historial y el mensaje del usuario se mantenga dentro de la ventana del modelo objetivo: 1 millón de tokens en grok-4.3 y 500.000 en grok-4.5. Luego, la estimación de costes: el número resultante, multiplicado por la tarifa del modelo, te da el precio de la solicitud antes de comprometerte. Por último, el truncamiento: para un documento de tamaño excesivo, la tokenización te muestra dónde cortar limpiamente en lugar de dejar que la API rechace todo el conjunto.
La herramienta visual de la consola
Para la creación de prototipos, xAI ofrece un tokenizador visual en su consola web donde pegas el texto y ves inmediatamente su desglose. Es una herramienta didáctica excelente; úsala al menos una vez antes de diseñar tus plantillas de prompts.
Allí harás tres observaciones útiles. El francés genera significativamente más tokens que el inglés para contenidos semánticamente idénticos, lo que impacta directamente en el coste de una aplicación en francés. El código fuente se divide según una lógica distinta a la del texto natural. Y la puntuación o los caracteres especiales suelen ocupar un token por sí solos, lo que explica por qué un JSON verboso cuesta sorprendentemente mucho transmitir.
Dónde colocar el recuento en una canalización
Cuidado con el reflejo de tokenizar sistemáticamente antes de cada llamada: duplicas el número de solicitudes de red y añades latencia a cada interacción, para obtener información que a menudo ya conocías. Reserva el recuento exacto para los casos en los que la incertidumbre es real.
Para todo lo demás, basta con una estimación. Cuenta aproximadamente 1,5 tokens por palabra en francés, unos 0,3 tokens por carácter de código y entre 256 y 1.792 tokens por imagen dependiendo de su tamaño. Estos órdenes de magnitud, aplicados del lado del cliente, te permiten rechazar localmente un prompt manifiestamente fuera de límites sin consumir una llamada.
Guarda el endpoint entonces para tres situaciones: prompts cuyo tamaño varía ampliamente, típicamente documentos proporcionados por el usuario o fragmentos recuperados por un sistema RAG; la calibración inicial de tus plantillas, cuando estableces de una vez por todas el presupuesto de tokens para cada bloque de construcción; y la depuración, cuando aparece un error de desbordamiento de contexto y necesitas identificar qué elemento causó la hinchazón.
Herramientas integradas, un concepto aparte
Los tokens no son la única fuente de coste. Las herramientas integradas de la API se facturan por llamada, independientemente del volumen de texto intercambiado.
| Herramienta | Tarifa |
|---|---|
| Web Search | 5 $ por 1.000 llamadas |
| X Search | 5 $ por 1.000 llamadas |
| Code Execution | 5 $ por 1.000 llamadas |
| File Attachments | 10 $ por 1.000 llamadas |
| Collections Search | 2,50 $ por 1.000 llamadas |
Haz los números con tu propio tráfico antes de generalizar una herramienta. Una aplicación que activa una búsqueda web en cada solicitud paga 5 $ por cada mil interacciones solo por la herramienta, lo que frecuentemente supera el coste de los tokens consumidos en el mismo periodo. La búsqueda web no es superflua, pero debe activarse bajo condición y no por defecto.
Puntos clave para recordar
- El endpoint
POST /v1/tokenize-textte permite contar tokens sin facturación - La consola web de tokenización es útil para crear prototipos y entender el tokenizador
- No llames al endpoint de tokenización en cada solicitud en producción: usa estimaciones
- Las herramientas integradas (Web Search, Code Execution, etc.) tienen costes adicionales por llamada
- El francés consume una media de unos 1,5 tokens por palabra