API de uso y facturación
Las API de uso y facturación de TeamoRouter te permiten consultar los tokens y el costo de cada solicitud a un modelo, sumar el uso y la facturación de un rango de tiempo y ver el saldo actual de la cuenta.
Este documento describe el contrato de la API. Si hay diferencias, mandan las respuestas reales de producción.
Las cuentas nuevas empiezan con saldo de $0: recarga antes de tu primera solicitud. Puedes recargar desde $5. Si una solicitud devuelve 402 (400 en el formato de OpenAI) con el texto «wallet balance is insufficient», tu saldo está vacío; la URL base y la clave están bien configuradas. Recarga y vuelve a intentar.
Resumen de la API
| Endpoint | Descripción |
|---|---|
GET /v1/billing/requests/{request_id} |
Tokens y costo de una sola solicitud |
GET /v1/billing/costs |
Total facturado a la API key autenticada en un rango de tiempo |
GET /v1/usage |
Total de tokens de la API key autenticada en un rango de tiempo |
GET /v1/billing/balance |
Saldo actual de la cuenta |
Primeros pasos
URL base
Usa la URL base de la API que aparece en la consola de TeamoRouter. En los ejemplos de abajo la llamamos $TEAMO_BASE_URL:
export TEAMO_BASE_URL="https://teamorouter.com"
Autenticación
Envía tu API key de TeamoRouter en la cabecera Authorization de cada solicitud:
Authorization: Bearer sk-teamo-xxx
Guarda tu API key de forma segura. No la pongas en código del frontend, repositorios públicos ni registros. Todas las claves e IDs de los ejemplos son ficticios.
Uso y costo de una solicitud
Con el ID de una solicitud obtienes los tokens y el costo final de esa llamada al modelo.
GET /v1/billing/requests/{request_id}
Parámetros de ruta
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
request_id |
cadena UUID | Sí | ID de solicitud que devuelve la llamada al modelo |
Ejemplo de solicitud
curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $TEAMO_API_KEY"
Ejemplo de respuesta
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1784081234,
"model": "gpt-5.4",
"usage": {
"input_tokens": 1000,
"output_tokens": 500,
"cached_write_tokens": 800,
"cached_read_tokens": 200,
"total_tokens": 2500
},
"amount": {
"value": "0.012680",
"currency": "USD"
}
}
Campos de tokens
| Campo | Descripción |
|---|---|
input_tokens |
Tokens de entrada que no usaron la caché |
output_tokens |
Tokens generados por el modelo |
cached_write_tokens |
Tokens escritos en la caché de prompts |
cached_read_tokens |
Tokens leídos de la caché de prompts |
total_tokens |
Suma de todas las categorías anteriores |
Las categorías que no aplican o que el servicio de origen no informa devuelven 0.
Facturación de un rango de tiempo
Devuelve el total facturado a la API key autenticada en un rango de tiempo. La respuesta básica solo trae datos agregados, no el detalle de cada solicitud.
GET /v1/billing/costs
Parámetros de consulta
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
start_time |
entero | Sí | Inicio del rango, incluido |
end_time |
entero | Sí | Fin del rango, excluido |
El rango no puede superar 90 días. Los rangos más largos devuelven 400 invalid_request.
Ejemplo de solicitud
curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
-H "Authorization: Bearer $TEAMO_API_KEY"
Ejemplo de respuesta
{
"start_time": 1784044800,
"end_time": 1784131200,
"total_amount": {
"value": "1.280000",
"currency": "USD"
},
"requests": 86
}
Uso de tokens de un rango de tiempo
Devuelve el total de tokens de la API key autenticada en un rango de tiempo.
GET /v1/usage
Parámetros de consulta
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
start_time |
entero | Sí | Inicio del rango, incluido |
end_time |
entero | Sí | Fin del rango, excluido |
El rango no puede superar 90 días. Los rangos más largos devuelven 400 invalid_request.
Ejemplo de solicitud
curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
-H "Authorization: Bearer $TEAMO_API_KEY"
Ejemplo de respuesta
{
"start_time": 1784044800,
"end_time": 1784131200,
"usage": {
"input_tokens": 120000,
"output_tokens": 30000,
"cached_write_tokens": 10000,
"cached_read_tokens": 80000,
"total_tokens": 240000
},
"requests": 86
}
Saldo de la cuenta
Devuelve el saldo disponible de la cuenta asociada a la API key actual.
GET /v1/billing/balance
Este endpoint no recibe parámetros de consulta. La API key identifica la cuenta.
Ejemplo de solicitud
curl "$TEAMO_BASE_URL/v1/billing/balance" \
-H "Authorization: Bearer $TEAMO_API_KEY"
Ejemplo de respuesta
{
"balance": {
"value": "85.320000",
"currency": "USD"
}
}
Manejo de errores
Cuando una llamada falla, el cuerpo de la respuesta trae un código de error estable y un mensaje que ayuda a diagnosticar el problema.
{
"error": {
"code": "invalid_request",
"message": "end_time must be greater than start_time"
}
}
Códigos de error comunes
| Estado HTTP | error.type / error.code |
Descripción |
|---|---|---|
400 |
invalid_request |
Parámetros no válidos, por ejemplo un rango de tiempo incorrecto |
401 |
missing_auth_credential / 401 |
Falta la API key |
401 |
invalid_api_key |
La API key no es válida |
404 |
not_found |
El registro de la solicitud no existe o la API key actual no tiene acceso |
429 |
rate_limit_exceeded |
Demasiadas solicitudes; vuelve a intentar más tarde |
500 |
internal_error |
Error interno del servicio |
Recomendaciones
- Usa el mismo
start_timeyend_timeal conciliar uso y facturación, para que las dos consultas cubran lo mismo. - Los precios pueden cambiar. Usa el
amountque viene en los registros históricos en lugar de recalcular cobros pasados con la lista de precios actual. - Configura tiempos de espera y reintentos razonables. Usa espera exponencial para las respuestas
429y5xx.