Documentación
Grupos de claves
Da a cada uno de tus clientes sus propias claves de API, reúnelas en un grupo, consulta lo que gastó cada cliente y cada clave en cualquier periodo y limita lo que cada cliente puede gastar al mes. Una cuenta, un saldo.
Un grupo es una carpeta de claves de API de tu cuenta, por ejemplo una por cliente: CID000001, CID000002. Una clave de un grupo llama a la API como cualquier otra, y un grupo no tiene saldo, recargas ni inicio de sesión propios; puede tener un límite de gasto mensual sobre todas sus claves. Cada clave está en un grupo o en ninguno.
Configura los grupos en tres pasos
- Crea un grupo. En la página Claves API, elige «Nuevo grupo» y ponle el nombre del cliente.
- Añade claves. Elige «Nueva clave» en el encabezado del grupo para crear una clave dentro. Para archivar una clave que ya tienes, abre su menú y elige «Mover a un grupo».
- Consulta las cifras. La página Claves de API muestra lo que gastó cada clave en este mes natural y el total de cada grupo. La página Uso muestra las mismas claves bajo sus grupos para hoy, los últimos 7 o 30 días, este mes, el mes pasado o los días que elijas, hasta 90.
Consulta un mes y expórtalo
En la página Uso, elige «Mes pasado» (o «Este mes», o «Personalizado» para elegir días) arriba. En «Por clave de API», el encabezado de cada grupo muestra su coste y sus llamadas. El menú de grupos de arriba limita toda la página a un grupo: sus cifras, su gráfico, sus modelos y sus llamadas. «Exportar CSV» descarga lo que muestra la página, con el mismo periodo y el mismo grupo, por clave o por día.
Por clave, el archivo tiene una fila por clave y grupo, con un nombre como kunavo-cost-by-key_2026-10-01_2026-10-31.csv. Incluye cada clave que hizo llamadas en el periodo, también las revocadas, bajo el grupo en el que se hizo cada llamada, y cada clave activa sin llamadas en el grupo en el que está ahora, con 0, para que la lista de claves de cada cliente esté completa. Los grupos siguen el orden del panel, las claves de cada grupo de la más cara a la más barata, y las claves sin grupo al final. Por día, el archivo empieza con una columna date y tiene una fila por cada día en que una clave hizo llamadas en un grupo.
| Columna | Contenido |
|---|---|
group | El grupo en el que se hicieron las llamadas; vacío para las llamadas hechas fuera de todo grupo. Un grupo eliminado después lleva (deleted) tras su nombre. |
key_name | El nombre de la clave. |
key_prefix | El comienzo de la clave, tal como lo muestra el panel. Nunca la clave completa. |
key_status | active o revoked. |
calls | Llamadas hechas con la clave en el periodo. |
errors | De esas llamadas, las que fallaron. Una llamada fallida no cuesta nada. |
input_tokens | Tokens de entrada, incluidas las lecturas y escrituras de caché. |
output_ | Tokens de salida. |
cached_ | De los tokens de entrada, los leídos de la caché de prompts. |
cache_ | De los tokens de entrada, los escritos en la caché de prompts. |
cost_usd | Lo que se cobró por las llamadas, en dólares estadounidenses, con ocho decimales. |
=, +, - o @ se escribe con un apóstrofo delante, para que una hoja de cálculo lo muestre como texto en lugar de ejecutarlo como fórmula.Limita lo que gasta cada grupo al mes
Abre el menú de un grupo en la página Claves de API y elige «Establecer límite mensual». El límite cuenta lo que gastan juntas todas las claves del grupo en un mes natural (UTC): las llamadas que hizo cada clave mientras estaba en el grupo. Una solicitud que haría que el grupo lo superara se rechaza con un 402 y no se cobra nada por ella. Deja el campo en blanco para no poner límite, o pon 0 para pausar todas las claves del grupo sin revocar ninguna.
El límite mensual propio de cada clave sigue aplicándose, y el primer límite que se alcanza es el que rechaza la solicitud. El encabezado del grupo muestra su mes frente al límite, con «Límite alcanzado» en cuanto se rechazan solicitudes, y «En pausa» cuando el límite es 0.
Kunavo escribe a la dirección de tu cuenta cuando un grupo, o una clave con límite propio, ha usado el 80 % de su límite mensual, y otra vez cuando empiezan a rechazarse solicitudes por ese límite: como máximo un correo de cada tipo al mes por límite.
Cómo se cuentan los importes
- El coste es lo que se cobró. El coste de cada llamada es el importe que se descontó de tu saldo cuando terminó. Una llamada fallida no cuesta nada.
- Los meses y los días son UTC. Este mes empieza el día 1 a las 00:00 UTC. En Yangón (UTC+6:30), por ejemplo, octubre termina el 1 de noviembre a las 06:30, hora local. La página Uso indica las fechas del periodo que muestra.
- Una llamada cuenta en el grupo en el que estaba su clave al hacerse la llamada. Si mueves una clave a otro grupo, allí solo cuentan sus llamadas a partir de entonces; sus llamadas anteriores se quedan donde estaban. Por eso el total del mes de un grupo en la página Claves de API puede no coincidir con la suma de las claves que aparecen ahora debajo.
- Una clave revocada se queda en su grupo. Lo que gastó antes de ser revocada sigue contando en los totales de ese grupo y aparece en la exportación.
- Un grupo eliminado conserva sus llamadas. Siguen bajo su nombre, marcado como eliminado, en la página Uso y en la exportación, y el nombre se puede volver a usar para un grupo nuevo.
- Tres lugares, una misma cifra. Para un mismo mes natural, el total de un grupo en la página Claves API, su total en «Este mes» de la página Uso y la suma de sus filas en el CSV coinciden hasta el céntimo.
Preguntas
- ¿Cada grupo tiene su propio saldo? No. Todos los grupos usan el saldo único de tu cuenta. Para limitar lo que puede gastar un cliente, pon un límite mensual a su grupo, o a cada una de sus claves.
- ¿Pueden mis clientes iniciar sesión para ver su uso? No. Los grupos solo los ves tú. Una clave puede consultar su propio uso con GET /v1/usage, que no muestra su grupo. Si su grupo tiene un límite mensual,
GET /v1/balancemuestra a la clave ese límite y lo que ha gastado todo el grupo este mes, pero no el nombre del grupo. - ¿Qué pasa si elimino un grupo? Tú eliges: sus claves siguen funcionando, a partir de entonces sin grupo, o se revocan junto con el grupo. En ambos casos, las llamadas que hicieron se quedan bajo el nombre del grupo.
- ¿Y si una clave pasa de un cliente a otro? Muévela al grupo del otro cliente: sus llamadas cuentan allí a partir de entonces, y sus llamadas anteriores se quedan con el primer cliente.
- ¿Puedo consultar otros periodos? Sí: elige «Personalizado» en la página Uso y hasta 90 días. Para un programa, GET /v1/usage devuelve el coste diario de una clave en el mismo periodo.
Para crear, agrupar, limitar y revocar las claves de un cliente desde tus propias herramientas en lugar de a mano, usa la API de gestión. Sus claves son una credencial aparte y solo funcionan en esa API.