API de xAI (Grok)
Cuando XAI_API_KEY está presente en el entorno, esta aplicación tiene acceso real a la API de xAI — úsala para funcionalidades de IA en lugar de simular respuestas o recurrir a otro proveedor. La misma variable se inyecta en la aplicación desplegada al publicar, por lo que el código construido con ella funciona de manera idéntica en vista previa y en producción.
La clave es la clave personal del propietario de la aplicación: cada llamada consume su cuota y créditos. Sé deliberado con el uso — consulta Gastar responsablemente antes de conectar llamadas de IA a cualquier cosa que se ejecute automáticamente o esté abierta a visitantes.
La clave desbloquea toda la superficie de la API, no solo el chat:
- Chat / LLM — modelo más reciente:
grok-4.5; usa este por defecto a menos que el usuario pida otro. - Imagine (imágenes y video) — genera y edita imágenes, genera video, en tiempo real dentro de la aplicación.
- Voz — texto a voz con voces expresivas (y transcripción).
- Documentación oficial: docs.x.ai — endpoints, modelos, parámetros, streaming, uso de herramientas. No adivines las formas de la API; consulta la documentación.
- La API es compatible con OpenAI (
https://api.x.ai/v1), por lo que cualquier cliente estilo OpenAI funciona cambiando la URL base y la clave.
Variables de entorno — no crees un archivo .env
| Variable | Dónde | Propósito |
|---|---|---|
XAI_API_KEY | servidor | Inyectada por la plataforma (vista previa y despliegue). Nunca la escribas, la hardcodees o se la pidas al usuario. |
La clave es solo del servidor: léela con process.env.XAI_API_KEY dentro de los manejadores createServerFn / código del servidor, nunca en componentes cliente, y nunca la expongas mediante una variable con prefijo VITE_ o en una respuesta de API.
Puede estar ausente (controlada por despliegue gradual). Degrada con elegancia — compruébala y muestra un estado amigable como 'Las funciones de IA no están disponibles' en lugar de fallar:
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("AI no está disponible en este entorno");
Llamar a la API (solo servidor)
No se necesita SDK — usa fetch simple desde una función del servidor:
import { createServerFn } from "@tanstack/react-start";
export const askGrok = createServerFn({ method: "POST" })
.validator((input: { prompt: string }) => input)
.handler(async ({ data }) => {
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) return { ok: false as const, error: "AI no está disponible" };
const res = await fetch("https://api.x.ai/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: "grok-4.5",
messages: [{ role: "user", content: data.prompt }],
}),
});
if (!res.ok) {
return { ok: false as const, error: `Error de API xAI ${res.status}` };
}
const body = (await res.json()) as {
choices: { message: { content: string } }[];
};
return { ok: true as const, text: body.choices[0]?.message.content ?? "" };
});
Para streaming, salidas estructuradas, visión o la lista completa de modelos, consulta docs.x.ai — las formas son compatibles con OpenAI.
Imagine — generación de imágenes y video (solo servidor)
La misma clave impulsa las funciones de imagen/video en tiempo real en la aplicación (avatares de usuario, arte de escenas, contenido generado). Es diferente de tus herramientas en tiempo de compilación imagine_text_to_image / imagine_image_to_image / imagine_image_to_video (la habilidad imagine-grok-build): usa la API cuando la aplicación en ejecución genera medios, y las herramientas cuando tú creas activos estáticos durante la compilación.
// POST https://api.x.ai/v1/images/generations — mismo encabezado de autenticación que el chat
body: JSON.stringify({
model: "grok-imagine-image-quality", // o "grok-imagine-image" (más barato)
prompt: data.prompt,
// n (≤10), resolución ("1k"|"2k"), response_format ("url"|"b64_json")
})
// → body.data[0].url
- Edición de imágenes:
POST /v1/images/edits— ediciones en lenguaje natural, hasta 3 imágenes de referencia. - Video:
grok-imagine-videoa través de los endpoints de video asíncronos (inicia, luego consulta el ID de solicitud devuelto; clips de hasta ~15s). - Parámetros completos y ejemplos: docs.x.ai → API de Imagine.
Voz — texto a voz (solo servidor)
POST https://api.x.ai/v1/tts convierte texto en audio hablado — narración, accesibilidad, voces de personajes:
// Mismo encabezado Authorization; devuelve bytes de audio (ej. MP3)
body: JSON.stringify({ text: data.text, voice_id: "eve" }) // eve = voz predeterminada
Enumera las voces en GET /v1/tts/voices (se admiten voces personalizadas); la transcripción (voz a texto) también está disponible. Detalles: docs.x.ai → API de Voz. Sirve el audio al cliente desde tu función del servidor — nunca llames a la API desde el navegador (eso expondría la clave).
Gastar responsablemente
La clave pertenece al propietario de la aplicación (el usuario para el que construyes): cada llamada — incluyendo las activadas por visitantes anónimos de la aplicación desplegada — consume su cuota y créditos personales. Gastarla en llamadas innecesarias degrada o rompe todos los demás usos de su clave. Sé cuidadoso con el uso:
- Limita la salida (
max_tokens) y mantén los mensajes pequeños para funciones orientadas a visitantes. La generación de imágenes, y especialmente de video, cuesta mucho más por llamada que el chat. - Nunca llames a la API en un bucle, con cada pulsación de tecla o al cargar la página — haz que las llamadas sean iniciadas por el usuario (pulsación de botón, envío de formulario) y aplica debounce.
- Almacena en caché o persiste los resultados (consulta la habilidad
neon) en lugar de regenerar el mismo contenido por visitante o por renderizado. - Protege los flujos costosos — especialmente la generación de medios. En una aplicación que ya tiene inicio de sesión, colócalos detrás de
authMiddleware(consulta la habilidadauth). El inicio de sesión está desactivado por defecto, y agregar el middleware sin él rompe la aplicación desplegada (AGENTS.md §0.5) — así que en una aplicación sin cuentas, limita el uso: llamadas iniciadas por el usuario, límites pequeños, resultados en caché. - No agregues tormentas de reintentos: ante un error de API, muéstralo; reintenta como máximo una vez.