Ir para o conteúdo principal
Português— Escolher um idioma
Menu

A API xAI para programadores

Aula 15 de 16 Atualizada a 29 de julho de 2026 Iniciante
Nesta página
  1. Integre o Grok nas suas aplicações
  2. Pré-requisitos
  3. Configuração inicial
  4. O seu primeiro pedido
  5. O que a API expõe
  6. Escolha o seu modelo
  7. Limites de taxa e boas práticas
  8. Pontos-chave

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:

  1. Uma conta xAI criada em accounts.x.ai
  2. Uma chave de API gerada em console.x.ai
  3. Um método de pagamento configurado (para ultrapassar a quota gratuita)
  4. 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 recomendada
  • grok-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