Anwendungsfälle
Nutzung abrechnen & Credits verkaufen
Verkaufen Sie Verbrauch zusätzlich zur Lizenzierung — Renderings, API-Aufrufe, KI-Generierungen, Exporte — mit Keyright-Credit-Pools, die an eine Lizenz gebunden sind: Preis pro Aktion festlegen, einen Pool befüllen, dann aus Ihrer Anwendung Guthaben abfragen und Credits verbrauchen, mit Probelauf-Preisberechnung und idempotenten Wiederholungen, online oder aus einem signierten Offline-Block.
Ziel
Berechnen Sie Nutzung, nicht nur den Platz. Lizenzierung beantwortet „darf dieser Kunde die Software ausführen?“; Credits beantworten „wie viel hat er verbraucht?“ — damit Sie Renderings, API-Aufrufe, KI-Generierungen, Exporte oder jede andere gemessene Aktion zusätzlich zu einer Lizenz verkaufen können, mit Kontingenten und Überschreitung. Ihre Anwendung berechnet den Preis einer Aktion, verbraucht Credits aus einem Pool, der an den Lizenzschlüssel des Kunden gebunden ist, und Keyright zieht sie atomar ab und erfasst die Nutzung.
Durchgehend ist $BASE die URL Ihres Issuing-Service und $TOKEN ein Produkt-Admin-Token — siehe Erste Schritte.
Wann einsetzen
- Nutzen Sie dies, wenn Ihr Produkt Verbrauch verkauft (pro Rendering, pro Export, pro Generierung) — neben oder anstelle einer pauschalen Platzlizenz — mit Kontingenten, Aufladungen und Überschreitung.
- Nutzen Sie dies, wenn Sie Kosten anzeigen müssen, bevor der Nutzer bestätigt (Probelauf-Preisberechnung), oder auf netzwerkisolierten Maschinen messen wollen (signierte Credit-Blöcke).
- Nicht nutzen, wenn Sie nur Plätze sowie unbefristete/befristete Lizenzen verkaufen — Credits sind rein additiv, und ein Produkt, das nie einen Pool konfiguriert, kommt nie mit ihnen in Berührung.
Das Modell
- Credit-Pool — ein Credit-Guthaben, das an einen Lizenzschlüssel gebunden ist. Eine Lizenz kann einen oder mehrere Pools haben (z. B. einen monatlichen „Render“-Pool und einen Auflade-Pool für „Überschreitung“), jeder mit einem von Ihnen gewählten Einheiten-Namen.
- Aktionskosten — was eine Einheit einer gemessenen
actionin Credits kostet. Sie definieren die Kosten pro Produkt (z. B.render= 1,hd-export= 5). - Verbrauchen — Ihre Anwendung gibt Credits für eine Aktion aus; Keyright prüft das Guthaben, zieht es atomar ab und erfasst die Nutzung. Guthaben liest, was übrig ist.
Der Verbrauch nutzt die Authentifizierung per Lizenzschlüssel — denselben Schlüssel, den Ihre Anwendung bereits hat, ohne Admin-Token. Die beiden Aufrufe sind nur online verfügbar (es gibt keinen Offline-Fallback); für getrennte Maschinen siehe Netzwerkisolierte Credit-Blöcke.
Was Sie tun (Anbieterseite)
Einmalige Einrichtung: Legen Sie den Preis jeder Aktion fest, erstellen Sie einen an eine Lizenz gebundenen Pool und befüllen Sie ihn. Das geht über das Dashboard (den Credits-Bereich des Produkts) oder die Admin-API mit Ihrem Produkt-Admin-Token.
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}'
Pools unterstützen außerdem Aufladung, Übertragung, geplante Zurücksetzungen und Schwellenwerte für niedriges Guthaben; die Nutzung ist pro Pool und produktübergreifend für Berichte abfragbar (GET /admin/usage). Die vollständige Admin-Oberfläche finden Sie in der HTTP-API-Referenz.
balance() liest.In Ihrem Code
Jedes SDK stellt dieselben zwei Aufrufe bereit; über reines HTTP sind es POST /v1/balance und POST /v1/consume. Zwei Funktionen machen sie in der Produktion sicher:
dryRun— berechnet den Preis einer Aktion, ohne abzubuchen, z. B. um Kosten anzuzeigen, bevor der Nutzer bestätigt.idempotencyKey— ein von Ihnen angegebener Schlüssel, damit ein wiederholter Aufruf das erste Ergebnis erneut liefert, anstatt doppelt abzubuchen. Übergeben Sie ihn immer bei einer echten Abbuchung, damit ein Netzwerk-Retry nie doppelt abrechnet.
consume liefert einen status von ok, insufficient (zu wenig Credits), unknown_action (keine Kosten konfiguriert), no_pool / ambiguous_pool (kein eindeutiger Pool zum Abbuchen) oder 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
# Any language (raw HTTP) — the same two calls, authenticated with the license key, no admin token
curl -s -X POST "$BASE/v1/balance" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>"}' # remaining balance per pool
curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","dryRun":true}' # price only
curl -s -X POST "$BASE/v1/consume" -H "content-type: application/json" \
-d '{"key":"<LICENSE_KEY>","product":"<your-product>","action":"render","quantity":1,"idempotencyKey":"<txn-id>"}'
# -> { "status":"ok", "totalCost":1, "unit":"renders", "balance":4929 } (fail closed on any non-ok status)
Jede Sprache ohne SDK nutzt diese HTTP-Endpunkte direkt — siehe Die HTTP-API direkt nutzen. Lauffähige Durchläufe all dessen (Operation 6) finden Sie in den SDK-Beispielen auf GitHub.
Wenn ein Pool leer ist, liefert consume insufficient und bucht nicht ab. Ihre Anwendung entscheidet, ob die Aktion blockiert, in eine Warteschlange gestellt oder der Kunde zum Aufladen aufgefordert wird — konfigurieren Sie einen Überschreitungs-Pool, um kontrollierte Überschreitung zu erlauben.
Netzwerkisolierte Credit-Blöcke
Auch getrennte Maschinen können messen: Der Anbieter stellt einen signierten Credit-Block aus (ein festes Kontingent, das der Client offline ausgibt) und gleicht den verbrauchten Betrag ab, sobald die Maschine das nächste Mal wieder verbunden ist. So funktionieren nutzungsbasierte Produkte auch in vollständig netzwerkisolierten Umgebungen. Netzwerkisolierte Blöcke sind ein Entitlement der höheren selbst gehosteten Tiers. Die umfassende Offline-Geschichte finden Sie unter Offline / netzwerkisoliert betreiben.
Cloud vs. Self-Hosting
Das Credit-Modell, die beiden Laufzeitaufrufe und die Admin-Einrichtung sind in beiden Betriebsarten identisch. Die Unterschiede:
- Basis-URL / Token.
$BASE/SVCisthttps://keyright.delta1labs.comauf Keyright Cloud oder die URL Ihres eigenen Issuing-Service bei Self-Hosting; die Laufzeitaufrufebalance/consumeauthentifizieren sich in beiden Fällen mit dem Lizenzschlüssel des Kunden. - Netzwerkisolierte Credit-Blöcke sind eine Funktion der höheren selbst gehosteten Tiers (eine netzwerkisolierte Maschine kann Keyright Cloud gar nicht erreichen), während die Online-Abrechnung in beiden Betriebsarten funktioniert.
Prüfen
- Legen Sie den Preis einer Aktion fest, erstellen Sie einen Pool auf einer Testlizenz und gewähren Sie ihm Credits — bestätigen Sie, dass der Pool das befüllte Guthaben anzeigt (
BalanceAsync/POST /v1/balance). - Rufen Sie
consumefür die Aktion mitdryRun: trueauf und bestätigen Sie, dass der Preis zurückkommt und das Guthaben unverändert bleibt. - Rufen Sie
consumeecht mit einemidempotencyKeyauf — bestätigen Siestatus: ok, dass das Guthaben um die Aktionskosten sinkt und die Nutzung erfasst wird. - Rufen Sie
consumeerneut mit demselbenidempotencyKeyauf — bestätigen Sie, dass das erste Ergebnis erneut geliefert und nicht noch einmal abgebucht wird. - Leeren Sie den Pool und bestätigen Sie, dass
consumeinsufficientliefert, ohne abzubuchen.
Siehe auch
- Erste Schritte — Ihre erste Lizenz ausstellen und verifizieren.
- Upgrades verkaufen & Versionen steuern — steuern, welche Builds eine Lizenz nutzen darf.
- Offline / netzwerkisoliert betreiben — signierte Offline-Leases, Lizenzdateien und Credit-Blöcke.
- HTTP-API-Referenz — die vollständige Übersicht der Admin- und Laufzeit-Endpunkte.