NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
TypeScript SDK

モデルとクレジット

Nodaro インスタンスが提供する AI モデルを一覧表示し、クレジット残高を確認して、実行前にモデルの料金を調べ、プランとサブスクリプションを読み取ります。

client.models は、Nodaro インスタンスが提供する AI モデルのカタログを返し、client.credits はクレジット残高と、任意のモデルの料金を返します。client.billing は、販売中のプランとサブスクリプションを返します。これらを組み合わせて使うと、ユーザーが選べるモデルと各実行の料金をあわせて表示できます。これらのメソッドは、クレジット REST API と同じエンドポイントを呼び出します。料金と残高があるのは Nodaro Cloud だけで、セルフホスティングの Community エディションと Business エディションにはクレジットの仕組みがありません。クレジットを参照してください。

メソッド

メソッド内容
models.list(opts?)モデルを、種類と開発元ごとにグループ化して一覧表示します
credits.balance()クレジット残高とティアを読み取ります
credits.modelCosts(ids)最大 50 件のモデルまたはバリアントのクレジット料金を調べます
credits.transactions(options?)クレジットのトランザクションを、1 ページずつ読み取ります
credits.usageSummary(options?)期間内のクレジットの使用状況を、請求画面向けに集計します
credits.history(options?)残高のすべての動きを、1 ページずつ読み取ります
credits.exportHistory(filters?)絞り込んだ履歴全体を CSV で書き出します
credits.claimWelcomeOffer(input?)ファーストパーティの Web アプリで、ウェルカムオファーを受け入れます
credits.markWelcomeOfferSeen()ウェルカムのポップアップが自動で開いたこと、またはユーザーが後でと回答したことを報告します
billing.plans() ほか販売中のプランとクレジットパック、サブスクリプション、デプロイメントの課金方法を読み取ります。ファーストパーティのアプリでは、購入、請求書、カード、自動チャージ、決済も扱います

client.models

models.list(opts?)

モデルのカタログを返します(GET /v1/models)。種類(画像、動画、オーディオ)と開発元ごとにグループ化されています。各モデルには、その機能、Nodaro Cloud でのクレジット料金、短いプロンプトのコツが含まれます。このエンドポイントは公開されており、サーバーはレスポンスを 5 分間キャッシュします。MCP の list_models ツールも、同じデータを返します。

list(opts?: {
  kind?: "image" | "video" | "audio"
  mode?: string
  family?: string
  featuredOnly?: boolean
}): Promise<ModelsListResult>

プロパティ

型

const catalog = await client.models.list({ kind: "video", mode: "i2v" })

for (const section of catalog.sections) {
  for (const family of section.families) {
    for (const model of family.models) {
      console.log(family.family, model.id, model.durations, model.pricing?.[0]?.credits)
    }
  }
}

結果には、種類ごとの sections(それぞれにモデルの families を持ちます)、よくある用途向けのモデル ID のリストである recommendations、totalModels が含まれます。各モデルには、次のフィールドがあります。

フィールド型説明
idstringモデル ID です。ノード実行の provider パラメーターに使います。
label、descriptionstring表示名と短い説明です。
modesstring[]モデルが何をするかを示します。t2i、i2i、t2v、i2v などです。
useCasesstring[]そのモデルに向いている用途です。
aspectRatios、resolutions、qualities、durations配列モデルが受け付ける値です。該当する場合のみ。
featuresstring[]追加の機能です。
pricing{ identifier, credits, note? }[]各バリアントのクレジット料金です。実行に請求される料金で、実行ボタンと同じ数値です。Nodaro Cloud のみ。
featuredbooleanおすすめのモデルかどうかです。
promptTipsstring[]そのモデル向けの短いプロンプトのコツです。
doctrineCoveredbooleanNodaro が、そのモデルのファミリーについて出典のあるプロンプトのガイダンスを用意している場合にのみ true です。「開発元のガイダンス」バッジは、これが true の場合にのみ表示してください。
maker{ id, name }モデルを作った企業です。id は企業ごとに 1 つの安定した値で、"google" や "black-forest-labs" などです。そのため、自分のアセットのキーとして使えます。新しいサーバーでは開発元が追加されることがあるので、知らない ID にも対応してください。開発元は、モデルがグループ化されている family と同じとは限りません。インスタンスが独自のラベルで提供するモデルには、maker がありません。
logoUrlstring | null開発元の公式ロゴで、インスタンス自身のメディア CDN 上の SVG です。インスタンスがその開発元のロゴを公開していない場合は null です。その場合は、開発元の名前か頭文字を代わりに表示してください。インスタンスが独自のラベルで提供するモデルでも null です。ロゴが差し替えられると新しいアドレスで届くので、アドレスは与えられたとおりに使ってください。MCP ツールには含まれません。

古いサーバーでは、maker と logoUrl は含まれません。

defaultDuration は、duration を指定しない場合にレンダリングされ、課金される長さです。autoDuration は、duration: -1 でモデルに長さを選ばせられることを意味します。referenceTaskTypes は、そのモデルで referenceTaskType が受け付ける値です。seedance-2-5 では ["reference", "edit", "extend"] で、ほかのモデルにはありません。

サイズのルールとファイル形式

アスペクト比や背景によってサイズが変わるモデル、またはデフォルトのサイズを宣言しているモデルは、次のフィールドを持ちます。ほかのモデルと古いサーバーでは、これらのフィールドは含まれません。

フィールド型説明
defaultResolutionstringresolution を指定しないリクエストがなるサイズで、モデルが宣言している場合に resolutions と同じ表記で示されます。FLUX 3 Klein では 1K、Seedream 5.5 と MiniMax H3 Image では 2K、PixVerse V6 Max では 720p です。resolutions の最初の項目がデフォルトだと決めつけず、このフィールドを読んでください。
resolutionsByAspectRatioRecord<string, string[]>resolutions より少ないサイズしかレンダリングしないアスペクト比と、その比でレンダリングするサイズです。一覧にない比では、resolutions のすべてのサイズをレンダリングします。比がレンダリングしないサイズを指定したリクエストは、その比がレンダリングする、指定以下で最大のサイズで実行され、そのサイズで課金されます。変更は adjustments で報告されます。
transparentResolutionstring透明な背景をレンダリングできる唯一のサイズです。ほかのサイズで透明を指定したリクエストは、このサイズで実行され、このサイズで課金されます。
backgroundOnlyAtTransparentResolutiontrueモデルが背景の設定を受け付けるのは transparentResolution のときだけです。ほかのサイズでは背景の設定は送られないため、opaque は auto としてレンダリングされます。

GPT Image 2.5(gpt-image-2-5-flare、gpt-image-2-5-sunburst、およびそれらの -i2i 編集モデル)は、27:16、16:27、9:8、8:9 では 1K だけをレンダリングします。透明な背景は 1K でだけレンダリングし、背景の設定も 1K でだけ受け付けます。GPT Image 2.6 Flare と Sunburst も、透明な背景は 1K でだけレンダリングします。

複数の種類のファイルを書き出すモデルは、既定の形式を先頭にした outputFormats を持ちます。GIF や SVG を書き出す場合は、gifFrameSize(512)、gifFrames({ min, max, default, values? })、gifFrameDurationMs({ min, max, step, default })、svgLevels も持ちます。画像のファイル形式を参照してください。

const { sections } = await client.models.list({ kind: "image" })
const m = sections.flatMap((s) => s.families.flatMap((f) => f.models)).find((x) => x.id === "gpt-image-2-5-flare")!
// The sizes to offer at the chosen ratio:
const sizesAt = (ratio: string) => m.resolutionsByAspectRatio?.[ratio] ?? m.resolutions ?? []
sizesAt("27:16") // ["1K"]
sizesAt("16:9")  // ["1K", "2K", "4K"]

カタログなしでメーカーのマークを描画するには、GET /v1/model-makers を呼び出します。応答は { makers: [{ id, name, logoUrl }] } で、プラットフォームが知っているすべてのメーカーを、カタログと同じフィールドで含みます。このルートは公開されており、5 分間キャッシュされます。モデルを調べるを参照してください。

for (const section of catalog.sections)
  for (const family of section.families)
    for (const m of family.models)
      console.log(m.id, m.maker?.name ?? family.family, m.logoUrl ?? "(no mark)")

同じカタログは、モデルのページにもあります。どのモデルを使うかについては、モデルの選び方を参照してください。

client.credits

credits.balance()

クレジット残高とティアを返します(GET /v1/user/credits)。ログインしているユーザーがいない場合は、UnauthorizedError をスローします。

balance(): Promise<UserBalance>
const balance = await client.credits.balance()
console.log(`${balance.total} credits (${balance.effectiveTier})`)
フィールド型説明
totalnumber今すぐ使えるクレジットです。
subscriptionnumber今月残っているサブスクリプションのクレジットです。年額プランでも毎月 monthlyAllocation にリセットされ、使わなかった分は繰り越されません。
topupnumber個別に購入してチャージしたクレジットです。
dailySpentnumber本日使用したクレジットです。
dailyLimitnumber | null1 日の利用上限です。上限がない場合は null です。
monthlyAllocationnumberプランが毎月付与するクレジットです。月額請求でも年額請求でも同じです。
tierstring保存されているサブスクリプションのティアです。"free" や "pro" などです。
effectiveTierstring実際に適用されているティアです。"payg" は従量課金を意味し、サブスクリプションはなくても購入したクレジットがあり、すべてのモデルを使え、透かしも 1 日の上限もありません。
featuresRecord<string, unknown>そのティアの機能です。
periodEndstring | null現在の請求期間の終了日で、ISO 8601 形式の日付です。年額プランでは 1 年先になりますが、サブスクリプションのクレジットは毎月リセットされます。
appCreditsAllowancenumber無料ティアで、アプリの実行によって得られるクレジットです。
freeGrantStateFreeGrantState無料の登録特典の状況です。"unclaimed"、"granted"、"withheld"、"revoked" のいずれかです。"withheld" は、アカウントは使えるものの特典が付与されなかったことを意味するので、有効化の手順を表示してください。デプロイメントに登録特典がない場合は含まれません。
freeGrantNotice"browser_unmeasured""withheld" のときに、申請でブラウザーのシグナルがまったく得られなかった場合にだけ含まれます。アプリでは、無料クレジットには通常のブラウザーと再読み込みが必要だと伝えてかまいません。
welcomeOfferWelcomeOfferStateデプロイメントでウェルカムオファーが有効な間だけ含まれます。含まれない場合は、ポップアップ、バナー、ブロックのいずれもありません。claimWelcomeOffer() を参照してください。
externalWallet{ available: number | null }デプロイ環境が共有の外部ウォレットを使っている場合にのみ含まれます。null は金額が取得できないことを意味します。この場合、代わりに total を表示しないでください。外部ウォレットを参照してください。
allowanceBalanceAllowance | null1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでのみ含まれます:{ granted, remaining, enforced }、クレジット単位の自分の割り当てです。そのようなデプロイメントでは total は個人の残高で、実行の支払いには使われないため、こちらを表示してください。enforced: false は、表示されるだけで強制されないことを表します。請求アカウント自身の場合と、読み取れなかった場合は null で、0 ではありません。
displayBalanceDisplayクレジットの代わりに独自の単位を表示するデプロイメントで、サーバーが換算した同じ数値です。単位が設定されていなければ含まれません。

何を表示するか決める際は、tier より effectiveTier を優先してください。1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、tier と effectiveTier はデプロイメントのプラン、つまり請求アカウントのティアです。

BalanceDisplay には、unit(単位のラベル)、decimals(数値の小数点以下の桁数、0〜4)と、その単位での total、subscription、topup、dailySpent、dailyLimit、monthlyAllocation、appCreditsAllowance が含まれます。それぞれ number | null で、null は取得できないことを表します。0 ではなく、全角ダッシュを表示してください。元のキーがあるときに限り、allowance: { granted, remaining } | null、externalWallet: { available }、welcomeOffer: { credits } も加わります。デプロイメントがインターフェースの言語ごとに単位の名前を決めている場合は unitLabels(ロケール ID から名前への対応)も含まれるので、unitLabels[locale] ?? unit を表示してください。これらの数値はそのまま表示し、クレジットを自分で換算しないでください。請求アカウントが 1 つのデプロイメントで請求アカウント自身が読み取る場合、その残高はクレジットのまま管理されるデプロイメントのプールなので、display は含まれません。

credits.modelCosts(ids)

モデルとそのバリアントのクレジット料金を、1 回の呼び出しでまとめて調べます(POST /v1/credits/model-costs)。確認されるのは、最初の 50 件までの識別子です。

modelCosts(ids: string[]): Promise<{
  data: Record<string, number>
  missing: string[]
  errors: string[]
  estimates?: string[]
  errorCodes?: Record<string, { code: string; message: string }>
  display?: ModelCostsDisplay
}>

プロパティ

型

const { data, missing } = await client.credits.modelCosts([
  "nano-banana-pro",
  "nano-banana-pro:4K",
  "seedance-2-fast:8s:720p",
])
console.log(data["nano-banana-pro:4K"])
if (missing.length) console.warn("No price for:", missing)
  • data には、料金が付いている各識別子と、そのクレジット料金の対応が入ります。
  • missing には、料金がない識別子が列挙されます。これらにはダッシュを表示してください。
  • errors には、調べるのに失敗した識別子が列挙されます。それ以外の料金は、そのまま返されます。
  • estimates には、data の識別子のうち、数値が固定の料金ではなく見積もりであるものが列挙されます。これらは従量課金の LLM の料金キーです。≈N と表示してください。該当するものがない場合、このフィールドは含まれません。
  • errorCodes は、errors の各識別子に料金がない理由を示します。現在のコードは llm_model_unpriced で、処理される経路に単価がなく、実行できないモデルです。errors が空の場合、このフィールドは含まれません。
  • display は、クレジットの代わりに独自の単位を表示するデプロイメントで含まれます:{ unit, decimals, data }。data は、同じ識別子を、サーバーが換算したその単位での価格に対応付けます(null は取得できないことを表します)。estimates にある識別子は、ここでも見積もりです。unitLabels がある場合は、単位の名前として unitLabels[locale] ?? unit を表示してください。GET /v1/credits/model-cost は、そこに display: { unit, decimals, creditCost } を加えます。デプロイメント独自の単位での価格を参照してください。

各モデルの識別子は、models.list() の pricing フィールドと、各モデルのページにあります。品質、解像度、長さなどの設定によって料金が変わるため、実行で使うバリアントを指定してください。実行時の料金は、実行が始まるときにもう一度確認されるため、この呼び出しはあくまで見積もりです。

音声モデルは、テキストの長さで料金が決まります。開始した 100 文字ごとの識別子は <model>:per-100-chars で、たとえば elevenlabs-v4:per-100-chars です。音声を長さで課金しないインストールでは、この識別子は missing に入ります。そのため、サーバーがどのルールで課金しているかも、この応答でわかります。

リクエストは全体として料金が計算され、1 回だけ丸められます。そのため、開始したブロックが N 個のリクエストの正確な料金は、ID <model>:per-100-chars:<N>u です。N は 8 から、モデルの 1 リクエストあたりの上限までです。N にブロックの料金を掛けた額は、これより高くなることがあります。同じ形の ID で、単位あたりで課金されるすべての実行の料金を確認できます。<row>:<N>u は、その行の N 単位分の正確な料金です。たとえば apply-edl:4u、trim-video:5u、ltx-2.3-pro-retake:per-second:2.5u、elevenlabs-dubbing:3u です。ボイスチェンジャー Pro の変換全体は voice-changer-pro:<slot>,<slot>,… で、@nodaro/shared の voiceChangerProQuoteCreditId(slots) で作れます。単位あたりで料金が決まる実行の正確な料金を参照してください。

LLM の呼び出しには、固定の料金がありません。実際に使ったトークンに応じて、呼び出しを処理したレーンでのモデルの単価で課金されます。その料金キーは <feature>:<model> で、プロバイダー自身の API では :direct が、料金が推論の強度で変わるモデルでは :effort-<level> が付きます。キーは、@nodaro/shared/llm-models の llmPriceKey で作れます。答えは、一般的な呼び出しの見積もりです。

import { llmPriceKey } from "@nodaro/shared/llm-models"

const key = llmPriceKey("llm-chat", "claude-fable-5") // "llm-chat:claude-fable-5"
const { data, estimates } = await client.credits.modelCosts([key])
const shown = estimates?.includes(key) ? `~${data[key]}` : String(data[key])

missing にある従量課金のキーは、サーバーが LLM の呼び出しをモデルごとに料金設定していないことを意味するので、料金は表示しないでください。GET /v1/credits/model-cost?model=<id> は、1 つの識別子に { model, creditCost, estimate?: true, display? } で答えます。LLM の呼び出しとLLM 呼び出しの課金のしくみを参照してください。

credits.transactions(options?)

クレジットのトランザクションを、新しい順に 1 ページ分返します(GET /v1/credits/transactions)。Cloud エディションのみです。セルフホスティング環境は 404 で答えます。

transactions(options?: { limit?: number; cursor?: string }): Promise<CreditTransactionsPage>

プロパティ

型

ページは { data: CreditTransaction[], nextCursor } です。行がもうない場合、nextCursor は null です。

フィールド型説明
idstringトランザクションの ID です。
created_atstringISO 8601 形式の日付です。
credits_chargednumber | null精算後に、その実行にかかった料金です。確保した額より少ないことがあり、確保が返還された場合は 0、確保がまだ未精算のあいだは null です。
credits_reservednumber | null実行が受け付けられたときに確保した額です。この値は変わりません。
credits_usednumber | null同じ確保額を元の名前で返すもので、既存の連携のために残されています。credits_charged を使ってください。
actionstring | nullクレジットを使ったモデルまたは操作です。
statusstring | null"reserved"、"committed"、"refunded" のいずれかです。
metadataRecord<string, unknown>その実行自体の課金の詳細です。
payer"user" | "workspace""workspace" は、自分の残高ではなく、クラスやチームの予算から支払われたことを示します。
workspaceIdstring | nullpayer が "workspace" の場合の、支払ったワークスペースです。

どの額を読むか。 実行は、まずクレジットを確保し、その後に精算されます。確保した額の全部または一部が請求され、残りは残高に戻ります。利用額を知るには、credits_charged を足し合わせてください。クレジットを参照してください。

let cursor: string | undefined
let spent = 0
do {
  const page = await client.credits.transactions({ limit: 50, cursor })
  for (const t of page.data) spent += t.credits_charged ?? 0
  cursor = page.nextCursor ?? undefined
} while (cursor)
console.log(`${spent} credits charged`)

credits.usageSummary(options?)

期間内のクレジットの使用状況を、請求画面の表示のように集計して返します(GET /v1/credits/usage-summary)。対象は個人のお金だけで、ワークスペースが支払った実行は含まれません。Nodaro Cloud のみです。

usageSummary(options?: { from?: string; to?: string; bucket?: "day" | "week" | "month" }): Promise<UsageSummary>

プロパティ

型

1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、請求アカウント自身のセッションだけが呼び出せます。そのトークンには、コード payer_balance_jwt_only の ForbiddenError が返されます。

フィールド型説明
period{ from, to, bucket }サーバーが受け取った期間です。
totalsUsageSummaryTotals{ used, purchased, granted, refunded, runs, avgPerRun } です。下記を参照してください。
mostUsedUsageByModel | null使用額が最も多いモデルです。実行がない場合は null です。
byModelUsageByModel[]{ model, provider, credits, runs, share } で、使用額の多い順です。share は used に占める割合で、0〜1 です。
byCategoryUsageByCategory[]{ category, credits, runs } で、category は "image"、"video"、"audio"、"other" のいずれかです。
overTimeUsageOverTime[]単位ごとに 1 行で、空の単位も含めて古い順です:{ bucket, used, purchased, runs }。bucket は UTC の日("2026-10-26")、週の月曜日、または月("2026-10")です。最初の単位は、週や月の途中からのことがあります。
bySession、byWorkflowUsageByGroup[]各セッションや各ワークフローにかかった額で、使用額の多い順です:{ id, name, tool, credits, runs, models, lastAt }。名前がない場合や削除された場合、name は null です。tool はセッションにだけあります。
truncatedboolean読み取りがサーバーの上限である 5,000 行に達し、数値が実際より少ない場合に true です。期間を短くしてください。
partialboolean補助的な読み取りが失敗し、グループの一部が欠けているか名前がない場合に true です。合計は正しいままです。

totals の内容:

  • used は、各実行の課金額の合計です。実行中の実行は確保額で数え、返還された実行は数えません。
  • purchased は、パック、チャージ、サブスクリプションの付与です。
  • granted は無料のクレジットで、取り消された付与を差し引きます。
  • refunded は、返還された実行や Stripe から戻った額です。実行が確保額より少なく精算されて戻った分は、返還ではありません。
  • runs は、課金された実行と実行中の実行の数です。avgPerRun は used を runs で割った値で、小数第 1 位までです。
const s = await client.credits.usageSummary({ bucket: "week" })
console.log(s.totals.used, "credits used;", s.mostUsed?.model, "most used")
for (const w of s.overTime) console.log(w.bucket, w.used)

credits.history(options?)

残高のすべての動きを、新しい順に 1 ページ分返します(GET /v1/credits/history)。実行、購入、付与、返還、調整、失効で、それぞれの後の残高も付きます。transactions() が実行だけを一覧にするのに対し、history() は請求画面が表示する明細全体です。Nodaro Cloud のみで、1 つの請求アカウントを持つデプロイメントでは usageSummary() と同じ規則が適用されます。

history(options?: CreditHistoryOptions): Promise<CreditHistoryPage>

プロパティ

型

ページは { data: CreditHistoryEntry[], nextCursor } です。最後のページでは、nextCursor は null です。

フィールド型説明
idstring行の ID です。
atstring起きた日時で、ISO 8601 形式です。
kindCreditHistoryKind何の動きかです。"app" は、公開したアプリで得た、またはアプリに支払ったクレジットです。"adjustment" は管理者による修正とその他すべてです。
sourcestring記録自身の語で、usage、one_time_purchase、subscription_renewal、signup_grant、refund、app_earnings、expiry などです。
amountnumber符号付きの動きです。実行の確保はマイナス、購入はプラスです。
balanceAfternumberその直後の残高です。
pool"subscription" | "topup" | "mixed"残高のどの部分が動いたかです。
descriptionstring | null記録のメモです。
model、providerstring | nullジョブのある行で、実行されたモデルとそのプロバイダーです。
chargenumber | nullジョブの課金額で、ジョブの確保の行、つまり実行が受け付けられたときの確保にだけあります。精算された課金額、実行中は確保額、返還後は 0 です。ほかの行はすべて null なので、charge を合計すると各ジョブを 1 回だけ数えます。使用額には amount ではなく、このフィールドを読んでください。
statusstring | nullcharge と並ぶ値で、"reserved"、"committed"、"refunded" のいずれかです。
jobCreditHistoryJob | nullジョブのある行で、{ id, type, status, startedAt, completedAt, durationMs, workflowId, sessionId } です。ジョブが削除された場合、type などは null です。
receiptUrlstring | null領収書がある購入での、Stripe の領収書です。
const page = await client.credits.history({ kind: "usage", limit: 50 })
for (const e of page.data) console.log(e.at, e.model, e.charge ?? e.amount, "→", e.balanceAfter)

credits.exportHistory(filters?)

絞り込んだ履歴全体を、CSV のテキストとして返します(GET /v1/credits/history?format=csv)。フィールドと絞り込みは history() と同じで、動きごとに 1 行、新しい順で、ページ分けはありません。最大 5,000 行で、最後の行は一覧が切られたかどうかを示します。残りは from と to を狭めて取得してください。

exportHistory(filters?: CreditHistoryFilters): Promise<string>
const csv = await client.credits.exportHistory({ from: "2026-10-01T00:00:00Z" })
const href = URL.createObjectURL(new Blob([csv], { type: "text/csv" }))

credits.claimWelcomeOffer(input?)

ウェルカムオファーへのユーザーの「はい」を、1 つの操作で記録します(POST /v1/credits/welcome-offer/claim)。マーケティングメールへの同意を記録し、その同意とともに無料の登録特典を申請します。不正利用のチェックは引き続き行われるので、grant を読み取ってください。特典がすでに決定しているアカウントでは、同意だけが記録されます。Nodaro Cloud 限定です。セルフホスティングのインスタンスは 404 を返します。

claimWelcomeOffer(input?: WelcomeOfferClaimInput): Promise<WelcomeOfferClaimResult>

同意は本人の選択なので、このメソッドには、supabaseAuth() によるサインイン済みのブラウザーセッションが必要です。 API トークンや OAuth アプリのトークンでは 403 になります。デプロイメントでオファーが無効になっている間は、呼び出しは 409 welcome_offer_disabled を返すので、balance().welcomeOffer がある場合にだけオファーを表示してください。1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、無料の登録クレジットは適用されません。呼び出しは 409 not_applicable を返し、同意も含めて何も記録せず、balance() には welcomeOffer が含まれません。

WelcomeOfferClaimInput は、collectSignupKeys() の SignupKeys に sourceApp を加えたものです。sourceApp は、小文字の英字、数字、ダッシュで最大 40 文字の、自分のアプリのスラッグです。形式が正しくないスラッグは、拒否されずに、ないものとして保存されます。locale も受け付けます。これは、ユーザーが回答したときのインターフェースの言語で、"en"、"ja"、"pt-BR" など、Nodaro が提供する言語の ID です。大文字と小文字を区別して完全一致で照合されるため、"en-US" や "pt-br" は、ないものとして保存されます。同意とともに、最新の同意の言語として記録されます。

フィールド型説明
consent"granted"メールの同意が記録されました。
grantFreeGrantState"granted":特典が今回または以前に付与されました。"withheld":不正利用のチェックで拒否されました。"revoked":特典は以前に取り消されました。"unclaimed":何も変わっていないので、失敗として扱い、ユーザーに再試行させてください。
creditsnumber特典の額で、balance().welcomeOffer.credits と同じです。特典は、サブスクリプションのクレジットをこの額まで補充するもので、上乗せされるわけではありません。

WelcomeOfferState には 4 つのフィールドがあります。

フィールド型意味
popupDueboolean(任意)今ウェルカムのポップアップを自動で開きます。サーバーが判断します。条件は、付与が未申請で、後でが一度も選ばれておらず、ポップアップが自動で開いた回数が 3 回未満で、そのどれも直近 24 時間以内ではないことです。このフィールドより前にリリースされたサーバーは、このフィールドを省きます。その場合は、popupSeen が false の間ポップアップを開いてください。
popupSeenboolean!popupDue です。popupDue より前に作られたアプリのために残されています。代わりに popupDue を読んでください。
consentPendingbooleanアカウントにクレジットはあるが、メールの同意がまだです。
creditsnumber申請で付与される額です。consentPending の場合は、アカウントに付与された額で、現在の申請で付与される額より多いことがあります。

額はサーバーに従うので、オファーには固定の数値ではなく credits の値を表示してください。

credits.markWelcomeOfferSeen()

ウェルカムのポップアップに何が起きたかをサーバーに伝えます(POST /v1/credits/welcome-offer/seen)。サーバーはそれをもとに、すべてのアプリで welcomeOffer.popupDue を決めます。

eventタイミング効果
"shown"popupDue が true だったため、ポップアップが自動で開いたとき。アカウントの 3 回の表示のうち 1 回と数えます。ポップアップが対象でなかったときは何も数えないので、繰り返し呼び出しても問題ありません。
"later"ユーザーが後でと回答したとき。ポップアップはそれ以降自動では開きません。

回答せずに閉じた場合(×、Escape、外側のクリック)は、メソッドをまったく呼ばないことで報告します。その場合、ポップアップは後日の訪問でまた自動で開くことがあります。開くのは 1 日に最大 1 回、全部で 3 回までです。独自のボタンからポップアップを開くことも、表示には数えられません。イベントなしで呼び出すと、メソッドはボディを送らず、サーバーはそれを "later" として扱います。呼び出しが失敗しても、ポップアップがもう一度表示されるかもしれないというだけなので、エラーは無視してかまいません。ルールは claimWelcomeOffer() と同じです。1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、409 not_applicable も返します。

markWelcomeOfferSeen(event?: "shown" | "later"): Promise<{ ok: true }>
import { collectSignupKeys } from "@nodaro/sdk/signup-signals"

const { welcomeOffer } = await client.credits.balance()
// An older server sends popupSeen alone: the popup is due while it is false.
const due = welcomeOffer ? (welcomeOffer.popupDue ?? welcomeOffer.popupSeen === false) : false
if (due && !openedByItselfThisVisit()) {
  showPopup({ credits: welcomeOffer.credits }) // the server's figure, never a constant
  rememberOpenedByItselfThisVisit()            // for example, a sessionStorage mark
  void client.credits.markWelcomeOfferSeen("shown").catch(() => {})
}

// On "Maybe later":
void client.credits.markWelcomeOfferSeen("later").catch(() => {})
// On the ×, Escape or a click outside: close the popup and call nothing.

// On "Yes":
const keys = await collectSignupKeys()
const { grant, credits } = await client.credits.claimWelcomeOffer({ ...keys, sourceApp: "my-app", locale: "en" })
if (grant === "granted") showToast(`Your ${credits} free credits are ready`)

client.billing

client.billing は、販売中のプランと価格、呼び出し元のサブスクリプション、デプロイメントの課金方法を読み取ります。その人自身のセッション(supabaseAuth)でログインしたファーストパーティのアプリでは、請求画面全体も扱えます。購入、請求書、登録済みのカード、自動チャージ、Stripe Checkout とカスタマーポータルへの受け渡しです。セッション専用と記したメソッドは、ログイン済みのセッションにだけ応答します。API キーやアプリの OAuth トークンには ForbiddenError が返されるので、そうしたクライアントはアプリの請求ページに案内してください。

// A pricing screen: works signed out.
const { data: plans, topUps } = await client.billing.plans()

// Mark the plan the signed-in account is on.
const { effectiveTier } = await client.billing.subscription()
const current = plans.find((p) => p.id === effectiveTier) // undefined: pay-as-you-go, or a tier not on sale
メソッド戻り値補足
plans()Promise<BillingPlansResult>GET /v1/billing/plans。公開(デプロイメントがユーザーに販売している場合):認証情報は不要で、どの呼び出し元にも同じ応答を返します。1 つの請求アカウントが全ユーザーの料金を支払う場合は、サインインしたその請求アカウントだけが一覧を受け取ります。{ data: BillingPlan[], topUps, topUpRange, stripePublishableKey } を返します。stripePublishableKey(string | null)は、埋め込み Checkout のフォームを表示するための Stripe の公開可能キーです。デプロイメントにキーがない場合は null で、そのときは Checkout のページを使います。Nodaro Cloud 限定で、セルフホスティングのインスタンスでは NotFoundError をスローします。ユーザーに販売しないデプロイメントでは ForbiddenError をスローします。価格を一時的に読み取れない場合は、ステータス 503 の NodaroError をスローします。
subscription()Promise<BillingSubscriptionResult>GET /v1/billing/subscription。{ data: BillingSubscription | null, effectiveTier } を返します。アカウントが一度もサブスクリプションに登録していない場合、data は null です。effectiveTier は、アカウントの利用権限が従うティアです。通常はプランの id で、サブスクリプションなしでクレジットを購入した場合は "payg"、または "enterprise" のような販売されていないティアです。ブラウザーセッション、ワークフローの制限のない個人の API トークン、または OAuth アプリのトークンが必要です。Nodaro Cloud 限定です。1 つの請求アカウントがすべてのユーザーの分を支払うデプロイメントでは、effectiveTier はデプロイメントのプランで、data は自分のサブスクリプションです。通常は null です。
surface()Promise<BillingSurface>GET /v1/billing/surface。公開で、すべてのエディションで使えます。デプロイメントが使用量を計測するかどうか(計測しない場合、providerId は "none")と、料金を表示する単位(displayUnit)です。
account()Promise<BillingAccountSummary | null>GET /v1/billing/account。デプロイメントの課金プロバイダーが報告する、呼び出し元の plan、balance、dailyAllowance で、単位はその unit です。プロバイダーが応答できなかった場合は null で、残高 0 という意味ではありません。すべてのエディションで使えます。
purchases()Promise<BillingPurchase[]>GET /v1/billing/transactions。セッション専用。アカウントのクレジットの購入で、新しい順に最新の 50 件です:{ id, stripe_transaction_id, type, amount_usd, credits_granted, tier, created_at, receipt_url }。type は "subscription"、"topup"、"refund" のいずれかで、"refund" では credits_granted がマイナスです。
invoices()Promise<BillingDocument[]>GET /v1/billing/invoices。セッション専用。すべての支払いを書類として、新しい順に返します。kind は、サブスクリプションの支払いでは "invoice" で、Stripe の number、pdfUrl、url があります。クレジットパックやチャージでは "receipt" で、付与された credits と領収書の url があり、PDF はありません。返金は status が "refunded" の領収書で、amount と credits はマイナスです。status は "paid"、"open"、"void"、"uncollectible"、"refunded" のいずれかです。
paymentMethod()Promise<BillingPaymentMethod>GET /v1/billing/payment-method。セッション専用。{ card, billingDetails } です。card は { brand, last4, expMonth, expYear } または null、billingDetails は { name, email, country } または null です。まだ購入していないアカウントでは、エラーではなく、どちらも null です。
autoRecharge()Promise<BillingAutoRecharge>GET /v1/billing/auto-recharge。セッション専用。{ enabled, thresholdCredits, amountUsd, failureCount, lastAttemptAt, hasSavedCard } です。残高がしきい値を下回ると、保存されたカードからその金額がチャージされます。
setAutoRecharge(input)Promise<BillingAutoRechargeSaved>PUT /v1/billing/auto-recharge。セッション専用。{ enabled, thresholdCredits?, amountUsd? } です。オンにするには両方の数値が必要です。thresholdCredits は 100〜100,000、amountUsd は topUpRange の範囲内の整数の金額です。そうでない場合は、ステータス 400 の NodaroError をスローします。保存すると、失敗回数がリセットされます。
checkout(input)Promise<BillingCheckoutSession>POST /v1/billing/create-checkout-session。セッション専用。{ priceId, mode?, returnPath?, embedded?, uiMode?, replacesSessionId? } で { url } を返します。プランの価格やクレジットパックの Stripe Checkout のページで、その人をそこに送ります。プロモーションコードはプランにだけ適用され、支払額 0 で確定したパックの購入ではクレジットは付与されません。アカウントにすでにサブスクリプションがある間、プランについてはステータス 409 をスローします。代わりに changePlan() を使ってください。ユーザーに販売しないデプロイメントでは、コード self_serve_disabled の ForbiddenError をスローします。uiMode: "embedded" では、Stripe の埋め込み Checkout のために { url: null, clientSecret, sessionId } を返します。このフォームはリダイレクトしません。自分の画面の中で購入するを参照してください。replacesSessionId は、このセッションが置き換える、自分の以前の Checkout セッションを指定します。
loadCredits(input)Promise<BillingLoadSession>POST /v1/billing/create-load-session。セッション専用。{ amountUsd, returnPath?, embedded?, uiMode?, replacesSessionId? } で { url, credits } を返します。topUpRange の範囲内の整数の金額を、パックと同じレートでクレジットとしてチャージする Checkout のページです。credits は付与される量です。カードは自動チャージのために保存されます。uiMode: "embedded" では、checkout() と同じように { url: null, clientSecret, sessionId, credits } を返します。
checkoutStatus(sessionId)Promise<BillingCheckoutStatus>GET /v1/billing/checkout-session/:sessionId。セッション専用。自分の Checkout セッション 1 つの { status, paymentStatus, mode, granted, paymentUnderWay? } です。granted は、そのクレジットまたはプランがアカウントに付与されると true になります。自分のものではないセッション、または存在しないセッションでは、コード checkout_session_not_found の NotFoundError をスローします。1 分に 60 回を超えて読み取ると、RateLimitedError をスローします。
portal(input?)Promise<BillingPortalSession>POST /v1/billing/manage-subscription。セッション専用。{ returnPath? } で { url } を返します。カード、請求先住所、請求書、解約のための Stripe カスタマーポータルのページです。最初の購入の前は NotFoundError をスローします。
changePlan(input)Promise<BillingChangePlanResult>POST /v1/billing/change-plan。セッション専用。{ newPriceId } で { subscriptionId, tier } を返します。有効なサブスクリプションを別のプランの価格に移します。アップグレードでは、請求期間の残りの価格差がすぐに請求され、その支払いが成功したときにだけ適用されます。2 つのプランの月間クレジットの差が請求期間ごとに 1 回付与され、0 で確定したアップグレードの請求書では付与されません。ダウングレードはすぐに適用され、未使用の期間は次の請求書でクレジットされ、現在のクレジットは期間が終わるまで残ります。月払いと年払いの切り替えでは、クレジットは付与されません。有効なサブスクリプションがない場合は NotFoundError、パックの価格や現在の価格ではステータス 400、サブスクリプションが有効でない場合はステータス 409 をスローします。アップグレードが支払いを待っている場合は、ステータス 409、コード plan_change_payment_required の NodaroError をスローします。プランは変わらず、details.invoiceUrl がその支払いのための Stripe のページです。1 つのアカウントから 24 時間に 5 回プラン変更をリクエストしたあとは、RateLimitedError をスローします。プランを変更するを参照してください。

returnPath は、Stripe がその人を戻す、自分のオリジン上のパスです。たとえば "/billing" や "/settings/credits?tab=history" です。先頭に / が 1 つあり、クエリを含められ、ホストと # は含みません。決済とチャージは、クエリに checkout=success または checkout=cancelled を加えます。returnPath は embedded より優先されます。省くと、Nodaro アプリ自身のページが使われます。

// A billing screen in a first-party app, signed in with supabaseAuth.
const [method, docs, auto] = await Promise.all([
  client.billing.paymentMethod(),
  client.billing.invoices(),
  client.billing.autoRecharge(),
])
// Buy a pack and come back to this screen.
const { url } = await client.billing.checkout({ priceId: pack.priceId!, returnPath: "/settings/credits" })
window.location.assign(url!)

// Or buy inside this screen with Stripe's embedded Checkout.
const { stripePublishableKey } = await client.billing.plans()
const { clientSecret, sessionId } = await client.billing.checkout({ priceId: pack.priceId!, uiMode: "embedded" })
// Mount Stripe's embedded Checkout with stripePublishableKey and clientSecret. When it completes:
const { granted } = await client.billing.checkoutStatus(sessionId!)

BillingPlan には、次のフィールドがあります。

フィールド型説明
idstring"free"、"basic"、"standard"、"pro"、"business" のいずれかです。
namestring表示名です。
prices{ monthly, yearly } | null無料プランでは null です。monthly は { priceId, amount, currency, credits } です。yearly には、年額を月数で割った perMonth が加わります。priceId は、checkout() と changePlan() が受け取り、サブスクリプションの stripe_price_id と一致する Stripe の価格 ID です。amount は通貨の主単位で(12 は 12.00 を意味します)、currency は "USD" などの ISO 4217 のコードです。現在販売できない場合、どちらの価格も null になることがあります。その場合は無料ではなく、利用できないものとして表示してください。
prices.*.credits{ amount, per } | nullその価格で付与される内容で、per は "month" または "year" です。年額の価格でも、月額の価格と同じく、プランのクレジットが毎月付与されます。
signupCreditsnumber | null無料プランで、登録時に 1 回だけ付与されるクレジットです。有料プランでは null です。
parallelismnumber1 つのワークフローで同時に実行されるノードの数です。
storageBytesnumberメディア用のストレージで、単位はバイトです。

topUps は、クレジットパック { id, credits, price, priceId } で、小さい順です。id は "topup-25" のようなパック自身の ID です。現在価格を示せない場合、price は null です。priceId は checkout() 用の Stripe の価格 ID で、price とあわせて null になります。パックは、loadCredits() で price.amount をチャージすれば、いつでも購入できます。topUpRange({ min, max, currency })は、クレジットとしてチャージできる整数の金額の範囲で、パックと同じレートです。プランなしでクレジットを購入する方法については、サブスクリプションなしの API を参照してください。

自分の画面の中で購入する

checkout() と loadCredits() は uiMode(BillingUiMode)を受け付けます。既定の "hosted" は Checkout のページの url を返し、"embedded" は Stripe の埋め込み Checkout フォームのために { url: null, clientSecret, sessionId } を返します。フォームは、clientSecret と、plans() の stripePublishableKey を使って表示します。フォームはリダイレクトしないため、returnPath と embedded は使われません。ただし、無効な returnPath では、引き続きステータス 400 をスローします。ステータス 503、コード embedded_checkout_unavailable の NodaroError は、デプロイメントに埋め込みフォームがないことを意味します。Checkout のページを使ってください。

フォームが完了したら、granted が true になるまで checkoutStatus(sessionId) をポーリングし、それから残高をもう一度読み取ります。プランの granted は、そのクレジットより少し先に true になることがあります。

replacesSessionId は、このセッションが置き換える、自分の以前の Checkout セッションの sessionId です。たとえば、埋め込みフォームをやめて、Checkout のページを開く場合です。こうすると、2 つのセッションの両方が支払われることはありません。ステータス 409、コード checkout_already_complete の NodaroError は、その購入が支払い済みであることを意味します。もう一度リクエストしないでください。checkout_in_progress は、支払いが確認中であることを意味します。checkoutStatus() を読み取り、paymentUnderWay: false で open、または expired になってから、もう一度リクエストしてください。checkout_session_not_found の NotFoundError は、そのセッションが自分のものではないか、同じ購入のものではないことを意味します。同じ購入とは、プランならプラン、同じパック、または同じ金額の load です。状態を読み取った後でも、置き換えが拒否されることがあります。そのため、もう一度リクエストするのは、ユーザーが操作したときだけにするか、試す間隔を長くしてください。以前の Checkout セッションを置き換えるを参照してください。

モデルと料金をあわせて表示する

1 つのノード向けに、各モデルの料金を隣に添えたモデルピッカーを作ります。

const { data: node } = await client.nodes.get("generate-video")
const { data: prices } = await client.credits.modelCosts(node.providers ?? [])

const options = (node.providers ?? []).map((id) => ({
  id,
  price: prices[id] ?? null, // null: no price on this instance
}))

ノードのデフォルトモデルを使うには、実行時に provider を省略します。ユーザーがモデルを選んだ場合は、その ID を provider として client.nodes.runAndWait() に送ります。

よくある質問

コードから、Nodaro が提供するモデルを一覧表示するには、どうすればよいですか?

client.models.list() を呼び出します。画像、動画、オーディオのすべてのモデルが種類と開発元ごとにグループ化されて返され、モード、アスペクト比、解像度、長さに加えて、Nodaro Cloud ではクレジット料金も含まれます。

実行する前に、1 つのモデルの料金を調べるには、どうすればよいですか?

モデルの料金識別子(nano-banana-pro や nano-banana-pro:4K など)を指定して、client.credits.modelCosts を呼び出します。data フィールドには、各識別子とそのクレジット料金の対応が入ります。

SDK で LLM の呼び出しを見積もるには、どうすればよいですか?

@nodaro/shared/llm-models の llmPriceKey(feature, model) で料金キー(たとえば llm-chat:claude-fable-5)を作り、client.credits.modelCosts に渡します。数値は一般的な呼び出しの見積もりで、estimates に一覧表示されるので、≈N と表示してください。

SDK でクレジット残高を確認するには、どうすればよいですか?

client.credits.balance() を呼び出します。total フィールドは利用できるクレジット数で、サブスクリプションのクレジットとチャージしたクレジットに分かれています。

SDK で、実行にかかった料金を合計するには、どうすればよいですか?

各ページの nextCursor を使って client.credits.transactions() をページごとに読み、credits_charged を足し合わせます。実行が最初に確保した額である credits_reserved は、支払った額ではありません。

自分のアプリで Nodaro のプランと価格を表示するには、どうすればよいですか?

client.billing.plans() を呼び出します。ログインは不要で、すべてのプランを月額と年額の価格とクレジットとともに、クレジットパックとあわせて返します。購入には、その人自身のログイン済みセッションが必要で、client.billing.checkout() を使います。

SDK で使用状況や請求の履歴の画面を作るには、どうすればよいですか?

期間の合計を、モデル、カテゴリ、セッション、ワークフロー別に得るには client.credits.usageSummary() を呼び出します。残高のすべての動きには client.credits.history() を、同じ一覧の CSV には exportHistory() を使います。

セルフホスティング環境に、クレジット料金はありますか?

いいえ。セルフホスティングの Community エディションと Business エディションにはクレジットの仕組みがないため、レスポンスにモデルの料金やクレジットのコストは含まれません。

最終更新

目次