Credits & nutzungsbasierte Abrechnung

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 gemessene Aktion zusätzlich zu einer Lizenz verkaufen können, mit Kontingenten und Überschreitung. Credits sind optional: Ein Produkt, das nur Plätze verkauft, muss sie nie anfassen.

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 (z. B. render = 1, hd-export = 5). Sie definieren sie pro Produkt.
• 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 (kein Offline-Fallback); für getrennte Maschinen siehe den Abschnitt „Luftdicht getrennte Credit-Blöcke” weiter unten.

In Ihrer Anwendung

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

Jede Sprache ohne SDK nutzt die 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.

Einmalige Einrichtung durch den Anbieter

Konfigurieren Sie Kosten und füllen Sie Pools über die Admin-API (mit dem Admin-Token Ihres Produkts) oder das Dashboard. Legen Sie den Preis einer Aktion fest, erstellen Sie einen an eine Lizenz gebundenen Pool und gewähren Sie Credits:

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. Die vollständige Admin-Oberfläche finden Sie in der HTTP-API-Referenz.

Luftdicht getrennte 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 wieder verbunden ist. So funktionieren nutzungsbasierte Produkte auch in vollständig getrennten Umgebungen. Getrennte Blöcke sind ein Anspruch der höheren selbst gehosteten Stufen.

FAQ

Muss ich Credits verwenden? Nein. Credits sind rein additiv — platzbasierte und unbefristete Lizenzierung funktioniert genau wie zuvor, wenn Sie nie einen Pool konfigurieren.

Was passiert, wenn ein Pool leer ist? consume liefert 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).

Kann eine Abbuchung gefahrlos wiederholt werden? Ja, wenn Sie einen idempotencyKey übergeben. Ein wiederholter Aufruf mit demselben Schlüssel liefert das ursprüngliche Ergebnis und bucht nie erneut ab.