外部ウォレット

外部ウォレットは、あなたが運用するサービスです。各顧客の共有予算を保持し、専用の Nodaro Cloud デプロイメントは、支出する前にこのサービスに問い合わせます。Nodaro は、生成ごとに、実行前にクレジットの確保をウォレットに依頼し、その後に正確な金額を精算し、残高を読み取って顧客に表示します。デプロイメントの請求アカウントは、それでもプラットフォームの利用分を自分のプリペイド残高から支払いますが、そのうちどれだけを各顧客が使えるかは、すべてのプロダクトを通じて、ウォレットが決めます。

仕組み

• 請求アカウントが支払います。デプロイメントは、1 つの請求アカウント（サーフェスプロファイルの billing.payerAccount）を指定し、そのプリペイド残高が、デプロイメント上のすべての操作の代金を支払います。エディションとサーフェスプロファイルを参照してください。
• SSO が顧客を識別します。顧客は、デプロイメントの SSO プロバイダーを通じてログインします。顧客に対するプロバイダーのサブジェクトは sso_subject として送られ、あなたのウォレットはこれによって顧客を認識します。
• ウォレットが判断します。単一ノードのリクエストとワークフローのノードのそれぞれについて、Nodaro はまず請求アカウントのプリペイド残高を確認し、そのうえで、顧客の共有予算に対する確保をあなたのウォレットに依頼します。顧客のローカルな Nodaro クレジット残高は関係しません。

プリペイド残高が空の場合、ウォレットに問い合わせる前にリクエストが止まることがあります。一度問い合わせが行われたら、その顧客の共有予算については、ウォレットの判断が最終的なものになります。

デプロイメントを設定する

API とワーカーの両方に、次の環境変数を設定します。

• 最初の 3 つは、まとめて設定します。デプロイメントの既存の請求方法を維持するには、3 つすべてを未設定のままにします。
• ローカルの利用枠をオフにします。ユーザーごとの利用枠の強制、billing.allowances: "enforce" は、オフである必要があります。この 2 つを組み合わせた設定は、有効化の時点で拒否されます。
• 単位を先に決めます。ウォレットを有効化する前に、Nodaro のクレジットと自分のプロダクトの予算との換算方法を決めておきます。サーフェスプロファイルの billing.unitRate と billing.unitLabel をそれに合わせて設定すると、両方のプロダクトで同じ数字が表示されます。

リクエストの契約

Nodaro は、すべての呼び出しを POST で送ります。JSON ボディには contract: 1 と unit: "nodaro_credit" が含まれ、ヘッダーには Authorization: Bearer <token> が付きます。金額は Nodaro のクレジットです。あなたのウォレットが管理する明示的な換算を経ずに、自分のプロダクトの単位として読み取らないでください。

確保

{
  "contract": 1,
  "unit": "nodaro_credit",
  "action": "reserve",
  "operation_id": "a3354131-4e5e-43a6-8f61-3914f09c658e",
  "job_id": null,
  "user_id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
  "sso_provider": "partner",
  "sso_subject": "customer-123",
  "model_identifier": "example-model",
  "reserved_credits": 30
}

応答する前に、顧客の共有予算のうち利用可能な分から、その金額をアトミックに確保してください。リクエストを許可する場合は、次のように応答します。

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","decision":"allow","reserved_credits":30}

予算が不足している場合や、支出が許可されていないアカウントの場合は、同じエンベロープで HTTP 200 を返し、"decision": "deny" とします。金額は不要です。サービス側のエラーには、2xx 以外のステータスで応答してください。

あなたのウォレットが許可しない限り、モデルには何も届きません。タイムアウト、形式が正しくない応答、金額や ID の不一致、識別情報の欠落、拒否のいずれも、リクエストを止めます。このリクエストの Idempotency-Key ヘッダーは <operation_id>:reserve です。

精算または解放

処理が終わると、Nodaro は同じ操作のフィールドに "action": "settle" と actual_credits を付けて送ります。その金額どおりに課金し、確保の残りを解放してください。0 での精算は、すべてを解放します。

{"contract":1,"unit":"nodaro_credit","operation_id":"a3354131-4e5e-43a6-8f61-3914f09c658e","settled":true,"actual_credits":12}

• キーは <operation_id>:settle です。配信は少なくとも 1 回です。再試行では、再度課金せずに、最初の結果を返す必要があります。
• 矛盾するリクエストは拒否します。同じ操作に対して、識別情報、確保の上限、最終的な金額のいずれかが異なるリクエストは拒否してください。
• 遅れた確保より先に、精算が届くことがあります。0 での精算は、まだ知らない操作であっても、永続的な最終記録を作成する必要があります。その後に届く確保が、その記録を再び開いてはいけません。
• 確保に有効期限はありません。生成と、その結果に対する人によるレビューは、どの HTTP リクエストよりも長く続くことがあります。各確保は精算されるまで保持し、べき等性の記録も保持してください。コールバックが遅れているという理由だけで、有効な確保を解放しないでください。

残高

{"contract":1,"unit":"nodaro_credit","action":"balance","user_id":"5bf0d884-47b1-468e-a7b2-2433f957b267","sso_provider":"partner","sso_subject":"customer-123"}

{"contract":1,"unit":"nodaro_credit","sso_subject":"customer-123","available_credits":250}

• 利用可能とは、確保後の金額です。available_credits は、すべてのプロダクトを通じて、未精算の確保をすべて除いた金額です。
• ここでは小数を使えます。残高は小数になることがあり、課金可能な 1 クレジットに満たない残りも表示できます。確保と精算の金額は、常に整数のクレジットです。
• スタジオには 1 つの数字だけが表示されます。スタジオは、残高を一度だけデプロイメントの表示単位に変換し、ユーザーごとの利用枠の表示は隠します。残高を取得できない場合は、不明として表示されます。
• 競合は確保で決まります。リクエストが同時に届いた場合、判断の基準になるのは、残高ではなく確保の呼び出しです。

配信と復旧

• Nodaro は、それぞれの精算をすぐに配信しようとします。失敗した場合は、1 分ごとに動くワーカーが、最大 1 時間のバックオフで再試行します。確認されていない精算は、配信されるまで保持されます。
• Nodaro が自動的にキャンセルするのは、一度も許可されなかった確保だけです。許可されて実行中のジョブは、通常のジョブの復旧に従います。
• 操作が未完了の間は、ウォレットの設定を削除したり、別のウォレットに向けたりしないでください。トークンを再発行する場合は、同じウォレットの上で再発行してください。

料金の確認

GET /v1/deployment-billing/pricing は、あなたのウォレット自身の表示や計画のために、デプロイメントの価格表を返します。請求アカウントのセッション、またはその請求連携キーのいずれかが必要です。

• メディアのバリアントとテキストの操作は、その時点で有効な価格に基づいて解決されます。価格が設定されていないバリアントは、エラーコードとともに null のままです。
• 設定、数量、長さ、実測の使用量によって、最終的な金額は変わることがあります。計上には、確保と精算の金額を使い、このリストにある基本料率は使わないでください。
• 変更を検出するには、If-None-Match を使った完全なリクエストを優先してください。since パラメーターは価格の行のタイムスタンプに従うため、実行時の設定のすべての変更を検知できるわけではありません。