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

API de Gestão: Gestão de Chaves e Faturação

Aula 12 de 14 Atualizada a 28 de julho de 2026 Intermediario
Nesta página
  1. Gere a sua conta sem a consola
  2. Provisionar e rodar chaves
  3. Acompanhar e controlar a faturação
  4. Monitore o seu consumo na granularidade correta
  5. Pontos-chave

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