Uso de tokens y reasoning_tokens
En esta página
Actualizado el 3 de noviembre de 2026. Según la referencia de la API de Chat Completions de xAI:
max_tokensestá obsoleto en favor demax_completion_tokens, que limita únicamente la respuesta visible. Fuente: Chat Completions.
Comprende la facturación por tokens
Cada solicitud a la API de Chat Completions se factura en función del número de tokens consumidos. El objeto usage de la respuesta te ofrece un recuento exacto, algo esencial para supervisar costes, optimizar indicaciones (prompts) y dimensionar tus presupuestos de API.
El objeto usage estándar
Esta es la estructura del objeto usage que se devuelve con cada respuesta:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 342,
"total_tokens": 469
}
}
Los tres contadores básicos
prompt_tokens: número de tokens en tu solicitud (mensaje de sistema + historial + nuevo mensaje). Este es el lado de «entrada» de la facturación.completion_tokens: número de tokens generados por el modelo en su respuesta. Este es el lado de «salida».total_tokens: suma de los dos anteriores. Este es el total facturado por esta solicitud.
Impacto del historial en los costes
Dado que el extremo (endpoint) no mantiene estado, el historial se envía con cada solicitud. Esto significa que prompt_tokens aumenta con cada intercambio:
Intercambio 1 : prompt_tokens = 50 (sistema + 1 mensaje de usuario)
Intercambio 2 : prompt_tokens = 150 (sistema + 2 de usuario + 1 de asistente)
Intercambio 3 : prompt_tokens = 300 (sistema + 3 de usuario + 2 de asistente)
Intercambio 10: prompt_tokens = 1500 (sistema + 10 de usuario + 9 de asistente)
En conversaciones largas, el coste del historial puede superar rápidamente el coste de la propia respuesta.
reasoning_tokens: específico de los modelos de razonamiento
Los modelos Grok con capacidades de razonamiento (como grok-4.20-0309-reasoning) añaden un campo extra al objeto usage:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 892,
"total_tokens": 1019,
"completion_tokens_details": {
"reasoning_tokens": 550
}
}
}
¿Qué son los reasoning_tokens?
reasoning_tokens representan los tokens que el modelo utiliza para su razonamiento interno —el «pensamiento» que realiza antes de producir su respuesta final—. Estos tokens se generan, pero no son visibles en el campo content de la respuesta.
En el ejemplo anterior:
- El modelo generó 892 tokens en total (
completion_tokens) - Incluyendo 550 tokens de razonamiento interno (
reasoning_tokens) - Quedando 342 tokens de respuesta visible (892 - 550)
Por qué es importante
Los tokens de razonamiento se facturan igual que los tokens de completado normales. Para un modelo de razonamiento, la respuesta visible puede representar solo una fracción del coste total:
usage = response.usage
visible_tokens = usage.completion_tokens - usage.completion_tokens_details.reasoning_tokens
reasoning_tokens = usage.completion_tokens_details.reasoning_tokens
print(f"Tokens visibles: {visible_tokens}")
print(f"Tokens de razonamiento: {reasoning_tokens}")
print(f"Proporción de razonamiento: {reasoning_tokens / usage.completion_tokens * 100:.0f}%")
No es extraño que los tokens de razonamiento representen entre el 50 % y el 80 % de los tokens de completado en preguntas complejas.
Estrategias de optimización de costes
Reduce prompt_tokens
- Resume el historial: en lugar de enviar toda la conversación, resume los intercambios más antiguos.
- Limita el mensaje de sistema: una indicación de sistema de 500 tokens rara vez es necesaria; apunta a 100–200 tokens.
- Filtra mensajes: envía solo los intercambios relevantes para la pregunta actual.
Controla completion_tokens
- Usa
max_completion_tokens(max_tokensestá obsoleto): limita la respuesta visible, no el razonamiento. - Especifica el formato: «Responde en 3 frases» cuesta menos que «Explica en detalle».
- Elige el modelo adecuado: un modelo sin razonamiento es menos costoso si la tarea no requiere un pensamiento complejo.
Supervisa los costes en producción
import json
def log_usage(response, requete_id: str):
usage = response.usage
log = {
"id": requete_id,
"prompt": usage.prompt_tokens,
"completion": usage.completion_tokens,
"total": usage.total_tokens,
}
if hasattr(usage, "completion_tokens_details") and usage.completion_tokens_details:
log["reasoning"] = usage.completion_tokens_details.reasoning_tokens
print(json.dumps(log))
Puntos clave
- El objeto
usagecontieneprompt_tokens,completion_tokensytotal_tokens. prompt_tokensaumenta con cada intercambio debido al envío del historial.- Los modelos de razonamiento añaden
reasoning_tokensdentro decompletion_tokens_details. - Los tokens de razonamiento se facturan a la tarifa de salida, pero son invisibles en la respuesta; su peso en el coste depende de la tarea y del esfuerzo, así que mídelo.
- Optimiza resumiendo el historial, ajustando el esfuerzo de razonamiento, limitando
max_completion_tokensy eligiendo el modelo adecuado.