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:

bash
export TEAMO_BASE_URL="https://teamorouter.com"

Autenticación

Envía tu API key de TeamoRouter en la cabecera Authorization de cada solicitud:

http
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.

http
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

bash
curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Ejemplo de respuesta

json
{
  "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.

http
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

bash
curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Ejemplo de respuesta

json
{
  "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.

http
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

bash
curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Ejemplo de respuesta

json
{
  "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.

http
GET /v1/billing/balance

Este endpoint no recibe parámetros de consulta. La API key identifica la cuenta.

Ejemplo de solicitud

bash
curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Ejemplo de respuesta

json
{
  "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.

json
{
  "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_time y end_time al conciliar uso y facturación, para que las dos consultas cubran lo mismo.
  • Los precios pueden cambiar. Usa el amount que 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 429 y 5xx.
Ready? Three steps to startLog in to the console · top up · create an API key
DiscordGet community help instantly