URL Base e Primeira Solicitação
Nesta página
A API de Gestão: Um Plano de Controlo Separado
A API de Gestão da xAI é distinta da API de inferência que utiliza para enviar prompts ao Grok. Esta permite-lhe administrar os seus recursos: criar e gerir chaves de API, configurar a faturação, monitorizar a utilização e controlar o acesso da sua equipa. Toda esta administração ocorre através de um URL dedicado.
URL Base
Esta separação não é um pormenor de implementação: reflete uma diferença fundamental entre as duas APIs. Uma consome tokens e executa modelos; a outra administra, fatura e concede permissões. Mantê-las em dois domínios e com dois conjuntos de chaves garante que uma chave de aplicação roubada nunca possa criar outras chaves nem ler as suas informações de faturação.
https://management-api.x.ai
Não confunda este URL com https://api.x.ai, que é o endereço para chamadas de inferência (completamentos de chat, embeddings, etc.). Todos os pedidos de gestão — chaves, faturação, análises — passam por management-api.x.ai.
Autenticação na API de Gestão
O mecanismo de autenticação é idêntico — um token Bearer no cabeçalho Authorization — mas a chave em si não é. Esta é a confusão mais comum ao começar, resultando num erro 401 perfeitamente opaco: nada na mensagem de erro indica que apresentou simplesmente a chave certa à API errada.
curl https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Este pedido de validação (GET /auth/management-keys/validation) permite-lhe verificar se a sua chave de gestão é válida e está ativa. É o ponto de entrada mais simples para testar a sua configuração.
Chave de Gestão vs Chave de Inferência
- Chave de gestão: concede acesso aos endpoints de
management-api.x.ai(administração, faturação, análises) - Chave de inferência: concede acesso aos endpoints de
api.x.ai(chat, embeddings, imagens)
Ambos os tipos de chave são gerados na consola da xAI, mas os seus escopos diferem. Uma chave de inferência não pode aceder a endpoints de gestão e vice-versa.
Estrutura dos Endpoints
Os endpoints da API de Gestão seguem uma organização lógica:
/auth/teams/{teamId}/api-keys— gestão de chaves de API/auth/api-keys/{apiKeyId}— operações numa chave específica/auth/teams/{teamId}/models— modelos acessíveis/auth/teams/{teamId}/endpoints— endpoints ACL disponíveis/v1/billing/teams/{teamId}/— faturação e análises
O parâmetro teamId é o identificador da sua equipa na consola da xAI e estrutura quase todos os endpoints. Cada equipa possui as suas próprias chaves, quotas e definições de faturação, tornando-se a unidade natural de isolamento: separar dois projetos em duas equipas separa também os seus orçamentos e acessos, sem qualquer configuração adicional.
O Seu Primeiro Pedido de Gestão
Eis um exemplo completo para validar a sua configuração:
# Defina a sua chave de gestão
export MANAGEMENT_API_KEY="xai-mgmt-..."
# Valide a chave
curl -s https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
Se a resposta contiver informações sobre a sua equipa e a chave, a sua configuração está a funcionar. Se obtiver um erro 401, verifique se está a utilizar uma chave de gestão (e não uma chave de inferência).
Pontos-chave
- A API de Gestão utiliza
https://management-api.x.ai, distinto dehttps://api.x.ai - A autenticação usa um token Bearer no cabeçalho
Authorization - As chaves de gestão e as chaves de inferência possuem escopos separados
- O endpoint
GET /auth/management-keys/validationpermite testar a sua configuração - Todos os endpoints de gestão estão organizados em torno do
teamId