Ir al contenido principal
Español— Elegir un idioma
Menú

Uso de tokens y reasoning_tokens

Lección 9 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Comprende la facturación por tokens
  2. El objeto usage estándar
  3. reasoning_tokens: específico de los modelos de razonamiento
  4. Estrategias de optimización de costes
  5. Puntos clave

Actualizado el 3 de noviembre de 2026. Según la referencia de la API de Chat Completions de xAI: max_tokens está obsoleto en favor de max_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_tokens está 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 usage contiene prompt_tokens, completion_tokens y total_tokens.
  • prompt_tokens aumenta con cada intercambio debido al envío del historial.
  • Los modelos de razonamiento añaden reasoning_tokens dentro de completion_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_tokens y eligiendo el modelo adecuado.