Models and credits

client.models returns the catalog of AI models a Nodaro instance offers, and client.credits returns your credit balance and the price of any model. client.billing returns the plans on sale and your subscription. Use them together to show users which models they can pick and what each run costs. The methods call the same endpoints as the Credits REST API. Prices and balances exist on Nodaro Cloud; self-hosted Community and Business installs have no credit system. See Credits.

Methods

client.models

models.list(opts?)

Returns the model catalog (GET /v1/models), grouped by kind (image, video, audio) and by maker. Each model has its capabilities, its credit prices on Nodaro Cloud, and short prompt tips. The endpoint is public, and the server caches the answer for 5 minutes. The MCP list_models tool returns the same data.

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)
    }
  }
}

The result has sections, one per kind, each with families of models; recommendations, lists of model ids for common jobs; and totalModels. Each model has these fields:

An older server leaves out maker and logoUrl.

defaultDuration is the length an unset duration renders and is charged at. autoDuration means duration: -1 lets the model choose the length. referenceTaskTypes lists the values referenceTaskType takes on that model: ["reference", "edit", "extend"] on seedance-2-5, and absent elsewhere.

Size rules and file formats

A model whose sizes depend on its aspect ratio or its background carries these fields. Every other model leaves them out, and so does an older server.

GPT Image 2.5 (gpt-image-2-5-flare, gpt-image-2-5-sunburst and their -i2i edit models) renders only 1K at 27:16, 16:27, 9:8 and 8:9. It renders a transparent background only at 1K, and takes a background setting only there. GPT Image 2.6 Flare and Sunburst also render a transparent background only at 1K.

A model that writes more than one kind of file carries outputFormats, its default first. Where it writes a GIF or an SVG, it also carries gifFrameSize (512), gifFrames ({ min, max, default, values? }), gifFrameDurationMs ({ min, max, step, default }) and svgLevels. See Image file formats.

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"]

To draw maker marks without the catalog, call GET /v1/model-makers. It answers { makers: [{ id, name, logoUrl }] }, with every maker the platform knows, and the same fields as the catalog. It is public and cached for 5 minutes. See Discover models.

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)")

The same catalog is on the Models pages. For advice on which model to use, read Choosing a model.

client.credits

credits.balance()

Returns your credit balance and tier (GET /v1/user/credits). Throws UnauthorizedError when no user is signed in.

balance(): Promise<UserBalance>

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

Prefer effectiveTier over tier when you decide what to show. On a deployment where one billing account pays for every user, tier and effectiveTier are the deployment's plan, the billing account's tier.

BalanceDisplay holds unit (the unit's label), decimals (the places its figures carry, 0 to 4), then total, subscription, topup, dailySpent, dailyLimit, monthlyAllocation and appCreditsAllowance in that unit. Each is number | null, where null means unavailable: show an em dash, never 0. It adds allowance: { granted, remaining } | null, externalWallet: { available } and welcomeOffer: { credits }, each present exactly when the raw key is. Where the deployment names its unit per interface language, it also carries unitLabels (locale id to word): show unitLabels[locale] ?? unit. Render these figures as they are, and never convert credits yourself. display is absent for the billing account's own read on a deployment with one billing account, because its balance is the deployment's pool, kept in credits.

credits.modelCosts(ids)

Looks up the credit price of models and their variants in one call (POST /v1/credits/model-costs). It checks up to the first 50 identifiers.

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 maps each priced identifier to its credit price.
• missing lists identifiers that have no price. Show a dash for them.
• errors lists identifiers whose lookup failed. The other prices still arrive.
• estimates lists the identifiers in data whose figure is an estimate, not a fixed price. These are metered LLM price keys. Show them as ≈N. The field is absent when there are none.
• errorCodes says why each identifier in errors has no price. Today the code is llm_model_unpriced: a model with no rate on the lane it would be served on, which cannot be run. The field is absent when errors is empty.
• display is present on a deployment that shows its own unit instead of credits: { unit, decimals, data }, where data maps the same identifiers to their price in that unit, converted by the server (null means unavailable). An identifier in estimates is an estimate here too. Show unitLabels[locale] ?? unit as the unit's word when unitLabels is present. GET /v1/credits/model-cost adds display: { unit, decimals, creditCost } there. See Prices in the deployment's own unit.

The identifiers of each model are in the pricing field of models.list() and on each model's page. Settings such as quality, resolution and duration change the price, so name the variant the run will use. The price at run time is checked again when the run starts, so this call is a preview.

Speech models are priced by the length of the text. Their identifier for each started block of 100 characters is <model>:per-100-chars, for example elevenlabs-v4:per-100-chars. It lands in missing on an install that does not price speech by length, so the answer also tells you which rule the server charges by.

A request is priced as a whole and rounded once. So the exact price of a request of N started blocks is the identifier <model>:per-100-chars:<N>u, with N from 8 up to the model's cap per request. N times the block price can be higher. The same id shape prices every run charged per unit: <row>:<N>u is the exact price of N units of that row, for example apply-edl:4u, trim-video:5u, ltx-2.3-pro-retake:per-second:2.5u or elevenlabs-dubbing:3u. A whole Voice Changer Pro convert is voice-changer-pro:<slot>,<slot>,…, which voiceChangerProQuoteCreditId(slots) from @nodaro/shared builds. See Exact prices of runs priced per unit.

An LLM call has no fixed price. It is charged for the tokens it actually used, at the model's rate on the lane that served it. Its price key is <feature>:<model>, plus :direct on the provider's own API, or :effort-<level> on a model whose price depends on the Effort, and llmPriceKey from @nodaro/shared/llm-models builds it. The answer is an estimate of a typical call:

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])

A metered key in missing means the server does not price LLM calls per model, so show no price for it. GET /v1/credits/model-cost?model=<id> answers one identifier as { model, creditCost, estimate?: true, display? }. See LLM calls and How LLM calls are charged.

credits.transactions(options?)

Returns one page of your credit transactions, newest first (GET /v1/credits/transactions). Cloud edition only: a self-hosted install answers 404.

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

The page is { data: CreditTransaction[], nextCursor }. nextCursor is null when there are no more rows.

Which amount to read. A run first holds credits, then it is settled: it is charged all or part of the hold, and the rest goes back to your balance. Add up credits_charged for your spend. See Credits.

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?)

Returns the credit usage of a period, summed the way a billing screen shows it (GET /v1/credits/usage-summary). It counts your personal money only: a run a workspace paid for is not in it. Nodaro Cloud only.

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

On a deployment where one billing account pays for every user, only the billing account's own session can call it. Its tokens get ForbiddenError with the code payer_balance_jwt_only.

In totals:

• used adds up each run's charge. A run that is still running counts at its hold, and a refunded run does not count.
• purchased is the packs, the loads and the subscription grants.
• granted is the free credits, minus any grant taken back.
• refunded is what came back for a refunded run or from Stripe. A hold released when a run settled below it is not a refund.
• runs counts the runs charged or still running. avgPerRun is used divided by runs, with one decimal.

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?)

Returns one page of every movement of your balance, newest first (GET /v1/credits/history): runs, purchases, grants, refunds, adjustments and expiries, each with the balance after it. transactions() lists runs alone, while history() is the whole statement a billing screen shows. Nodaro Cloud only, with the same rule as usageSummary() on a deployment with one billing account.

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

The page is { data: CreditHistoryEntry[], nextCursor }. nextCursor is null at the end.

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?)

Returns the whole filtered history as CSV text (GET /v1/credits/history?format=csv). It has the same fields and filters as history(), one line per movement, newest first, and no paging. It holds at most 5,000 rows, and its last line says when the list was cut: narrow from and to for the rest.

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?)

Records the user's "yes" to the welcome offer in one action (POST /v1/credits/welcome-offer/claim). It records the marketing-email consent, then claims the free signup grant with that consent. The abuse checks still decide, so read grant. An account whose grant was already decided only has its consent recorded. Nodaro Cloud only: a self-hosted instance answers 404.

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

This method needs a signed-in browser session, from supabaseAuth(), because the consent is a person's choice. An API token or an OAuth app token gets 403. While the deployment has the offer switched off, the call answers 409 welcome_offer_disabled, so show the offer only when balance().welcomeOffer is present. On a deployment where one billing account pays for every user, free signup credits do not apply: the call answers 409 not_applicable, records nothing, not even the consent, and balance() carries no welcomeOffer.

WelcomeOfferClaimInput is the SignupKeys from collectSignupKeys() plus sourceApp, your app's slug of up to 40 lowercase letters, digits and dashes. A malformed slug is stored as absent, never refused. It also takes locale, the interface language the user answered in. That is the id of a language Nodaro ships, such as "en", "ja" or "pt-BR". It is matched exactly and case-sensitively, so "en-US" or "pt-br" is stored as absent. It is recorded with the consent as the language of the latest one.

WelcomeOfferState has three fields: popupSeen (the one-time popup was shown), consentPending (the account has its credits but still owes the email consent) and credits (what a claim grants). Show the credits figure in the offer instead of a fixed number, because it follows the server.

credits.markWelcomeOfferSeen()

Records that the one-time welcome popup was shown (POST /v1/credits/welcome-offer/seen), so welcomeOffer.popupSeen turns true in every app. Calling it again changes nothing. A failed call only means the popup may show once more, so you can ignore errors. The rules are those of claimWelcomeOffer(). On a deployment where one billing account pays for every user, it also answers 409 not_applicable.

markWelcomeOfferSeen(): Promise<{ ok: true }>

import { collectSignupKeys } from "@nodaro/sdk/signup-signals"

const { welcomeOffer } = await client.credits.balance()
if (welcomeOffer && !welcomeOffer.popupSeen) {
  showPopup({ credits: welcomeOffer.credits }) // the server's figure, never a constant
  void client.credits.markWelcomeOfferSeen().catch(() => {})
}

// 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 reads the plans and prices on sale, the caller's subscription, and how the deployment bills. In a first-party app signed in with the person's own session (supabaseAuth), it also covers the whole billing screen: purchases, invoices, the card on file, the automatic top-up, and the hand-offs to Stripe Checkout and the Customer Portal. The methods marked session only answer a signed-in session alone. An API key or an app's OAuth token gets ForbiddenError, so link such a client to the app's billing page instead.

// 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

returnPath is a path on your own origin, such as "/billing" or "/settings/credits?tab=history", that Stripe sends the person back to. It has one leading /, may have a query, and has no host and no #. Checkout and load add checkout=success or checkout=cancelled to its query. It wins over embedded. Without it, the Nodaro app's own pages are used.

// 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!)

A BillingPlan has these fields:

topUps are the credit packs, { id, credits, price, priceId }, smallest first. id is the pack's own id, such as "topup-25". price is null when it cannot be stated right now. priceId is the Stripe price id for checkout(), and it is null with the price. A pack can always be bought as a load of price.amount through loadCredits(). topUpRange, { min, max, currency }, is the range of whole amounts that can be loaded as credits, at the same rate as the packs. See Pay as you go for buying credits without a plan.

Show models with their prices

Build a model picker for one node, with the price next to each model:

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
}))

Omit provider in a run to use the node's default model. When a user picks a model, send its id as provider to client.nodes.runAndWait().