Skip to content

Guide

Crédits et usage mesuré

Vendez de la consommation par-dessus les licences avec les crédits Keyright : des réserves de crédits liées à une licence, des coûts par action, la consultation du solde et la consommation de crédits depuis votre application (avec tarification à blanc et réessais idempotents), ainsi que la configuration initiale de l'éditeur.

Les licences répondent à « ce client a-t-il le droit d’exécuter le logiciel ? ». Les crédits répondent à « combien en a-t-il consommé ? », pour que vous puissiez vendre des rendus, des appels d’API, des générations d’IA, des exports ou toute action mesurée par-dessus une licence, avec des quotas et du dépassement. Les crédits sont facultatifs : un produit qui ne vend que des sièges n’a jamais à y toucher.

Le modèle

  • Réserve de crédits — un solde de crédits lié à une clé de licence. Une licence peut avoir une ou plusieurs réserves (par exemple une réserve mensuelle de « rendus » et une réserve de recharge pour le « dépassement »), chacune avec un nom d’unité que vous choisissez.
  • Coût d’action — ce que coûte en crédits une unité d’une action mesurée (p. ex. render = 1, hd-export = 5). Vous les définissez par produit.
  • Consommer — votre application dépense des crédits pour une action ; Keyright vérifie le solde, le débite de façon atomique et enregistre l’usage. Solde lit ce qu’il reste.

La consommation utilise l’authentification par clé de licence — la clé que votre application possède déjà, sans jeton d’administration. Les deux appels sont uniquement en ligne (pas de repli hors ligne) ; pour les machines déconnectées, voir la section « Blocs de crédits hors ligne » plus bas.

Dans votre application

Chaque SDK expose les deux mêmes appels ; en HTTP brut ce sont POST /v1/balance et POST /v1/consume. Deux fonctionnalités les rendent sûrs en production :

  • dryRun — tarifie une action sans débiter, p. ex. pour afficher un coût avant que l’utilisateur ne confirme.
  • idempotencyKey — une clé que vous fournissez pour qu’un appel réessayé rejoue le premier résultat au lieu de débiter deux fois. Passez-la toujours pour un débit réel, ainsi un réessai réseau ne facture jamais en double.

consume renvoie un status parmi ok, insufficient (crédits insuffisants), unknown_action (aucun coût configuré), no_pool / ambiguous_pool (pas de réserve unique à débiter) ou not_found.

// .NET
var pools = await client.BalanceAsync(licenseKey);          // remaining balance per pool
var quote = await client.ConsumeAsync(licenseKey, "render", dryRun: true);   // price only
var res   = await client.ConsumeAsync(licenseKey, "render", quantity: 1, idempotencyKey: txnId);
if (res.Status == "ok") Console.WriteLine($"charged {res.TotalCost} {res.Unit}, {res.Balance} left");
// Node.js
const { pools } = await client.balance(licenseKey);
const quote = await client.consume(licenseKey, 'render', { dryRun: true });
const res   = await client.consume(licenseKey, 'render', { quantity: 1, idempotencyKey: txnId });
# Python
pools = client.balance(license_key)
quote = client.consume(license_key, "render", dry_run=True)
res   = client.consume(license_key, "render", quantity=1, idempotency_key=txn_id)
// Java
List<PoolBalance> pools = client.balance(licenseKey);
ConsumeResult quote = client.consume(licenseKey, "render", 1, null, true);        // dry run
ConsumeResult res   = client.consume(licenseKey, "render", 1, txnId, false);      // real charge

Tout langage sans SDK utilise directement les endpoints HTTP — voir Utiliser l’API HTTP directement. Des parcours exécutables de tout ce qui précède (opération 6) se trouvent dans les exemples de SDK sur GitHub.

Configuration initiale de l’éditeur

Configurez les coûts et alimentez les réserves depuis l’API d’administration (avec le jeton d’administration de votre produit) ou le tableau de bord. Tarifez une action, créez une réserve liée à une licence et accordez des crédits :

SVC=https://keyright.delta1labs.com
# 1. what an action costs
curl -X POST "$SVC/admin/products/<your-product>/action-costs" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"action":"render","credits":1}'
# 2. a pool bound to a license key  (-> returns {"id":"pool_..."})
curl -X POST "$SVC/admin/credit-pools" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"licenseId":"<LICENSE_KEY>","product":"<your-product>","name":"Render credits","unit":"renders"}'
# 3. fund it
curl -X POST "$SVC/admin/credit-pools/<POOL_ID>/grant" \
     -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"amount":1000}'

Les réserves prennent aussi en charge la recharge, le transfert, les réinitialisations planifiées et les seuils de solde bas ; l’usage est interrogeable par réserve et entre produits pour le reporting. Voir la référence de l’API HTTP pour toute la surface d’administration.

Blocs de crédits hors ligne

Les machines déconnectées peuvent elles aussi mesurer : l’éditeur émet un bloc de crédits signé (une allocation fixe que le client dépense hors ligne) et réconcilie le montant dépensé à la reconnexion de la machine. Les produits basés sur l’usage continuent ainsi de fonctionner sur des déploiements totalement hors ligne. Les blocs hors ligne sont un droit des niveaux auto-hébergés supérieurs.

FAQ

Dois-je utiliser les crédits ? Non. Les crédits sont purement additifs — les licences par siège et perpétuelles fonctionnent exactement comme avant si vous ne configurez jamais de réserve.

Que se passe-t-il quand une réserve est épuisée ? consume renvoie insufficient et ne débite pas. Votre application décide de bloquer l’action, de la mettre en file d’attente ou d’inviter le client à recharger (configurez une réserve de dépassement pour autoriser un dépassement contrôlé).

Un débit peut-il être réessayé sans risque ? Oui, si vous passez une idempotencyKey. Un appel répété avec la même clé renvoie le résultat d’origine et ne débite jamais de nouveau.