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 Settings de tu Dashboard:
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
| Endpoint | Method | 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 |
logicalModel | string | longitud máxima 100 | Nombre del modelo lógico solicitado |
modelVendor | string | longitud máxima 100 | Proveedor público del modelo |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d |
accessChannel | enum | - | platform o byok |
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 |
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 | default 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, suspended, 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 | default 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 |
Contrato monetario
Semántica de reporting
logicalModel se refiere al modelo lógico 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.accessChannel=platform significa que la solicitud se facturó mediante el canal de plataforma de AI Sonar.accessChannel=byok significa que la solicitud usó su propia clave del proveedor upstream.
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 paginación de billing
/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.aisonar.dev/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"
curl "https://api.aisonar.dev/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,
"used_amount": 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"
}
]
}
Próximos pasos
