API xAI (Grok)
Quando XAI_API_KEY está presente no ambiente, este aplicativo tem acesso real à API xAI — use-a para funcionalidades de IA em vez de simular respostas ou recorrer a outro provedor. A mesma variável é injetada no aplicativo implantado na publicação, então o código construído com ela funciona de forma idêntica em preview e produção.
A chave é a chave pessoal do proprietário do aplicativo: cada chamada gasta sua cota e créditos. Seja deliberado sobre o uso — consulte Gaste com responsabilidade antes de conectar chamadas de IA a qualquer coisa que execute automaticamente ou seja aberta a visitantes.
A chave desbloqueia a superfície completa da API, não apenas chat:
- Chat / LLM — modelo mais recente:
grok-4.5; use-o como padrão, a menos que o usuário peça o contrário. - Imagine (imagens e vídeo) — gere e edite imagens, gere vídeo, em tempo de execução dentro do aplicativo.
- Voz — texto-para-fala com vozes expressivas (e transcrição).
- Documentação oficial: docs.x.ai — endpoints, modelos, parâmetros, streaming, uso de ferramentas. Não adivinhe formas de API; consulte a documentação.
- A API é compatível com OpenAI (
https://api.x.ai/v1), então qualquer cliente no estilo OpenAI funciona apenas alterando a URL base e a chave.
Variáveis de ambiente — não crie um arquivo .env
| Variável | Onde | Propósito |
|---|---|---|
XAI_API_KEY | servidor | Injetada pela plataforma (preview e implantação). Nunca escreva, codifique ou peça ao usuário. |
A chave é apenas no servidor: leia-a com process.env.XAI_API_KEY dentro de manipuladores createServerFn / código do servidor, nunca em componentes do cliente, e nunca a exponha por meio de uma variável prefixada com VITE_ ou uma resposta de API.
Ela pode estar ausente (restrito por rollout). Degrade graciosamente — verifique-a e mostre um estado amigável "Funcionalidades de IA não estão disponíveis" em vez de falhar:
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("A IA não está disponível neste ambiente");
Chamando a API (apenas no servidor)
Nenhum SDK necessário — fetch simples a partir de uma função do 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: "A IA não está disponível" };
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: `Erro da 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, saídas estruturadas, visão ou a lista completa de modelos, siga docs.x.ai — as formas são compatíveis com OpenAI.
Imagine — geração de imagem e vídeo (apenas no servidor)
A mesma chave dirige funcionalidades de imagem/vídeo em tempo de execução no aplicativo (avatares de usuário, arte de cena, conteúdo gerado). Distinto das ferramentas imagine_text_to_image / imagine_image_to_image / imagine_image_to_video em tempo de compilação (o skill imagine-grok-build): use a API quando o aplicativo em execução gera mídia, as ferramentas quando você cria ativos estáticos durante a construção.
// POST https://api.x.ai/v1/images/generations — mesmo cabeçalho de autenticação do chat
body: JSON.stringify({
model: "grok-imagine-image-quality", // ou "grok-imagine-image" (mais barato)
prompt: data.prompt,
// n (≤10), resolução ("1k"|"2k"), response_format ("url"|"b64_json")
})
// → body.data[0].url
- Edição de imagem:
POST /v1/images/edits— edições em linguagem natural, até 3 imagens de referência. - Vídeo:
grok-imagine-videopor meio dos endpoints de vídeo assíncronos (inicie, depois consulte o id da requisição retornado; clipes de até ~15s). - Parâmetros completos e exemplos: docs.x.ai → API Imagine.
Voz — texto-para-fala (apenas no servidor)
POST https://api.x.ai/v1/tts converte texto em áudio falado — narração, acessibilidade, vozes de personagens:
// Mesmo cabeçalho de Authorization; retorna bytes de áudio (ex.: MP3)
body: JSON.stringify({ text: data.text, voice_id: "eve" }) // eve = voz padrão
Liste vozes em GET /v1/tts/voices (vozes personalizadas suportadas); transcrição (fala-para-texto) também está disponível. Detalhes: docs.x.ai → API de Voz. Sirva o áudio para o cliente a partir da sua função do servidor — nunca chame a API do navegador (isso exporia a chave).
Gaste com responsabilidade
A chave pertence ao proprietário do aplicativo (o usuário para quem você está construindo): cada chamada — incluindo aquelas acionadas por visitantes anônimos do aplicativo implantado — gasta sua cota e créditos pessoais. Queimá-la em chamadas desperdiçadas degrada ou quebra todos os outros usos da chave. Seja cuidadoso com o uso:
- Limite a saída (
max_tokens) e mantenha prompts pequenos para funcionalidades voltadas a visitantes. Geração de imagem, e especialmente de vídeo, custa muito mais por chamada do que chat. - Nunca chame a API em um loop, a cada pressionamento de tecla ou ao carregar a página — faça chamadas iniciadas pelo usuário (pressionamento de botão, envio de formulário) e use debounce.
- Armazene em cache ou persista resultados (veja o skill
neon) em vez de regenerar o mesmo conteúdo por visitante ou por renderização. - Restrinja fluxos caros — geração de mídia em particular. Em um aplicativo que já tem login, coloque-os atrás de
authMiddleware(veja o skillauth). O login está desativado por padrão, e adicionar o middleware sem ele quebra o aplicativo implantado (AGENTS.md §0.5) — então, em um aplicativo sem contas, limite o uso: chamadas iniciadas pelo usuário, limites pequenos, resultados em cache. - Não adicione tempestades de repetição: em um erro de API, exiba-o; repita no máximo uma vez.