クレジット

クレジットは、Nodaro Cloud での支払いの単位です。API は、料金を常にクレジットで報告し、金額では報告しません。クレジットのエンドポイントは、残高とクレジットの履歴を返し、モデルや実行の料金を開始前に算出します。また、クライアントが通信しているデプロイメントが、そもそも使用量を計測しているかどうかも伝えます。

クレジットのエンドポイントは、Nodaro Cloud にだけあります。Community エディションと Business エディションにはクレジットの仕組みがないため、これらのルートは 404 を返します。例外は GET /v1/billing/surface で、すべてのエディションで応答します。

エンドポイント

これらのルートには、ほかのすべてのルートと同じトークンを使います。個人用 API トークン、OAuth トークン、セッションの JWT のいずれかです。

残高を読み取る

curl -s https://app.nodaro.ai/v1/credits/balance \
  -H "Authorization: Bearer $NODARO_API_KEY"

{ "total": 1250, "subscription": 1000, "topup": 250, "tier": "pro", "effectiveTier": "pro" }

const balance = await client.credits.balance()
console.log(`${balance.total} credits (${balance.effectiveTier})`)

total は、subscription と topup の合計です。tier は、保存されているサブスクリプションのティアで、free や pro などです。effectiveTier は、Nodaro が実際に適用するティアです。payg は、サブスクリプションはないもののクレジットを購入済みであることを示します。この場合、すべてのモデルが使え、ウォーターマークも 1 日の上限もありません。

SDK の client.credits.balance() が読み取る GET /v1/user/credits は、さらに多くの情報を返します。

使用時には、サブスクリプションのクレジットが先に使われます。サブスクリプションのクレジットは請求サイクルごとにリセットされ、チャージしたクレジットは購入から 12 か月間有効です。

クレジットの課金の流れ

• ジョブの開始時に確保されます。生成は、実行の前にその料金を確保します。残高が足りない場合、呼び出しは 402 insufficient_credits を返し、required と、ほとんどのアカウントでは balance も返します。ワークフローの実行には、最も高くなる場合の料金を賄えるだけのクレジットが必要です。
• 結果を返したときに請求されます。確保された分が、そのまま請求になります。
• 結果を返さなければ返還されます。モデルのセーフティフィルターやデプロイメントのポリシーでブロックされた生成は、必ず返還されます。キャンセルされたジョブも同様です。
• 実際に実行される内容で料金が決まります。選んだモデルに合わせてサーバーが設定を補正した場合、確保される額も補正後の値に従います。パラメーターの補正を参照してください。

ジョブの credit_status と取引の status は、同じ段階をたどります。まず reserved、次に committed か refunded です。そのため、クレジットが返還されたかどうかは、ジョブ自体から判断できます。ジョブのクレジットを参照してください。

取引履歴

GET /v1/credits/transactions は、クレジットの履歴を新しい順に返します。

curl -s "https://app.nodaro.ai/v1/credits/transactions?limit=2" \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": [
    {
      "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "created_at": "2026-09-26T14:03:11.284Z",
      "credits_used": 45,
      "action": "generate-image",
      "provider": "nano-banana-pro",
      "status": "committed",
      "metadata": { "model": "nano-banana-pro", "from_sub": 45, "from_topup": 0 },
      "payer": "user",
      "workspaceId": null
    }
  ],
  "nextCursor": "2026-09-26T14:03:11.284Z"
}

metadata に入るのは、該当する場合の次のキーだけです。model、from_sub と from_topup（どちらの残高から支払ったか）、is_app_run、allowance_delta、web_free_mode、status、loop_trim_refunded、surround_refine_refunded です。

行がそれ以上ない場合、nextCursor は null です。

実行前に料金を確認する

モデルの料金は設定によって変わることがあるため、バリエーションの ID には設定が含まれます。たとえば nano-banana-pro:4K や gpt-image-2:2K です。

curl -s -X POST https://app.nodaro.ai/v1/credits/model-costs \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models": ["nano-banana-pro", "nano-banana-pro:4K", "gpt-image-2:2K"]}'

{
  "data": { "nano-banana-pro": 45, "nano-banana-pro:4K": 60, "gpt-image-2:2K": 30 },
  "missing": [],
  "errors": []
}

const { data, missing } = await client.credits.modelCosts(['nano-banana-pro', 'nano-banana-pro:4K'])
console.log(data['nano-banana-pro:4K'])
if (missing.length) console.warn('No price for:', missing)

料金のない ID は missing に、料金の取得に失敗した ID は errors に入ります。そのため、1 つの不正な ID でリクエスト全体が失敗することはありません。これらの ID には、0 ではなくダッシュを表示してください。上の料金は例です。実際の値はレスポンスで確認するか、モデルで各モデルのページを参照してください。

CLI にはクレジット用のコマンドはありませんが、nodaro models list で各モデルのクレジットのティアを確認できます。

従量課金

API を使うのに、サブスクリプションは必要ありません。

• 購入すると有効になります。クレジットパックを購入するか、「請求」ページで 5〜1,000 ドルの範囲の任意の金額を 1 ドル単位でチャージすると、アカウントが従量課金に切り替わります。チャージ額が大きいほど、1 クレジットあたりの単価が安くなります。
• すべてが使えるようになります。effectiveTier が payg になり、すべてのモデルが使え、結果にウォーターマークが付かず、1 日の使用上限もなくなります。
• クレジットは購入から 12 か月間有効です。
• 開発者向けの経路で使えます。従量課金のクレジットは、API、SDK、CLI、MCP で使えます。Web エディターにはサブスクリプションが必要で、従量課金のアカウントがエディターからクレジットを使おうとすると、403 subscription_required が返されます。トークンを使った呼び出しで、このエラーが返されることはありません。
• 一定の量を継続して使う場合は、サブスクリプションのほうが 1 クレジットあたりの単価が安くなります。

注意点が 2 つあります。

• 結果はデフォルトで公開されます。非公開の結果は Standard プラン以上のサブスクリプションの機能なので、従量課金での結果は公開ギャラリーに表示されます。MCP で作成したジョブは、常に非公開です。
• メディアは、アカウントが有効な間は保持されます。購入もクレジットの使用もない状態が約 3 か月続くと、60 日より古いファイルが削除されることがあります。再びクレジットを使うと、削除は止まります。

購入そのものは、Web アプリで行います。決済、チャージ、自動チャージ、購入履歴、支払いポータルのための /v1/billing/* ルートは、API トークンと OAuth トークンを受け付けません。請求は app.nodaro.ai/billing で管理してください。

デプロイメントの使用量の計測方法を読み取る

次の 2 つのルートを使うと、クライアントは、デプロイメントの課金方法を前提にせずに、コストと使用量の表示を作れます。

GET /v1/billing/surface はトークンが不要で、誰にでも同じ内容を返します。

{
  "data": {
    "contract": 2,
    "providerId": "…",
    "displayUnit": "credits",
    "canReport": true,
    "canQuote": true,
    "canAccount": true,
    "mountCostTab": true,
    "deploymentPayer": false
  }
}

• displayUnit は、コストの表示でデフォルトで使う単位です。たとえば credits や usd です。
• クレジットのない Community エディションの環境では、providerId は none、mountCostTab は false になります。この場合、コストの表示は出さないでください。
• 1 つの請求アカウントがすべてのユーザーの分を支払う場合、deploymentPayer は true です。それがどのアカウントかは、表示されません。

GET /v1/billing/account は、アカウントの概要を { "data": … } として返します。請求サービスが応答できない場合、data は null です。その場合は「利用できない」と表示し、残高 0 として表示しないでください。概要には、常に次のフィールドがあります。

デプロイメントによっては、任意のフィールドが追加されます。クライアントは、受け取ったフィールドだけを表示します。任意のフィールドは、periodStart、generations、spent、payg、daily、reserveValue、byCategory です。金額は、{ amount, currency } のオブジェクトです。daily の limit が 0 の場合は、無制限ではなく、ブロックされていることを意味します。daily と dailyAllowance の両方がある場合は、daily が優先されます。null はすべて「利用できない」を意味し、0 ではありません。ダッシュを表示してください。

POST /v1/jobs/cost-summary は、複数のジョブのクレジットを合計します。最上位と内訳の各行にある total_credits は、数値か null です。レスポンスには、単位を示す unit と、料金を算出できなかったジョブの数を示す unavailable が含まれます。合計が null の場合は、バッチ内のどのジョブにも既知の請求額がなかったことを意味します。0 という意味ではありません。

ワークスペースと共有の請求

• ワークスペースの予算：組織のワークスペース内での作業は、あなたの残高ではなく、ワークスペースの予算から支払われます。その取引には payer: "workspace" が付きます。予算を超える実行では 402 budget_exceeded が、そのワークスペースでの自分の上限を超える実行では 402 member_cap_exceeded が返されます。ワークスペースと組織を参照してください。
• 1 つの請求アカウントで支払うデプロイメント：1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、GET /v1/user/credits に allowance: { granted, remaining, enforced } が追加されます。これは、クレジット単位での自分の利用枠です。enforced: false は、利用枠が表示されるだけで、実行は止められないことを意味します。請求アカウント自体の場合や、読み取れなかった場合、allowance は null になるので、null を 0 と解釈しないでください。デプロイメントが利用枠を適用している場合、自分の利用枠を超える実行では 402 user_allowance_exceeded が返されます。請求アカウントは、プールされた残高を、自分のブラウザーセッションからだけ管理します。トークンでその残高を読み取ろうとすると、403 payer_balance_jwt_only が返されます。独自のウォレットで支出を承認するデプロイメントについては、外部ウォレットを参照してください。