Cómo integrar la API de Grok 4.5: Responses API, precio, disponibilidad en la UE y configuración de prompt cache

Grok 4.5 es el modelo de xAI para codificación, agentes y trabajo de conocimiento. El modelo se llama grok-4.5. Si su proyecto ya usa OpenAI SDK, puede llamarlo apuntando baseURL a https://api.x.ai/v1; para nuevos proyectos, puede elegir xAI SDK, compatibilidad con OpenAI SDK o solicitar directamente la API REST.

Este artículo solo analiza el acceso a la API. La disponibilidad del modelo en los complementos Grok Build, Cursor y Office no es exactamente la misma que la región, la cuenta y el estado de facturación en la Consola API. No los confunda al solucionar problemas.

Confirma tres cosas antes de acceder

Antes de comenzar necesitas:

1. Cree una clave API en xAI API Console y guárdela en la variable de entorno XAI_API_KEY.
2. Confirme que la cuenta de destino pueda usar la Consola API; A partir de la actualización del documento oficial, los usuarios de la UE aún no pueden usar Grok 4.5 en la Consola API, que se espera que esté disponible más adelante este mes.
3. Deje en claro si desea utilizar API de respuestas o Finalizaciones de chat. Se prefiere el nuevo acceso para utilizar la API de Respuestas; Los proyectos existentes basados ​​en chat.completions pueden mantener primero la interfaz existente y luego agregar la configuración de enrutamiento de caché por separado.

No escriba claves API en JavaScript front-end, aplicaciones cliente o repositorios Git. Los navegadores y los clientes móviles y de escritorio deben solicitar primero su propio backend, que luego llama a la API xAI.

Rango de precio y capacidad de Grok 4.5

Los precios del texto básico que figuran en la documentación oficial son los siguientes:

La lista de precios no es la factura final. El costo real también se ve afectado por la duración de la entrada, la duración de la salida, la intensidad de la inferencia, las llamadas a herramientas, los aciertos de la caché, la limitación de la velocidad y los precios del equipo. Primero utilice tráfico pequeño para registrar tokens de entrada, salida y caché, y luego decida si desea aumentar la intensidad de la inferencia o expandir la concurrencia.

API de respuestas de llamadas usando OpenAI SDK

Si el proyecto ha instalado el SDK Python oficial openai, puede acceder a él de la siguiente manera. La clave es mantener base_url="https://api.x.ai/v1" y escribir el nombre del modelo como grok-4.5:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.5",
    input="请审查这段 Python 函数，指出边界条件问题并给出修正版。",
)

print(response.output_text)

La solicitud HTTP equivalente es:

1
2
3
4
5
6
7

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.5",
    "input": "请审查这段 Python 函数，指出边界条件问题并给出修正版。"
  }'

Cuando la solicitud devuelve un error, primero verifique la clave API, base_url, el nombre del modelo y la región de la cuenta, y luego verifique la cuota o la política a nivel de organización. No reescriba la clave en un archivo de código y la pruebe una y otra vez sólo porque el modelo no está disponible.

¿Por qué configurar prompt_cache_key?

Las conversaciones largas, el análisis de la base de código y los bucles de agentes a menudo envían repetidamente palabras de aviso del sistema, instrucciones de herramientas y contexto histórico. La caché de xAI se mantiene por servidor; Si una solicitud para la misma sesión no se enruta de manera confiable al mismo servidor, puede caer en un servidor sin caché y facturarse como una entrada completa.

En API de respuestas, se debe pasar prompt_cache_key como campo del cuerpo de la solicitud. Para la misma sesión continua, utilice un identificador que sea estable, impredecible y que no contenga texto fuente confidencial, como un UUID generado por el servidor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.5",
    input="继续根据刚才的约束补全测试用例。",
    extra_body={
        "prompt_cache_key": "7f26e7a8-1f8f-4c34-9f93-4e9e1d40d7a1"
    },
)

print(response.output_text)
print(response.usage.input_tokens_details.cached_tokens)

El propósito de esta clave es permitir que la misma sesión se enrute al mismo servidor de manera más estable, aumentando así la posibilidad de reutilización de la caché; no fuerza todas las solicitudes a una sola sesión, ni puede guardar su propio estado de sesión en su nombre. Los usuarios, proyectos, inquilinos o tareas que deban aislarse deben utilizar claves diferentes.

Chat Completions are not the same field

Si continúa usando Finalizaciones de chat en proyectos existentes, no copie prompt_cache_key directamente. Esta interfaz utiliza el encabezado de solicitud HTTP x-grok-conv-id:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_XAI_API_KEY",
    base_url="https://api.x.ai/v1",
)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "system", "content": "You are a careful code reviewer."},
        {"role": "user", "content": "Review this change and list regressions."},
    ],
    extra_headers={
        "x-grok-conv-id": "conv_abc123",
    },
)

print(response.choices[0].message.content)

El propósito de ambas interfaces es el mismo: permitir que la misma sesión acceda al mismo caché del servidor tanto como sea posible. Las diferentes posiciones de los campos son una fuente común de errores: la API de Respuestas usa el cuerpo de la solicitud prompt_cache_key y las Finalizaciones de Chat usan el encabezado de la solicitud x-grok-conv-id.

Cómo diseñar claves de caché para que no dejen de ser válidas

Puede pensar en las claves de caché como etiquetas de enrutamiento del lado del servidor dentro del mismo contexto reutilizable. Estrategia recomendada:

• Las solicitudes consecutivas de un usuario dentro de una sesión explícita comparten la misma clave;
• Genere nuevas claves al cambiar proyectos, modelos, versiones de palabras de aviso del sistema o rangos de permisos;
• Utilice una ID de base de datos, un UUID aleatorio o una ID de sesión interna con hash sin concatenar directamente correo electrónico, mensajes de texto o datos del cliente;
• Registre breves resúmenes de claves y tokens de caché en los registros de aplicaciones en lugar de registrar claves completas o entradas completas del usuario;
• Observe cached_tokens y utilice golpes reales para determinar si el diseño es efectivo.

Generar un nuevo UUID en cada ronda, o agrupar todas las tareas no relacionadas para el mismo usuario en una clave, socavará el valor de la estrategia de almacenamiento en caché. Lo primero dificulta la reutilización y lo segundo hace que la depuración, el aislamiento y la atribución de costos sean confusos.

Cómo abordar el despliegue en la UE y en múltiples regiones

La documentación oficial indica que Grok 4.5 aún no está disponible para los usuarios de la UE en la Consola API y se espera que se lance a finales de este mes. Por lo tanto, los productos dirigidos a usuarios de varias regiones deben incluir la disponibilidad regional como parte de la verificación de inicio:

1. Antes de crear una llamada en el backend, confirme si la cuenta y la región de implementación son elegibles para el acceso.
2. Devuelve un mensaje claro de indisponibilidad de funciones para regiones no elegibles en lugar de infinitos reintentos.
3. No utilice servidores proxy, cuentas compartidas ni información regional falsificada para eludir las restricciones del servicio.
4. Prepare modelos alternativos autorizados o rutas de procesamiento manual para procesos críticos y pruebe el comportamiento de degradación antes de entrar en funcionamiento.

Ya sea que la UE haya sido abierta, los precios y límites específicos pueden cambiar. Antes de publicar en el entorno de producción, la consola API, la página de detalles del modelo y la página de precios más recientes deben usarse como estándares, no solo el tiempo de publicación de este artículo.

Problemas comunes de acceso

Devolver 401 o 403

Priorice verificar si XAI_API_KEY realmente se inyecta en el entorno de ejecución, si la solicitud se envía a https://api.x.ai/v1 y si la cuenta califica para la consola API y el acceso regional. No imprima el encabezado de Autorización en el registro de errores.

El token de caché es siempre 0

Verifique que las solicitudes consecutivas utilicen el mismo prompt_cache_key y que el campo esté ubicado en el cuerpo de la solicitud de la API de Respuestas; Si utiliza Finalizaciones de chat, verifique el encabezado x-grok-conv-id. Los aciertos de la caché también se ven afectados por el contexto y el enrutamiento del servidor, y el error de la política no se puede determinar con una sola solicitud breve.

Costos más altos de lo esperado

Primero divida los tokens de entrada, salida y caché, verifique si se usa alta intensidad de inferencia de forma predeterminada, si se envían contextos largos repetidamente, si hay demasiadas llamadas a herramientas y luego ajuste las palabras de aviso, la segmentación de sesiones y las claves de caché. No se limite a adivinar basándose en la factura total: se trata de una cuestión de precio unitario del modelo.

Resumen

El camino más corto hacia Grok 4.5 es guardar XAI_API_KEY en el backend, apuntar el base_url del OpenAI SDK a https://api.x.ai/v1, llamar a la API de Respuestas con grok-4.5 y configurar un prompt_cache_key estable para la misma sesión continua. Para proyectos de finalización de chat existentes, utilice x-grok-conv-id. Antes de conectarse, verifique la disponibilidad en la UE, los precios en tiempo real, los límites y los tokens en caché para convertir llamadas de muestra en un flujo de trabajo de producción controlable.

Información oficial:

• https://docs.x.ai/developers/grok-4-5
• https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits
• https://x.ai/news/grok-4-5