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

Criar e configurar uma chave de API

Aula 2 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Por que criar chaves via API
  2. Endpoint de criação
  3. Exemplo completo com curl
  4. Estratégias de ACL recomendadas
  5. Endpoints de ACL disponíveis
  6. Pontos-chave

Por que criar chaves via API

Criar uma chave manualmente leva trinta segundos — é exatamente por isso que precisa de automação. Como é rápido, fá-lo sem pensar: sem convenção de nomes, sem limites de taxa, apenas um curinga “para avançar depressa”. Seis meses depois, ninguém sabe para que serve cada chave.

Utilizar a API obriga-o a nomear, delimitar o âmbito e definir um limite para cada chave, pois estes são parâmetros do script. A consistência deixa de ser uma disciplina que tem de manter para se tornar uma propriedade do código. Pode automatizar a criação de chaves para os seus ambientes (dev, staging, produção), aplicar ACLs granulares e definir limites de taxa — tudo dentro dos seus scripts de implementação ou ferramentas de infraestrutura.

Endpoint de criação

Para criar uma chave de API, envie um pedido POST para o seguinte endpoint:

POST /auth/teams/{teamId}/api-keys

Corpo do pedido

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Parâmetros detalhados

name (obrigatório): um identificador legível para a sua chave. Escolha um nome descritivo que indique a utilização (prod-backend, staging-chatbot, dev-john). Este nome aparece na consola e nos registos de utilização.

acls (obrigatório): a lista de permissões concedidas a esta chave. Estão disponíveis dois formatos:

  • api-key:endpoint:[endpoint] — restringe os endpoints acessíveis (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — restringe os modelos utilizáveis (grok-4.20-0309-reasoning, grok-4.3, etc.)

O caráter * funciona como um curinga: api-key:endpoint:* autoriza todos os endpoints, api-key:model:* todos os modelos. Reserve isto para desenvolvimento local. Em produção, um curinga significa que uma chave comprometida dá acesso a tudo o que a sua equipa pode fazer — incluindo os modelos mais dispendiosos, que a sua aplicação pode nunca utilizar.

qps (opcional): consultas por segundo — número máximo de pedidos por segundo.

qpm (opcional): consultas por minuto — número máximo de pedidos por minuto.

tpm (opcional): tokens por minuto — número máximo de tokens processados por minuto.

expireTime (opcional): data de expiração no formato ISO 8601. A chave será automaticamente desativada nesta data.

Exemplo completo com curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

A resposta contém a chave secreta, que nunca mais será exibida. Esta regra tem uma consequência prática que precisa de antecipar antes de executar o script, e não depois: se criar chaves num ciclo, o armazenamento deve ocorrer no mesmo movimento. Uma chave perdida entre a criação e o registo não é recuperável — tem de a eliminar e recomeçar. Grave-a num cofre (Vault, AWS Secrets Manager) em vez da saída padrão do seu terminal, onde acabará no seu histórico.

Estratégias de ACL recomendadas

Chave de desenvolvimento (ampla)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideal para desenvolvimento local: o acesso é amplo porque não sabe antecipadamente o que vai testar, mas os limites de taxa permanecem baixos. Este é o compromisso certo — um ciclo infinito escrito por engano numa sexta-feira à noite custará alguns cêntimos em vez de algumas centenas de euros.

Chave de produção (restrita)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

Em produção, a regra inverte-se: parta do que a aplicação faz realmente e autorize apenas isso. A pergunta a fazer ao escrever a ACL é sempre a mesma — se esta chave vazar amanhã, o que pode um terceiro fazer com ela? Uma chave limitada ao chat num único modelo e limitada a dez pedidos por segundo dá uma resposta curta.

Chave temporária (expirável)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

A expiração automática resolve o problema que ninguém gere: as chaves que as pessoas se esquecem de eliminar. Um POC, uma demonstração, um contratante passageiro — em todos estes casos, o expireTime garante que o acesso se desliga sozinho. Esta é a única forma fiável de manter um inventário limpo, porque não depende da memória de ninguém.

Endpoints de ACL disponíveis

Para ver os endpoints que pode utilizar nas ACLs, consulte:

GET /auth/teams/{teamId}/endpoints

Os endpoints disponíveis são: chat, embed, image, models, sample, tokenize, documents. Esta lista pode evoluir ao longo do tempo, por isso verifique regularmente.

Pontos-chave

  • A criação de chaves ocorre via POST /auth/teams/{teamId}/api-keys
  • As ACLs seguem o formato api-key:endpoint:[nome] ou api-key:model:[nome]
  • O curinga * concede acesso total a todos os endpoints ou modelos
  • A chave secreta é exibida apenas uma vez na criação — guarde-a imediatamente
  • Defina sempre limites de taxa (qps, qpm, tpm) adequados à utilização
  • Utilize expireTime para chaves temporárias