O URL base da API
Nesta página
O ponto de entrada da API Grok
Todos os pedidos à API da xAI passam por um único URL base. Compreender esse URL e os endpoints disponíveis é essencial antes de escrever a sua primeira linha de código.
O URL base
A API Grok reside neste endereço:
https://api.x.ai/v1
Este URL é a raiz de todos os endpoints. Por exemplo, para criar uma resposta, o URL completo é https://api.x.ai/v1/responses.
Porquê /v1?
O prefixo /v1 indica a versão da API. O versionamento permite à xAI evoluir a API sem quebrar as aplicações existentes. Se surgir uma versão 2, esta coexistirá com a v1 durante um período de transição.
Compatibilidade com o ecossistema OpenAI
Uma funcionalidade fundamental da API da xAI é a sua compatibilidade com o formato da OpenAI. Na prática, se já tiver código que funcione com a API da OpenAI, só precisa de alterar duas definições para usar o Grok:
- O URL base: substitua
https://api.openai.com/v1porhttps://api.x.ai/v1 - A chave da API: substitua a sua chave da OpenAI pela sua chave da xAI
Essa compatibilidade estende-se à maioria das ferramentas e bibliotecas do ecossistema OpenAI: LangChain, LlamaIndex, LiteLLM e muitas outras funcionam com o Grok sem alterações de código.
Os principais endpoints
A API expõe vários endpoints agrupados por funcionalidade.
Geração de texto
POST /v1/responses: o endpoint principal para gerar respostas (formato moderno)POST /v1/chat/completions: o endpoint compatível com a OpenAI (formato legado, ainda suportado)
Geração de multimédia
POST /v1/images/generations: gerar imagensPOST /v1/images/edits: editar imagens existentesPOST /v1/videos/generations: gerar vídeosPOST /v1/tts: síntese de fala (texto-para-fala)
Gestão de ficheiros
POST /v1/files: carregar um ficheiroGET /v1/files: listar ficheiros carregados
Tempo real
wss://api.x.ai/v1/realtime: agente de voz via WebSocket
Definir o URL nos seus SDKs
Quando utiliza um SDK compatível com a OpenAI, tem de especificar o URL base explicitamente:
from openai import OpenAI
client = OpenAI(
api_key="xai-your-key",
base_url="https://api.x.ai/v1"
)
Com o SDK nativo da xAI, o URL já vem pré-configurado e não precisa de definir nada.
Testar a conectividade
Antes de escrever qualquer código, uma chamada direta valida toda a cadeia (URL, chave, rede):
curl https://api.x.ai/v1/models \
-H "Authorization: Bearer xai-your-key"
A resposta lista os modelos disponíveis com a sua chave. É também a forma mais fiável de conhecer os IDs exatos dos modelos disponíveis na sua conta, sem depender de documentação que pode mudar. Mantenha este hábito: valide cada novo ambiente (máquina, CI, servidor) com esta mesma chamada antes de qualquer implementação.
Limites e quotas
A API impõe limites de taxa para cada equipa e cada modelo. Se os exceder, receberá um erro HTTP 429. A consola da xAI mostra as suas quotas atuais e a sua utilização em tempo real.
Pontos-chave
- O URL base é
https://api.x.ai/v1para todos os endpoints - A API é compatível com o formato da OpenAI: altere o URL e a chave, e está feito
- O endpoint principal de geração é
POST /v1/responses - O endpoint legado
POST /v1/chat/completionspermanece disponível para compatibilidade