API de Gestão: Gestão de Chaves e Faturação
Nesta página
Gere a sua conta sem a consola
A API de Gestão da xAI é uma interface REST dedicada à gestão da sua conta Enterprise. Enquanto a API de Inferência (api.x.ai) chama os modelos, a API de Gestão (management-api.x.ai) administra os seus recursos. A distinção pode parecer menor. Não é. Tudo o que, de outra forma, exigiria que alguém abrisse a consola web e clicasse, torna-se aqui automatizável — rastreável, reproduzível e integrável com as ferramentas que as suas equipas já utilizam.
Provisionar e rodar chaves
Criar chaves através da API permite automatizar o provisionamento para uma nova aplicação ou ambiente:
curl -X POST "https://management-api.x.ai/auth/teams/{teamId}/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "cle-production-chatbot",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"qps": 10,
"qpm": 100,
"tpm": 1000000,
"expireTime": "2026-12-31T23:59:59Z"
}'
Os parâmetros neste pedido definem totalmente o âmbito da chave:
- name: Identificador legível por humanos para a chave
- acls: Lista de permissões (endpoints e modelos autorizados)
- qps/qpm/tpm: Limites de taxa por segundo, por minuto e tokens por minuto
- expireTime: Data de expiração automática
Definir expireTime na criação é o hábito que lhe poupa mais problemas a longo prazo: uma chave emitida para um piloto de três meses expira por si só, em vez de sobreviver indefinidamente num ficheiro de configuração que ninguém volta a ler.
A rotação regular de chaves segue a mesma higiene de segurança. O endpoint dedicado gera uma nova chave secreta e invalida a antiga:
curl -X POST "https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Aviso: a antiga chave secreta é invalidada imediata e permanentemente. Prepare-se para implementar o novo valor no seu gestor de segredos antes de executar o comando, nunca depois. Três endpoints apenas de leitura completam o conjunto: GET /auth/teams/{teamId}/api-keys lista todas as chaves da equipa, GET /auth/api-keys/{apiKeyId}/propagation verifica se a chave foi propagada em todos os nós, e GET /auth/teams/{teamId}/models lista os modelos acessíveis com os respetivos preços. O segundo é aquele que consulta imediatamente após uma rotação, quando uma aplicação continua a devolver erros de autenticação e não tem a certeza se se trata de um erro da aplicação ou simplesmente de um atraso na propagação.
Acompanhar e controlar a faturação
A recuperação de informações de faturação utiliza um endpoint dedicado:
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Recupera o histórico de faturas com filtragem por período, aqui para março de 2026:
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/invoices?billingCycle.year=2026&billingCycle.month=3" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Cada fatura possui um estado entre PENDING, PAID, FAILED e WILL_NEVER_BE_CHARGED. Detetar um estado FAILED na sua monitorização é muito melhor do que tomar conhecimento do incidente através de uma interrupção de serviço numa segunda-feira de manhã.
Para prevenir estouros orçamentais, configure um limite mensal:
curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"monthlyLimit": 5000}'
Se operar em pré-pagamento, verifique o saldo da mesma forma:
# Check balance
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Lembre-se de que os créditos pré-pagos são não reembolsáveis, salvo exigência legal. Dimensione as suas compras com base no consumo observado ao longo de várias semanas, e não em projeções de crescimento otimistas.
Monitore o seu consumo na granularidade correta
O endpoint de análise permite acompanhar a utilização com fina granularidade:
curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/usage" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}],
"groupBy": ["model"]
}
}'
Este pedido devolve o consumo diário de tokens, desagregado por modelo, para março. Ao alterar timeUnit, muda de uma visão mensal para uma visão por minuto: os valores possíveis são MONTH, CALENDAR_WEEK, DAY, HOUR, QUARTER_HOUR e MINUTE. As agregações vão muito além de simples totais, incluindo SUM, AVG, MIN, MAX, P50, P90, P99 e COUNT. Os percentis caracterizam eficazmente a carga, porque as médias suavizam exatamente os picos que determinam a capacidade de que realmente precisa.
A API de Gestão assume então o seu lugar na sua cadeia de ferramentas. Provisiona chaves a partir do Terraform ou do Pulumi tal como faria com uma base de dados, o seu pipeline de CI/CD cria chaves efémeras para ambientes de teste e elimina-as no final da execução, scripts de monitorização alertam antes de atingir o limite de despesas e os seus painéis internos exibem o consumo sem que um humano tenha de exportar um CSV todas as segundas-feiras.
Pontos-chave
- A API de Gestão em management-api.x.ai gere chaves, faturação e métricas
- A rotação de chaves invalida permanentemente a antiga chave secreta
- Os limites de despesas protegem contra estouros orçamentais
- As análises de utilização oferecem granularidade desde o minuto até ao mês
- Integre a API de Gestão nas suas ferramentas de infraestrutura para automatizar a administração