Consulta tu saldo desde código con GET /v1/credits

26 de octubre de 2026 · Hyperouter · 3 min de lectura

Las solicitudes se pagan con un saldo prepagado, y una solicitud que el saldo no puede cubrir se rechaza con 402 insufficient_credits. Si prefieres enterarte de un saldo bajo antes de eso, pregúntalo: GET /v1/credits responde con tu saldo, autenticado con la misma clave de API que cualquier otra llamada.

La llamada

curl https://api.hyperouter.app/v1/credits \
  -H "Authorization: Bearer $HYPEROUTER_API_KEY"

La respuesta tiene tres campos, todos cadenas decimales en USD:

Hyperouter retiene lo máximo que puede costar una solicitud antes de ejecutarla, luego cobra lo que se usó y libera el resto (Facturación y límites). Por eso existe held_usd: mientras hay solicitudes en curso, una parte de tu saldo no está libre para gastar. available_usd es el saldo menos las retenciones, y es el número que debes vigilar.

Es el saldo de la cuenta

El saldo pertenece a la cuenta, no a la clave, así que todas las claves de la cuenta ven los mismos números. Una clave con su propio límite de crédito puede seguir siendo rechazada en ese límite con 402 insufficient_credits, aunque available_usd sea grande.

Los campos son cadenas, no floats. Hyperouter cuenta el dinero con exactitud, y una cadena lo mantiene exacto hasta que decides cómo analizarla. En Python, decimal.Decimal la lee directamente. En TypeScript, compara después de Number(...) si unos pocos dígitos de precisión no te importan, y para un umbral de alerta no importan.

Caché

La respuesta incluye Cache-Control: private, no-store, así que un proxy o un cliente que respete el encabezado no la conservará. Léela de nuevo cada vez.

Una comprobación por minuto es más que suficiente para una alerta. El saldo cambia cuando se liquidan las solicitudes y cuando el equipo acredita una recarga, y ninguno de los dos necesita un ciclo más ajustado.

Una alerta de saldo bajo

Un script pequeño, ejecutado desde cron o desde cualquier programador que ya tengas:

import os
import sys
from decimal import Decimal

import requests

THRESHOLD = Decimal("5.00")  # USD; pick your own

res = requests.get(
    "https://api.hyperouter.app/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['HYPEROUTER_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
credits = res.json()

available = Decimal(credits["available_usd"])
if available < THRESHOLD:
    print(f"Hyperouter balance low: {available} USD available", file=sys.stderr)
    sys.exit(1)

La mayoría de los programadores ya saben convertir una salida distinta de cero en un mensaje. La misma comprobación en TypeScript:

const res = await fetch("https://api.hyperouter.app/v1/credits", {
  headers: { Authorization: `Bearer ${process.env.HYPEROUTER_API_KEY}` },
});
if (!res.ok) throw new Error(`credits: HTTP ${res.status}`);

const { available_usd } = await res.json();
if (Number(available_usd) < 5) {
  console.error(`Hyperouter balance low: ${available_usd} USD available`);
  process.exitCode = 1;
}

Si la propia llamada falla con 401, la clave falta, está mal formada, es desconocida o está desactivada; los errores de autenticación enumeran cada caso.

Recargar

Por ahora las recargas son manuales. Abre una solicitud de recarga en el panel con el importe, la referencia del pago y una captura de pantalla del pago. El equipo comprueba el pago y acredita tu saldo. Cada recarga lleva una comisión del 5,5 % del importe pagado, con un mínimo de $0.80, así que fija tu umbral lo bastante alto como para dejar tiempo a que una persona la acredite.

Qué sigue

• Cada respuesta incluye su cargo como usage.cost, y GET /v1/generations/{id} devuelve el registro de cualquier solicitud, así que puedes conciliar el gasto por solicitud.
• Errores sobre los que puedes actuar trata 402 insufficient_credits en un bucle de reintentos.