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

Cabeceras de la API y gestión del desbordamiento

Lección 8 de 14 Actualizado el 28 de julio de 2026 Intermedio
En esta página
  1. Decide qué solicitudes consumen tu capacidad
  2. Omitir voluntariamente la capacidad dedicada
  3. Enrutar una solicitud a un grupo específico
  4. Qué ocurre en caso de desbordamiento
  5. Traducir la prioridad al código de la aplicación
  6. Puntos clave

Decide qué solicitudes consumen tu capacidad

Reservar capacidad solo resuelve la mitad del problema: aún debes elegir qué solicitudes se benefician realmente de ella. El rendimiento aprovisionado no es una compra global que realizas una vez al inicio del mes; es un mecanismo que controlas llamada a llamada. xAI expone cabeceras HTTP dedicadas para este fin, las cuales arbitran, solicitud por solicitud, entre tu capacidad dedicada y el grupo compartido. Así, una asignación fija se convierte en una palanca operativa que tus equipos manipulan directamente desde el código de la aplicación.

Omitir voluntariamente la capacidad dedicada

La primera cabecera sirve para excluir una solicitud de tu asignación:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-disable: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Summarize this document."}]
  }'

Renunciar a tu propia capacidad puede parecer contraintuitivo. Sin embargo, cuatro situaciones lo justifican en las operaciones diarias. En primer lugar, tareas no críticas: un análisis por lotes lanzado a las 22:00 o un trabajo de procesamiento diferido no necesita una garantía de latencia, y sería una lástima que consumiera la asignación pagada para el tráfico interactivo. En segundo lugar, preservar la capacidad durante los picos: al desactivar el rendimiento aprovisionado en el procesamiento secundario, liberas asignación exactamente cuando las solicitudes prioritarias llegan en gran volumen. La cabecera también sirve para pruebas A/B, cuando deseas medir la brecha real de rendimiento entre la capacidad dedicada y la compartida bajo tu propia carga, en lugar de basarte en una promesa del proveedor. Por último, es valiosa para la depuración: forzar que la solicitud pase por el grupo compartido te indica de inmediato si la anomalía observada proviene de la capacidad aprovisionada o de tu código.

Enrutar una solicitud a un grupo específico

La segunda cabecera dirige la llamada a un grupo de capacidad identificado:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-id: pool-support-client" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "How can I help you?"}]
  }'

Esta cabecera se vuelve indispensable tan pronto como múltiples aplicaciones dentro de tu organización llaman a Grok. Entonces creas grupos separados: un pool-support para el chatbot de atención al cliente, un pool-analysis para el análisis de documentos y un pool-internal para herramientas de negocio; cada uno opera de forma independiente. La segmentación aísla el rendimiento: la campaña de análisis de documentos lanzada un lunes por la mañana ya no degrada los tiempos de respuesta del soporte. También genera un consumo desglosado por uso, proporcionando así una base factual para la repercutición de costes o el arbitraje, donde antes dependías de conjeturas. Además, evita inherentemente que una única aplicación monopolice la capacidad en detrimento de las demás.

Qué ocurre en caso de desbordamiento

Cuando el tráfico supera la capacidad aprovisionada, la alternativa es automática y silenciosa: la solicitud pasa al grupo compartido bajo la modalidad de pago por uso, se aplican las tarifas estándar del modelo y queda sujeta a los límites de tasa habituales. No se devuelve ningún error; tu aplicación no percibe que haya ocurrido nada.

Esta discreción tiene dos caras. Por el lado de la disponibilidad, la noticia es buena: nunca encontrarás un error 429 causado por exceder la capacidad aprovisionada. Por el lado financiero y de la calidad del servicio, la cosa es menos favorable. La solicitud se factura a la tarifa de pago por uso, potencialmente más alta; los tiempos de respuesta pueden variar ya que el procesamiento tiene lugar en infraestructura compartida; y, sobre todo, el SLA del 99,9 % solo cubre las solicitudes procesadas dentro del rendimiento aprovisionado. Un desbordamiento, por tanto, no rompe nada; simplemente te hace salir sigilosamente del ámbito por el que pagas. La API de gestión expone la proporción de solicitudes procesadas en modo aprovisionado frente a las de pago por uso: examina esta ratio cada mes como si fuera una factura. Una tasa de desbordamiento creciente es la señal de que necesitas aumentar la asignación.

Traducir la prioridad al código de la aplicación

En lugar de multiplicar las funciones de llamada, la práctica más sólida consiste en calificar la prioridad en el momento en que se emite la solicitud:

import httpx

def query_grok(prompt: str, priority: str = "normal"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    if priority == "low":
        headers["x-pt-disable"] = "true"
    elif priority == "high":
        headers["x-pt-id"] = "pool-critical"

    response = httpx.post(
        "https://api.x.ai/v1/chat/completions",
        headers=headers,
        json={
            "model": "grok-4.3",
            "messages": [{"role": "user", "content": prompt}],
        },
    )
    return response.json()

El parámetro priority se convierte en la única decisión expuesta a la lógica de negocio, y la política de enrutamiento permanece concentrada en una única función que puedes evolucionar sin tocar el resto. Revisa tu propio código de llamada y clasifica cada punto de entrada en una de tres categorías: el ejercicio muestra regularmente que una buena mitad del tráfico no necesitaba capacidad dedicada.

Puntos clave

  • La cabecera x-pt-disable: true omite la capacidad aprovisionada para una solicitud
  • La cabecera x-pt-id enruta a un grupo de capacidad específico
  • Los desbordamientos recurren automáticamente al pago por uso sin generar errores
  • La segmentación en grupos permite aislar el rendimiento y rastrear el consumo por aplicación
  • Supervisa la tasa de desbordamiento para ajustar tu asignación si es necesario