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

O URL base da API

Aula 4 de 14 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. O ponto de entrada da API Grok
  2. O URL base
  3. Compatibilidade com o ecossistema OpenAI
  4. Os principais endpoints
  5. Definir o URL nos seus SDKs
  6. Testar a conectividade
  7. Limites e quotas
  8. Pontos-chave

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/v1 por https://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 imagens
  • POST /v1/images/edits: editar imagens existentes
  • POST /v1/videos/generations: gerar vídeos
  • POST /v1/tts: síntese de fala (texto-para-fala)

Gestão de ficheiros

  • POST /v1/files: carregar um ficheiro
  • GET /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/v1 para 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/completions permanece disponível para compatibilidade