# クレジット

> API で Nodaro のクレジット残高と履歴を取得し、モデルや実行の料金を開始前に確認します。確保、返還、従量課金の仕組みも説明します。

Source: https://nodaro.ai/ja/docs/developers/api/credits

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

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

## エンドポイント
| メソッド | パス | 説明 |
| --- | --- | --- |
| `GET` | `/v1/credits/balance` | 残高です。合計、サブスクリプション、チャージの各クレジットと、ティアを返します。 |
| `GET` | `/v1/user/credits` | 1 日の使用量を含む、より詳しい残高のレコードです。 |
| `GET` | `/v1/credits/transactions` | クレジットの履歴を、ページ単位で返します。 |
| `POST` | `/v1/credits/model-costs` | 最大 50 個のモデル ID のクレジット料金です。 |
| `POST` | `/v1/credits/video-pro-estimate` | **動画生成 Pro**（Generate Video Pro）の実行料金です。[ジョブ](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run)を参照してください。 |
| `GET` | `/v1/billing/surface` | 公開。このデプロイメントが、使用量をどのように計測しているかを返します。 |
| `GET` | `/v1/billing/account` | デプロイメントの請求システムから取得した、アカウントの概要です。 |
| `POST` | `/v1/jobs/cost-summary` | 複数のジョブのクレジットを、まとめて返します。 |

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

## 残高を読み取る
**curl**

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

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

**TypeScript SDK**

```ts
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` は、さらに多くの情報を返します。

| フィールド | 説明 |
| --- | --- |
| `total`, `subscription`, `topup` | 上記と同じく、あなたのクレジットです。 |
| `dailySpent` | 今日使ったクレジットです。 |
| `dailyLimit` | 1 日の使用上限です。上限がない場合は `null` です。 |
| `monthlyAllocation` | プランで、請求サイクルごとに付与されるクレジットです。 |
| `tier`, `effectiveTier` | 保存されているティアと、適用されているティアです。 |
| `features` | ティアで使える機能です。 |
| `periodEnd` | 請求期間が終わる日時です。 |
| `appCreditsAllowance` | アプリの利用で得たクレジットです。無料ティアの場合のみです。 |

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

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

ジョブの `credit_status` と取引の `status` は、同じ段階をたどります。まず `reserved`、次に `committed` か `refunded` です。そのため、クレジットが返還されたかどうかは、ジョブ自体から判断できます。[ジョブのクレジット](https://nodaro.ai/docs/developers/api/jobs#credits-of-a-job)を参照してください。

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

| クエリ | 説明 |
| --- | --- |
| `limit` | 1〜50 です。デフォルトは 20 です。 |
| `cursor` | 前のページの `nextCursor` です。値は、最後の行の `created_at` の日時です。 |

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

```json
{
"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"
}
```

| フィールド | 説明 |
| --- | --- |
| `credits_used` | このエントリーのクレジットです。 |
| `action`, `provider` | 何が、どのモデルで実行されたかです。 |
| `status` | `reserved`、`committed`、`refunded` のいずれかです。 |
| `payer` | 自分の残高から支払った場合は `user`、クラスやチームの予算から支払った場合は `workspace` です。 |
| `workspaceId` | 支払ったワークスペース、または `null` です。 |
| `metadata` | 実行がどのように課金されたかです。常にオブジェクトで、該当するものがない場合は `{}` です。 |

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

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

## 実行前に料金を確認する
| ルート | 料金を確認できるもの |
| --- | --- |
| `POST /v1/credits/model-costs` | 最大 50 個のモデル ID の料金を、まとめて返します。 |
| `GET /v1/models` | すべてのモデルの料金です。バリエーションごとに `pricing` のエントリーがあります。[モデルを探す](https://nodaro.ai/docs/developers/api/nodes#discover-models)を参照してください。 |
| `GET /v1/nodes/:type` | ノードの `creditCost` です。単一の料金か、料金の範囲です。 |
| `GET /v1/api/schema` | ワークフロー全体の料金を、`estimatedCredits` として返します。[ワークフロー](https://nodaro.ai/docs/developers/api/workflows#run-a-workflow-with-new-input-values)を参照してください。 |
| `POST /v1/credits/video-pro-estimate` | 動画生成 Pro の実行料金を、何も確保せずに返します。[ジョブ](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run)を参照してください。 |
| `POST /v1/recast/estimate` | Recast の実行料金です。[Recast](https://nodaro.ai/docs/developers/api/recast) を参照してください。 |
| `POST /v1/pro-3d-render/quote` | **3D レンダリング Pro**（3D Render Pro）の実行料金です。[3D シーン](https://nodaro.ai/docs/developers/api/3d-scenes)を参照してください。 |

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

**curl**

```bash
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"]}'
```

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

**TypeScript SDK**

```ts
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 ではなくダッシュを表示してください。上の料金は例です。実際の値はレスポンスで確認するか、[モデル](https://nodaro.ai/docs/models)で各モデルのページを参照してください。

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](https://app.nodaro.ai/billing) で管理してください。

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

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

```json
{
"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 として表示しないでください。概要には、常に次のフィールドがあります。

| フィールド | 説明 |
| --- | --- |
| `plan` | プランを表す文字列です。`unknown` も、有効な値です。 |
| `balance` | 残高、または `null` です。 |
| `dailyAllowance` | 1 日の利用枠、または `null` です。 |
| `unit` | これらの数値の単位です。 |

デプロイメントによっては、任意のフィールドが追加されます。クライアントは、受け取ったフィールドだけを表示します。任意のフィールドは、`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` が返されます。[ワークスペースと組織](https://nodaro.ai/docs/developers/api/workspaces#budgets-and-usage)を参照してください。
- **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` が返されます。独自のウォレットで支出を承認するデプロイメントについては、[外部ウォレット](https://nodaro.ai/docs/developers/external-wallet)を参照してください。

## Frequently asked questions

### API でクレジット残高を確認するにはどうすればよいですか？

GET /v1/credits/balance を送信します。合計（total）、サブスクリプション（subscription）、チャージ（topup）の各クレジットと、tier と effectiveTier が返されます。SDK の client.credits.balance() は、1 日の使用量も含む、より詳しいレコードを返します。

### API での生成では、クレジットはいつ請求されますか？

クレジットは、ジョブの開始時に確保され、結果を返したときに請求されます。ジョブがセーフティフィルターやポリシーでブロックされた場合や、実行前にキャンセルされた場合は、確保されたクレジットが返還されます。どちらになったかは、ジョブの credit_status でわかります。

### サブスクリプションなしで Nodaro API を使えますか？

はい。クレジットパックをどれか購入すると従量課金が有効になり、すべてのモデルが使えるようになります。ウォーターマークも 1 日の上限もありません。従量課金のクレジットは、API、SDK、CLI、MCP で使え、12 か月間有効です。

### 実行の料金を、開始する前に知るにはどうすればよいですか？

POST /v1/credits/model-costs は最大 50 個のモデル ID のクレジット料金を返し、GET /v1/models はすべてのモデルの料金ティアを一覧表示します。GET /v1/api/schema は、ワークフロー全体の料金を見積もります。動画生成 Pro（Generate Video Pro）には、専用の見積もりルートがあります。

### セルフホスティング環境で、クレジットのエンドポイントは使えますか？

いいえ。Community エディションと Business エディションにはクレジットの仕組みがないため、クレジットのルートは 404 を返し、ノードとモデルの記述子にもクレジット料金は含まれません。モデルのプロバイダーに直接支払います。