Administración
API de gestión
Administra el saldo de la organización, las claves API y el uso y facturación por clave mediante un token de gestión.
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.
Crea un token de gestión en Dashboard → API → Management Tokens:
Authorization: Bearer mt-your-management-tokenLos 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 | opcional, predeterminado Default Key, longitud 1-50 | Nombre visible, recortado en el servidor |
limitAmount | number | string | null | 0–100000 USD | null significa sin límite; 0 impide el gasto. Las cadenas decimales admiten hasta 6 decimales. Al crear la clave, omitir este campo significa sin límite. |
limitCurrency | enum | predeterminado USD | Solo USD. Enviar CNY devuelve 400 currency_retired. |
models | string[] | predeterminado [] | Lista opcional de modelos lógicos permitidos |
deliveryPolicy | string | null | auto, verified, official, null | null hereda la política de entrega del espacio de trabajo. |
expiresAt | string | null | datetime RFC3339 | null significa sin caducidad |
PATCH /v1/management/api-keys/{keyId}
| Campo | Tipo | Valor predeterminado / límites | Notas |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | longitud 1-50 | Nombre visible actualizado |
limitAmount | number | string | null | 0–100000 USD | null significa sin límite; 0 impide el gasto. Las cadenas decimales admiten hasta 6 decimales. |
limitCurrency | enum | predeterminado USD | Solo USD. Enviar CNY devuelve 400 currency_retired. Si se especifica, también se requiere limitAmount. |
models | string[] | - | Lista actualizada de modelos lógicos permitidos |
deliveryPolicy | string | null | auto, verified, official, null | null hereda la política de entrega del espacio de trabajo. |
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.
limitCurrencyusaUSDde forma predeterminada; enviarCNYdevuelve400 currency_retired.
Semántica de reporting
modelse refiere al modelo público solicitado por el llamador.modelVendorse refiere al proveedor público del modelo, no a la ruta física oculta.scenees 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
/usagepueden incluirbilling_transaction_iduna vez que la solicitud subyacente haya alcanzado el estado de liquidación. Usarequest_id+billing_transaction_idpara 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.
Solicitud
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.
Solicitud
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"Respuesta
{
"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
}
}