API de gestión

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Resumen

La API de gestión te permite consultar los totales de saldo de la organización, administrar las claves API de la organización y consultar uso y facturación por clave sin usar una clave estándar de inferencia. Emite el token de gestión desde la página Configuración de tu panel:

Authorization: Bearer mt-your-management-token

Los tokens de gestión son distintos de las claves API de inferencia. Usa mt-... para /v1/management/* y sk-... para endpoints de inferencia como /v1/responses.

Endpoints disponibles

Punto de conexión	Método	Descripción
`/v1/management/balance`	GET	Devuelve los totales actuales de saldo de la organización
`/v1/management/api-keys`	GET	Lista las claves API administradas por usuarios de la organización actual
`/v1/management/api-keys`	POST	Crea una nueva clave API de usuario
`/v1/management/api-keys/{keyId}`	PATCH	Actualiza nombre, límite de uso, modelos permitidos, caducidad o estado
`/v1/management/api-keys/{keyId}/usage`	GET	Devuelve el detalle paginado de uso de una clave específica
`/v1/management/api-keys/{keyId}/billing`	GET	Devuelve el desglose agregado de facturación de una clave específica

Contrato de filtros de uso

GET /v1/management/api-keys/{keyId}/usage admite los siguientes parámetros de consulta:

Parámetro	Tipo	Valor predeterminado / límites	Notas
`page`	integer	predeterminado `1`, mínimo `1`	Número de página basado en 1
`limit`	integer	predeterminado `50`, mínimo `1`, máximo `100`	Tamaño de página
`model`	string	longitud máxima `100`	Nombre del modelo solicitado
`modelVendor`	string	longitud máxima `100`	Proveedor público del modelo
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	Límite inferior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`
`endDate`	string	-	Límite superior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`

Si startDate y endDate están presentes, startDate debe ser anterior o igual a endDate.

Contrato del cuerpo de la clave API

POST /v1/management/api-keys

Campo	Tipo	Valor predeterminado / límites	Notas
`name`	string	requerido, predeterminado `Default Key`, longitud `1-50`	Nombre visible, recortado en el servidor
`limitAmount`	number \| null	mínimo `0`, máximo de entrada `1000000`	`null` o omitido = ilimitado, `0` = cuota cero. Los valores positivos se normalizan a un límite almacenado que no puede superar `100000` USD equivalente.
`limitCurrency`	enum	predeterminado `USD`	Solo USD. Enviar `CNY` devuelve `400 currency_retired`.
`models`	string[]	predeterminado `[]`	Lista opcional de modelos lógicos permitidos
`expiresAt`	string \| null	datetime RFC3339	`null` significa sin caducidad

PATCH /v1/management/api-keys/

Campo	Tipo	Valor predeterminado / límites	Notas
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	longitud `1-50`	Nombre visible actualizado
`limitAmount`	number \| null	mínimo `0`, máximo de entrada `1000000`	`null` = ilimitado, `0` = cuota cero. Los valores positivos se normalizan a un límite almacenado que no puede superar `100000` USD equivalente.
`limitCurrency`	enum	predeterminado `USD`	Solo USD. Enviar `CNY` devuelve `400 currency_retired`.
`models`	string[]	-	Lista actualizada de modelos lógicos permitidos
`expiresAt`	string \| null	datetime RFC3339	`null` elimina la caducidad

Debe proporcionarse al menos un campo de PATCH.

Campos monetarios

Los campos monetarios de solicitudes y respuestas de la API de gestión solo admiten USD.
limitCurrency usa USD de forma predeterminada; enviar CNY devuelve 400 currency_retired.

Semántica de reporting

model se refiere al modelo público solicitado por el llamador.
modelVendor se refiere al proveedor público del modelo, no a la ruta física oculta.
scene es la escena pública de la solicitud derivada del endpoint o del tipo de tarea.

Las respuestas exponen solo campos públicos de facturación y reporting. Los detalles internos de enrutamiento y los metadatos físicos del proveedor permanecen ocultos.

Los elementos de /usage pueden incluir billing_transaction_id una vez que la solicitud subyacente haya alcanzado el estado de liquidación. Usa request_id + billing_transaction_id para conciliación a nivel de solicitud.

Nota sobre la paginación de facturación

/usage está paginado. /billing es actualmente un endpoint agregado y no devuelve metadatos de paginación estilo page / limit. Si necesitas registros de línea, usa /usage.

Ejemplo rápido

Empieza consultando el saldo de la organización con el token de gestión actual.

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

Luego lista las API keys disponibles para ese mismo token de gestión.

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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Base

Texto

Archivos y lotes

Imágenes

Audio y tiempo real

Música

Video y recursos

Worlds

3D

Trabajos asíncronos

Gemini nativo

Administración

Resumen

Endpoints disponibles

Contrato de filtros de uso

Contrato del cuerpo de la clave API

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Campos monetarios

Semántica de reporting

Nota sobre la paginación de facturación

Ejemplo rápido

Próximos pasos

​Resumen

​Endpoints disponibles

​Contrato de filtros de uso

​Contrato del cuerpo de la clave API

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​Campos monetarios

​Semántica de reporting

​Nota sobre la paginación de facturación

​Ejemplo rápido

​Próximos pasos

Resumen

Endpoints disponibles

Contrato de filtros de uso

Contrato del cuerpo de la clave API

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Campos monetarios

Semántica de reporting

Nota sobre la paginación de facturación

Ejemplo rápido

Próximos pasos