Resumen
La API de administración te permite gestionar las API Keys de la organización y consultar uso y facturación por clave sin usar una API Key estándar de inferencia.
Puedes emitir y rotar el token de administración desde la página Settings del Dashboard.
Authorization: Bearer mt-your-management-token
Los tokens de administración son distintos de las API Keys de inferencia. Usa mt-... para /v1/management/* y sk-... para endpoints de inferencia como /v1/responses.
Endpoints disponibles
| Endpoint | Method | Descripción |
|---|
/v1/management/api-keys | GET | Lista las API Keys de usuario de la organización actual |
/v1/management/api-keys | POST | Crea una nueva API Key de usuario |
/v1/management/api-keys/{keyId} | PATCH | Actualiza nombre, límite de uso, modelos permitidos, vencimiento o estado |
/v1/management/api-keys/{keyId}/usage | GET | Recupera el detalle de uso paginado para una clave concreta |
/v1/management/api-keys/{keyId}/billing | GET | Recupera el desglose agregado de facturación para una clave concreta |
Contrato de filtros de uso
GET /v1/management/api-keys/{keyId}/usage admite los siguientes parámetros de consulta.
| Parámetro | Tipo | Valores por defecto / límites | Descripción |
|---|
page | integer | valor por defecto 1, mínimo 1 | Número de página empezando en 1 |
limit | integer | valor por defecto 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 se envían a la vez, startDate debe ser anterior o igual a endDate.
Contrato del cuerpo de API Key
POST /v1/management/api-keys
| Campo | Tipo | Valores por defecto / límites | Descripción |
|---|
name | string | obligatorio, valor por defecto Default Key, longitud 1-50 | Nombre visible; el servidor recorta espacios al inicio y al final |
limitAmount | number | null | mínimo 0, máximo 100000 | null u omitido = ilimitado, 0 = cuota cero, valor positivo = tope de gasto en USD |
limitCurrency | enum | valor por defecto USD | Opcional: USD o CNY. Si se establece en CNY, limitAmount se interpreta en RMB y el servidor lo convierte a USD antes de guardarlo |
models | string[] | valor por defecto [] | Lista opcional de modelos lógicos permitidos |
expiresAt | string | null | datetime RFC3339 | null significa sin vencimiento |
PATCH /v1/management/api-keys/
| Campo | Tipo | Valores por defecto / límites | Descripción |
|---|
status | enum | - | active, inactive, revoked |
name | string | longitud 1-50 | Nombre visible actualizado |
limitAmount | number | null | mínimo 0, máximo 100000 | null = ilimitado, 0 = cuota cero |
limitCurrency | enum | valor por defecto USD | Opcional: USD o CNY. Si se establece en CNY, limitAmount se interpreta en RMB y el servidor lo convierte a USD antes de guardarlo |
models | string[] | - | Lista actualizada de modelos lógicos permitidos |
expiresAt | string | null | datetime RFC3339 | null elimina el vencimiento |
Contrato monetario
- De forma predeterminada,
limitAmount en la solicitud se interpreta en USD. Si estableces limitCurrency: "CNY", puedes enviar un tope en RMB y el servidor lo convertirá a USD con el tipo de cambio actual antes de guardarlo.
- Los campos monetarios de la respuesta conservan el valor original en USD y agregan un acompañante en RMB con el sufijo
_cny.
exchange_rate se devuelve junto con los metadatos de la API key y representa la tasa USD→CNY usada para cada valor *_cny de esa respuesta.
Semántica de reporting
logicalModel se refiere al modelo lógico público solicitado por quien llama.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ó a través del canal de plataforma de LemonData.accessChannel=byok significa que la solicitud usó tu propia clave del proveedor upstream.
Las respuestas solo exponen campos públicos de facturación y reporting. Los detalles de routing interno y la metadata física del proveedor permanecen ocultos.
Nota sobre la paginación de billing
/usage está paginado. /billing es actualmente un endpoint agregado y no devuelve metadata de paginación tipo page / limit. Si necesitas registros detallados línea por línea, usa /usage.
Ejemplo rápido
Empieza listando las API Keys disponibles para el token de administración actual.
curl "https://api.lemondata.cc/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_cny": 3600.0,
"used_amount": 148.25,
"used_amount_cny": 1067.4,
"exchange_rate": 7.2,
"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"
}
]
}
Siguientes pasos
