API de gerenciamento

Visão geralCopy Anchor Link

A API de gerenciamento permite consultar os totais de saldo da organização, gerenciar as API Keys da organização e consultar uso e faturamento por chave sem usar uma API Key padrão de inferência.

Crie e rotacione o token de gerenciamento em Dashboard → API → Management Tokens.

Authorization: Bearer mt-your-management-token

Endpoints disponíveisCopy Anchor Link

Contrato de filtros de usoCopy Anchor Link

GET /v1/management/api-keys/{keyId}/usage aceita os seguintes parâmetros de query.

Se startDate e endDate forem enviados juntos, startDate deve ser anterior ou igual a endDate.

Contrato do corpo da API KeyCopy Anchor Link

POST /v1/management/api-keysCopy Anchor Link

PATCH /v1/management/api-keys/{keyId}Copy Anchor Link

A requisição PATCH deve incluir pelo menos um campo.

Campos monetáriosCopy Anchor Link

• Os campos monetários de requisição e resposta da API de gerenciamento aceitam apenas USD.
• limitCurrency usa USD por padrão; enviar CNY retorna 400 currency_retired.

Semântica de reportingCopy Anchor Link

• model se refere ao modelo público solicitado por quem faz a chamada.
• modelVendor se refere ao fornecedor público do modelo, e não à rota física oculta.
• scene é a cena pública da solicitação derivada do endpoint ou do tipo de tarefa.

As respostas expõem apenas campos públicos de faturamento e reporting. Os detalhes internos de roteamento e a metadata física do provedor permanecem ocultos.

• Itens de /usage podem incluir billing_transaction_id assim que a requisição subjacente atingir o estado de liquidação concluída. Use request_id + billing_transaction_id para reconciliação por requisição.

Nota sobre a paginação de faturamentoCopy Anchor Link

/usage é paginado. /billing atualmente é um endpoint agregado e não retorna metadata de paginação no estilo page / limit. Se você precisar de registros detalhados linha a linha, use /usage.

Exemplo rápidoCopy Anchor Link

Comece consultando o saldo da organização com o token de gerenciamento atual.

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Em seguida, liste as API Keys disponíveis para esse mesmo token de gerenciamento.

curl "https://api.tokenlab.sh/v1/management/api-keys" \
  -H "Authorization: Bearer mt-your-management-token"

{
  "object": "list",
  "data": [
    {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-abc123...",
      "status": "active",
      "limit_amount": 500.0,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": [
        "gpt-4o-mini",
        "claude-3-7-sonnet"
      ],
      "expires_at": "2026-04-30T00:00:00.000Z",
      "last_used_at": "2026-03-27T08:12:45.000Z",
      "created_at": "2026-03-01T10:00:00.000Z",
      "delivery_policy": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Próximos passosCopy Anchor Link

• Obter saldo da organização
• Listar API Keys
• Criar API Key
• Atualizar API Key
• Obter uso da API Key
• Obter faturamento da API Key