Vérifier votre solde depuis le code avec GET /v1/credits

26 octobre 2026 · Hyperouter · 3 min de lecture

Les requêtes sont payées sur un solde prépayé, et une requête que le solde ne peut pas couvrir est refusée avec 402 insufficient_credits. Si vous préférez être averti d’un solde bas avant d’en arriver là, demandez-le : GET /v1/credits répond avec votre solde, authentifié par la même clé API que tous les autres appels.

L’appel

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

La réponse a trois champs, tous des chaînes décimales en USD :

Hyperouter bloque le maximum qu’une requête peut coûter avant son exécution, puis débite ce qui a été utilisé et libère le reste (Facturation et limites). C’est la raison d’être de held_usd : tant que des requêtes sont en cours, une partie de votre solde n’est pas libre. available_usd est le solde moins les montants bloqués, et c’est le chiffre à surveiller.

C’est le solde du compte

Le solde appartient au compte, pas à la clé : toutes les clés du compte voient donc les mêmes chiffres. Une clé qui a sa propre limite de crédit peut quand même être refusée à cette limite avec 402 insufficient_credits, même lorsque available_usd est élevé.

Les champs sont des chaînes, pas des flottants. Hyperouter compte l’argent exactement, et une chaîne le garde exact jusqu’à ce que vous décidiez comment l’analyser. En Python, decimal.Decimal la lit directement. En TypeScript, comparez après Number(...) si quelques chiffres de précision ne comptent pas pour vous, ce qui est le cas pour un seuil d’alerte.

Cache

La réponse porte Cache-Control: private, no-store : un proxy ou un client qui respecte l’en-tête ne la conservera pas. Lisez-la à nouveau chaque fois.

Une vérification par minute suffit largement pour une alerte. Un solde bouge lorsque des requêtes se règlent et lorsque l’équipe crédite une recharge, et ni l’un ni l’autre n’exige une boucle plus serrée.

Une alerte de solde bas

Un petit script, lancé depuis cron ou n’importe quel planificateur que vous avez déjà :

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)

Un code de sortie non nul est quelque chose que la plupart des planificateurs savent déjà transformer en message. La même vérification 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 l’appel lui-même échoue avec 401, la clé est absente, mal formée, inconnue ou désactivée ; les erreurs d’authentification détaillent chaque cas.

Recharger

Les recharges sont manuelles pour l’instant. Ouvrez une demande de recharge dans le tableau de bord avec le montant, la référence du paiement et une capture d’écran du paiement. Notre équipe vérifie le paiement et crédite votre solde. Chaque recharge supporte des frais de 5,5 % du montant payé, avec un minimum de 0,80 $ : fixez donc votre seuil assez haut pour laisser à une personne le temps de la créditer.

Et ensuite

• Chaque réponse porte son coût dans usage.cost, et GET /v1/generations/{id} renvoie l’enregistrement de n’importe quelle requête : vous pouvez ainsi rapprocher les dépenses requête par requête.
• Des erreurs sur lesquelles agir traite de 402 insufficient_credits dans une boucle de nouvelles tentatives.