API de Gerenciamento de Tokens

Solicitação de acesso à API

Para usar a API de controle de tokens, você precisa primeiro solicitar acesso ao revendedor ou ao administrador. O uso só é liberado depois que o administrador habilitar o recurso.

E-mail de contato: support@bsf.ai

Informe o motivo da solicitação e a conta que deve ser habilitada.

Todos os endpoints de gerenciamento de tokens exigem autenticação de usuário (middleware UserAuth) e aceitam dois métodos:

Session Cookie (enviado automaticamente após o login pelo navegador)
Access Token (enviado pelo header Authorization, ideal para curl / chamadas programáticas)

Ao usar autenticação por Access Token, envie os seguintes headers:

Header	Obrigatório	Descrição
`Authorization`	Sim	Access Token do usuário

Todos os exemplos com curl abaixo usam autenticação por Access Token. Substitua:

https://api.bsf.ai/ — a URL do seu serviço
{ACCESS_TOKEN} — o seu Access Token de usuário

Caminho base: /api/token

Estrutura de dados

Objeto Token

Campo	Tipo	Descrição
`id`	int	ID do token (chave primária)
`user_id`	int	ID do usuário proprietário
`key`	string	API Key (48 caracteres, gerada automaticamente, com prefixo `sk-`)
`status`	int	Status: `1` Ativo / `2` Desativado / `3` Expirado / `4` Cota esgotada
`name`	string	Nome do token (máximo de 50 caracteres)
`created_time`	int64	Data de criação (timestamp Unix)
`accessed_time`	int64	Data do último acesso (timestamp Unix)
`expired_time`	int64	Data de expiração (timestamp Unix); `-1` significa que nunca expira
`remain_quota`	int	Cota restante
`unlimited_quota`	bool	Se a cota é ilimitada
`used_quota`	int	Cota já consumida
`model_limits_enabled`	bool	Se as restrições de modelo estão ativadas
`model_limits`	string	Modelos permitidos (separados por vírgula, por exemplo `gpt-4,claude-3-opus`)
`allow_ips`	string	Lista de IPs permitidos (separados por quebra de linha `\n`, aceita notação CIDR)
`group`	string	Grupo de canais
`cross_group_retry`	bool	Retentativa entre grupos (só tem efeito no grupo `auto`)

Endpoints da API

1. Listar tokens

GET /api/token/?p={page}&size={pageSize}

Parâmetros de query:

Parâmetro	Tipo	Obrigatório	Descrição
`p`	int	Não	Número da página, começando em 0
`size`	int	Não	Itens por página

Exemplo de resposta:

json

{
  "success": true,
  "message": "",
  "data": {
    "page": 0,
    "page_size": 10,
    "total": 2,
    "items": [
      {
        "id": 1,
        "name": "my-token",
        "status": 1,
        "key": "",
        "created_time": 1710000000,
        "expired_time": -1,
        "remain_quota": 500000,
        "unlimited_quota": false,
        "used_quota": 12000,
        "model_limits_enabled": false,
        "model_limits": "",
        "allow_ips": "",
        "group": "",
        "cross_group_retry": false
      }
    ]
  }
}

Atenção: o campo key vem vazio nas respostas de listagem e não retorna a API Key real.

Exemplo com curl:

bash

curl -X GET 'https://api.bsf.ai/api/token/?p=0&size=10' \
  -H 'Authorization: {ACCESS_TOKEN}'

2. Buscar tokens

GET /api/token/search?keyword={keyword}&token={tokenKey}&p={page}&size={pageSize}

Parâmetros de query:

Parâmetro	Tipo	Obrigatório	Descrição
`keyword`	string	Não	Busca aproximada por nome
`token`	string	Não	Busca pela Key
`p`	int	Não	Número da página
`size`	int	Não	Itens por página

A busca tem limite de frequência (middleware SearchRateLimit). A busca aproximada exige no mínimo 2 caracteres e aceita no máximo 2 curingas.

Exemplo com curl:

bash

# Search by name
curl -X GET 'https://api.bsf.ai/api/token/search?keyword=production&p=0&size=10' \
  -H 'Authorization: {ACCESS_TOKEN}'

# Search by Key
curl -X GET 'https://api.bsf.ai/api/token/search?token=abc123&p=0&size=10' \
  -H 'Authorization: {ACCESS_TOKEN}'

3. Consultar um único token

GET /api/token/{id}

Parâmetros de path:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	int	Sim	ID do token

Exemplo de resposta:

json

{
  "success": true,
  "message": "",
  "data": {
    "id": 1,
    "name": "my-token",
    "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": 1,
    "remain_quota": 500000,
    "..."
  }
}

Exemplo com curl:

bash

curl -X GET 'https://api.bsf.ai/api/token/1' \
  -H 'Authorization: {ACCESS_TOKEN}'

4. Criar um token

POST /api/token/
Content-Type: application/json

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do token, máximo de 50 caracteres
`expired_time`	int64	Não	Data de expiração (timestamp Unix); `-1` para nunca expirar
`remain_quota`	int	Não	Cota restante (para tokens sem cota ilimitada, faixa de 0 a 1.000.000.000 × QuotaPerUnit)
`unlimited_quota`	bool	Não	Se a cota é ilimitada
`model_limits_enabled`	bool	Não	Se as restrições de modelo devem ser ativadas
`model_limits`	string	Não	Modelos permitidos (separados por vírgula)
`allow_ips`	string	Não	Lista de IPs permitidos (separados por quebra de linha, aceita CIDR)
`group`	string	Não	Grupo de canais
`cross_group_retry`	bool	Não	Retentativa entre grupos

Exemplo de requisição:

json

{
  "name": "production-key",
  "expired_time": 1735689600,
  "remain_quota": 1000000,
  "unlimited_quota": false,
  "model_limits_enabled": true,
  "model_limits": "gpt-4,gpt-4o,claude-3-opus",
  "allow_ips": "192.168.1.0/24\n10.0.0.1",
  "group": "default"
}

Resposta:

json

{
  "success": true,
  "message": ""
}

Cada usuário tem um limite máximo de tokens. A criação falha se esse limite for ultrapassado.

Exemplo com curl:

bash

# Create a token with quota and model restrictions
curl -X POST 'https://api.bsf.ai/api/token/' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "production-key",
    "expired_time": 1735689600,
    "remain_quota": 1000000,
    "unlimited_quota": false,
    "model_limits_enabled": true,
    "model_limits": "gpt-4,gpt-4o,claude-3-opus",
    "allow_ips": "192.168.1.0/24\n10.0.0.1",
    "group": "default"
  }'

# Create an unlimited, never-expiring token
curl -X POST 'https://api.bsf.ai/api/token/' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "unlimited-key",
    "expired_time": -1,
    "unlimited_quota": true
  }'

5. Atualizar um token

5a. Atualizar todos os campos modificáveis

PUT /api/token/
Content-Type: application/json

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
`id`	int	Sim	ID do token a ser atualizado
`name`	string	Não	Nome do token
`expired_time`	int64	Não	Data de expiração
`remain_quota`	int	Não	Cota restante
`unlimited_quota`	bool	Não	Se a cota é ilimitada
`model_limits_enabled`	bool	Não	Se as restrições de modelo devem ser ativadas
`model_limits`	string	Não	Modelos permitidos
`allow_ips`	string	Não	Lista de IPs permitidos
`group`	string	Não	Grupo de canais
`cross_group_retry`	bool	Não	Retentativa entre grupos

Exemplo com curl:

bash

# Update token name, quota, and model restrictions
curl -X PUT 'https://api.bsf.ai/api/token/' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "name": "renamed-key",
    "remain_quota": 2000000,
    "unlimited_quota": false,
    "model_limits_enabled": true,
    "model_limits": "gpt-4o,claude-3-5-sonnet",
    "expired_time": 1767225600
  }'

5b. Atualizar apenas o status

PUT /api/token/?status_only=1
Content-Type: application/json

Corpo da requisição:

Campo	Tipo	Obrigatório	Descrição
`id`	int	Sim	ID do token
`status`	int	Sim	`1` Ativar / `2` Desativar

Restrições:

Tokens expirados não podem ser ativados, a menos que a data de expiração seja atualizada
Tokens com a cota esgotada não podem ser ativados, a menos que tenham cota ilimitada

Exemplo com curl:

bash

# Disable a token
curl -X PUT 'https://api.bsf.ai/api/token/?status_only=1' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"id": 1, "status": 2}'

# Enable a token
curl -X PUT 'https://api.bsf.ai/api/token/?status_only=1' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"id": 1, "status": 1}'

Resposta:

json

{
  "success": true,
  "message": "",
  "data": { "...updated token object..." }
}

6. Excluir um token

DELETE /api/token/{id}

Parâmetros de path:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	int	Sim	ID do token

Exemplo com curl:

bash

curl -X DELETE 'https://api.bsf.ai/api/token/1' \
  -H 'Authorization: {ACCESS_TOKEN}'

Resposta:

json

{
  "success": true,
  "message": ""
}

A exclusão é lógica (soft delete) — os dados não são removidos imediatamente.

7. Excluir tokens em lote

POST /api/token/batch
Content-Type: application/json

Corpo da requisição:

json

{
  "ids": [1, 2, 3]
}

Resposta:

json

{
  "success": true,
  "message": "",
  "data": 3
}

data é a quantidade de tokens realmente excluídos.

Exemplo com curl:

bash

curl -X POST 'https://api.bsf.ai/api/token/batch' \
  -H 'Authorization: {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [1, 2, 3]}'

Consulta de uso do token

Este endpoint usa autenticação por Bearer Token (ou seja, a própria API Key consulta o seu uso) e não exige login do usuário.

GET /api/usage/token/
Authorization: Bearer sk-xxxxxxxx

Exemplo com curl:

bash

curl -X GET 'https://api.bsf.ai/api/usage/token/' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Exemplo de resposta:

json

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "my-token",
    "total_usd_granted": 2.024,
    "total_usd_used": 0.024,
    "total_usd_available": 2.0,
    "unlimited_quota": false,
    "model_limits": {
      "gpt-4": true,
      "claude-3-opus": true
    },
    "model_limits_enabled": true,
    "expires_at": 1735689600,
    "user_usd_available": 88.5
  }
}

Campo	Descrição
`total_usd_granted`	Cota total concedida ao token (USD); equivale a `total_usd_available + total_usd_used`
`total_usd_used`	Cota já usada pelo token (USD)
`total_usd_available`	Cota restante disponível no token (USD)
`unlimited_quota`	Se a cota é ilimitada
`model_limits`	Mapeamento das restrições de modelo
`expires_at`	Data de expiração; `0` significa que nunca expira
`user_usd_available`	Saldo restante da conta do usuário (USD). Quando a cota ilimitada está ativada, este campo representa o limite realmente utilizável

Estatísticas diárias de uso do token

GET /api/token/{id}/usage?start_date={start}&end_date={end}

Exige autenticação com login do usuário (igual aos endpoints de gerenciamento de tokens).

Parâmetros de path:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	int	Sim	ID do token

Parâmetros de query:

Parâmetro	Tipo	Obrigatório	Descrição
`start_date`	string	Não	Data inicial, no formato `YYYY-MM-DD`
`end_date`	string	Não	Data final, no formato `YYYY-MM-DD`

Limites:

Sem parâmetros, o padrão é consultar o último 1 dia
No máximo 7 dias; se ultrapassar, o período é truncado automaticamente para start_date + 7 days
Os resultados ficam em cache por 10 minutos para reduzir a carga sobre o banco de dados

Exemplo de resposta:

json

{
  "success": true,
  "data": {
    "token_id": 1,
    "token_name": "my-token",
    "start_date": "2026-03-20",
    "end_date": "2026-03-26",
    "daily": [
      {
        "date": "2026-03-20",
        "usd": 0.35,
        "requests": 12,
        "prompt_tokens": 5000,
        "completion_tokens": 2000
      }
    ]
  }
}

Descrição dos campos de daily:

Campo	Descrição
`date`	Data (YYYY-MM-DD)
`usd`	Gasto do dia (USD)
`requests`	Número de requisições
`prompt_tokens`	Quantidade de tokens de entrada
`completion_tokens`	Quantidade de tokens de saída

Exemplos com curl:

bash

# Query last 1 day (default)
curl -X GET 'https://api.bsf.ai/api/token/1/usage' \
  -H 'Authorization: {ACCESS_TOKEN}'

# Query specific date range (max 7 days)
curl -X GET 'https://api.bsf.ai/api/token/1/usage?start_date=2026-03-20&end_date=2026-03-26' \
  -H 'Authorization: {ACCESS_TOKEN}'

Conversão de unidades de cota

Unidade	Descrição
`quota`	Unidade interna
`USD`	Unidade exibida ao usuário
Conversão	`1 USD = 500,000 quota` (ou seja, US$ 0,002 / 1K tokens)

Formato da resposta de erro

json

{
  "success": false,
  "message": "error message"
}

Solicitação de acesso à API ​

Estrutura de dados ​

Objeto Token ​

Endpoints da API ​

1. Listar tokens ​

2. Buscar tokens ​

3. Consultar um único token ​

4. Criar um token ​

5. Atualizar um token ​

5a. Atualizar todos os campos modificáveis ​

5b. Atualizar apenas o status ​

6. Excluir um token ​

7. Excluir tokens em lote ​

Consulta de uso do token ​

Estatísticas diárias de uso do token ​

Conversão de unidades de cota ​

Formato da resposta de erro ​

Solicitação de acesso à API

Estrutura de dados

Objeto Token

Endpoints da API

1. Listar tokens

2. Buscar tokens

3. Consultar um único token

4. Criar um token

5. Atualizar um token

5a. Atualizar todos os campos modificáveis

5b. Atualizar apenas o status

6. Excluir um token

7. Excluir tokens em lote

Consulta de uso do token

Estatísticas diárias de uso do token

Conversão de unidades de cota

Formato da resposta de erro