Skip to content

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 action in 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.

Ihre Anwendunghält den Lizenzschlüsselbalance() · consume()Key-AuthKeyrightPreis = Aktionskosten × Mengeprüft + bucht atomar ababbuchenCredit-Poolan den Lizenzschlüssel gebundenEinheit · RestguthabendryRunPreis einer Aktion ohne AbbuchungidempotencyKeyein Retry liefert erneut — nie doppelt abgebuchtNetzwerkisoliertsignierter Credit-Block offline ausgegeben, bei Verbindung abgeglichen
Ein Credit-Pool ist an einen Lizenzschlüssel gebunden; Ihre Anwendung berechnet Preise und verbraucht daraus mit dem Schlüssel, den sie bereits hält — gefahrlos wiederholbar, online oder aus einem signierten Offline-Block.

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.

Die Übersicht Usage & credits in Keyright mit vier Statistik-Kacheln — Entitled 5.000 renders, Consumed 70 (1 % des gesamten Anspruchs), Available 4.930 renders und Pools 1 (keiner erschöpft) — über einer Tabelle „By pool“, die einen Pool „AI renders“ (acme-app · renders) auflistet, gebunden an die Lizenz LIC-4AF59FF333A887E931AF mit 5.000 zugeteilten, 70 verbrauchten und 4.930 verfügbaren Credits.
Das Dashboard Usage & credits: ein Pool „AI renders“, gebunden an einen Lizenzschlüssel, befüllt mit 5.000 Renderings, 70 verbraucht und 4.930 übrig — dasselbe Guthaben, das Ihre Anwendung mit 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/SVC ist https://keyright.delta1labs.com auf Keyright Cloud oder die URL Ihres eigenen Issuing-Service bei Self-Hosting; die Laufzeitaufrufe balance/consume authentifizieren 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

  1. 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).
  2. Rufen Sie consume für die Aktion mit dryRun: true auf und bestätigen Sie, dass der Preis zurückkommt und das Guthaben unverändert bleibt.
  3. Rufen Sie consume echt mit einem idempotencyKey auf — bestätigen Sie status: ok, dass das Guthaben um die Aktionskosten sinkt und die Nutzung erfasst wird.
  4. Rufen Sie consume erneut mit demselben idempotencyKey auf — bestätigen Sie, dass das erste Ergebnis erneut geliefert und nicht noch einmal abgebucht wird.
  5. Leeren Sie den Pool und bestätigen Sie, dass consume insufficient liefert, ohne abzubuchen.

Siehe auch