A API xAI para programadores
Nesta página
Integre o Grok nas suas aplicações
Tudo o que aprendeu a fazer na interface do Grok pode ser acionado a partir do seu próprio código. A API xAI traz essas capacidades para as suas aplicações, sites e serviços: a conversa deixa de ser um destino para se tornar uma função que o seu produto invoca.
Pré-requisitos
Precisa de quatro coisas antes de escrever a sua primeira linha de código:
- Uma conta xAI criada em accounts.x.ai
- Uma chave de API gerada em console.x.ai
- Um método de pagamento configurado (para ultrapassar a quota gratuita)
- Um ambiente de desenvolvimento Python ou JavaScript
As duas primeiras são tarefas que já realizou neste curso: a conta gere a autenticação e a chave identifica a sua aplicação junto da API. O método de pagamento só entra em cena quando o seu uso excede a quota gratuita, o que acontece mais depressa do que imagina assim que um serviço corre continuamente. Quanto ao ambiente, Python e JavaScript oferecem as melhores ferramentas, mas como a API fala HTTP, qualquer linguagem capaz de enviar um pedido serve.
Configuração inicial
O primeiro passo é armazenar a sua chave de API de forma segura, numa variável de ambiente:
export XAI_API_KEY="xai-your-key-here"
Nunca inclua a sua chave diretamente no código fonte. A razão é banal: uma chave escrita num ficheiro acaba mais cedo ou mais tarde num repositório Git, e uma chave enviada para um repositório público é explorada em minutos por bots que analisam commits, enquanto a fatura fica em seu nome.
De seguida, escolha um SDK. O SDK nativo xAI para Python instala-se com pip install xai-sdk. Se o seu código já invoca a OpenAI, a biblioteca openai funciona tal como está, graças à compatibilidade de formatos. Do lado do JavaScript, adicione o Vercel AI SDK com npm install ai @ai-sdk/xai, que se integra com aplicações React e Next.js.
O seu primeiro pedido
Com o SDK nativo, criar o cliente e abrir uma conversa leva três linhas:
from xai_sdk import Client
import os
client = Client(api_key=os.getenv("XAI_API_KEY"))
response = client.chat.create(model="grok-4.5")
A rota compatível com a OpenAI é igualmente direta: apenas o base_url muda em relação ao código existente, razão pela qual muitas equipas fazem a migração em poucos minutos.
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.responses.create(
model="grok-4.5",
input="Explain machine learning to me in 3 sentences."
)
Para verificar se uma chave funciona antes mesmo de escrever qualquer código, nada supera uma chamada pela linha de comandos:
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"input": "Hi, how are you?"
}'
O que a API expõe
A base é a geração de texto (respostas conversacionais, escrita, análise), juntamente com um modo de raciocínio que resolve problemas complexos passo a passo. O streaming soma-se a isso, entregando a resposta token a token em vez de esperar pelo fim da geração.
Um segundo conjunto dá acesso à informação: pesquisa em tempo real na web e no X, e RAG, que consulta coleções de documentos que construiu. A vertente multimodal cobre a compreensão de imagens que fornece, a geração de imagens e vídeos com grok-imagine, e a voz, com conversas faladas e TTS.
Finalmente, três mecanismos tornam a API programável no sentido estrito: chamada de funções, que permite ao modelo invocar as suas próprias funções; saídas estruturadas, que garantem JSON utilizável sem pós-processamento frágil; e execução de código no servidor.
Escolha o seu modelo
O raciocínio varia consoante o modelo. grok-4.7, o modelo de destaque, oferece raciocínio configurável: o parâmetro reasoning_effort (low, medium, high ou xhigh) define a profundidade do pensamento, pedido a pedido. grok-4.3 mantém-se como a opção económica, de contexto muito longo, a cerca de metade do preço. Existem versões dos modelos sem raciocínio para tarefas simples: reformular ou classificar não requer deliberação interna.
As convenções de nomenclatura afetam a estabilidade da sua aplicação:
grok-4.20: a versão estável mais recente recomendadagrok-4.20-latest: a versão mais recente (pode mudar)grok-4.20-0309: uma versão fixada numa data específica (9 de março)
Em produção, uma versão fixada protege os seus prompts de alterações silenciosas no modelo; latest serve para exploração, desde que aceite que o comportamento possa mudar.
Limites de taxa e boas práticas
A API impõe limites de taxa para manter o serviço estável: no nível de entrada, cerca de 10 milhões de tokens por minuto e 1.800 pedidos por minuto para modelos como o grok-4.3, e mais à medida que o seu nível sobe. Os modelos de geração de imagem e vídeo têm os seus próprios limites, muito mais baixos, de 30 a 300 pedidos por minuto dependendo do modelo, por isso fique atento a eles num serviço virado para o consumidor.
Alguns hábitos separam um protótipo de uma integração sólida. Ative o streaming para respostas longas, porque trinta segundos perante um ecrã em branco parecem uma indisponibilidade. Passe um ID de conversa para beneficiar da cache. Encaminhe cada tarefa para o modelo certo: grok-4.3 para volume simples, grok-4.20 para raciocínio. Trate os erros com novas tentativas e recuo exponencial, ou um pico de tráfego transforma-se numa avalanche de pedidos rejeitados. E monitore o seu uso na consola antes de descobrir o total no final do mês.
Pontos-chave
- A API xAI é compatível com o formato OpenAI, o que facilita a migração
- Existem vários SDKs disponíveis: xAI nativo, OpenAI e o Vercel AI SDK
- A API cobre texto, imagens, vídeo, voz e pesquisa
- Dois níveis de modelos: grok-4.7 (destaque, raciocínio configurável) e grok-4.3 (económico, contexto de 1M)
- Guarde sempre a sua chave de API numa variável de ambiente, nunca diretamente no código