מודלים וקרדיטים

client.models מחזיר את קטלוג מודלי ה-AI שמופע של Nodaro מציע, והמשאב client.credits מחזיר את יתרת הקרדיטים שלכם ואת המחיר של כל מודל. המשאב client.billing מחזיר את התוכניות שנמכרות ואת המנוי שלכם. השתמשו בהם יחד כדי להראות למשתמשים אילו מודלים הם יכולים לבחור, וכמה עולה כל הרצה. המתודות קוראות לנקודות הקצה שבדף ה-API קרדיטים. מחירים ויתרות קיימים ב-Nodaro Cloud; בהתקנות באירוח עצמי של מהדורת Community ושל מהדורת Business אין מערכת קרדיטים. ראו את הדף קרדיטים.

מתודות

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 של מודלים; את השדה recommendations, רשימות של מזהי מודלים לשימושים נפוצים; ואת השדה totalModels. לכל מודל יש השדות האלה:

שרת מגרסה ישנה יותר משמיט את maker ואת logoUrl.

כדי להציג את הלוגואים של היצרנים בלי הקטלוג, קראו ל-GET /v1/model-makers. נקודת הקצה מחזירה { makers: [{ id, name, logoUrl }] }, עם כל יצרן שהפלטפורמה מכירה, ועם אותם שדות כמו בקטלוג. היא ציבורית, והתשובה נשמרת במטמון למשך 5 דקות. ראו בדף ה-API גילוי מודלים.

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

כשמחליטים מה להציג, עדיף להסתמך על effectiveTier ולא על tier.

credits.modelCosts(ids)‎

בודקת בקריאה אחת את המחיר בקרדיטים של מודלים ושל הווריאנטים שלהם (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 }>
}>

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 ריק, השדה לא מופיע.

המזהים של כל מודל מופיעים בשדה pricing של models.list() ובדף של כל מודל. הגדרות כגון איכות, רזולוציה ואורך משנות את המחיר, ולכן ציינו את הווריאנט שההרצה תשתמש בו. המחיר נבדק שוב כשההרצה מתחילה, ולכן הקריאה הזו רק מציגה אותו מראש.

מודלי דיבור מתומחרים לפי אורך הטקסט. המזהה שלהם לכל 100 תווים, או חלק מהם, הוא <model>:per-100-chars, למשל elevenlabs-v4:per-100-chars. בהתקנה שלא מתמחרת דיבור לפי אורך, המזהה הזה מופיע ב-missing, כך שהתשובה גם מראה לפי איזה כלל השרת גובה.

בקשה מתומחרת כמכלול ומעוגלת פעם אחת. לכן המחיר המדויק של בקשה עם N יחידות של 100 תווים, או חלק מהן, הוא המזהה <model>:per-100-chars:<N>u, כש-N נע מ-8 ועד התקרה של המודל לבקשה. מכפלה של N במחיר היחידה יכולה לצאת גבוהה יותר. אותה צורת מזהה נותנת מחיר לכל הרצה שמחויבת לפי יחידה: המזהה <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>,…, והפונקציה voiceChangerProQuoteCreditId(slots) מ-@nodaro/shared בונה אותו. ראו בדף ה-API מחירים מדויקים להרצות שמתומחרות לפי יחידה.

לקריאת LLM אין מחיר קבוע. היא מחויבת לפי הטוקנים שהיא השתמשה בהם בפועל, בתעריף של המודל בשירות שהריץ אותה. מפתח המחיר שלה הוא <feature>:<model>, ועוד :direct כשהקריאה רצה ב-API של הספק עצמו, והפונקציה llmPriceKey מ-@nodaro/shared/llm-models בונה אותו. התשובה היא אומדן של קריאה טיפוסית:

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> עונה על מזהה אחד בצורה { model, creditCost, estimate?: true }. ראו בדף ה-API קריאות LLM, ואת הסעיף איך מחויבות קריאות LLM בדף קרדיטים.

credits.transactions(options?)‎

מחזירה עמוד אחד מתנועות הקרדיטים שלכם, מהחדש לישן (GET /v1/credits/transactions). ב-Nodaro Cloud בלבד: בהתקנה באירוח עצמי הנתיב מחזיר 404.

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

העמוד הוא { data: CreditTransaction[], nextCursor }. השדה nextCursor הוא null כשאין עוד שורות.

איזה סכום לקרוא. קודם משוריינים קרדיטים להרצה, ואחר כך מגיע החיוב הסופי שלה: נגבה עליה כל השריון או חלק ממנו, והשאר חוזר ליתרה שלכם. כדי לחשב את ההוצאות שלכם, סכמו את credits_charged. ראו את דף ה-API קרדיטים.

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>

בפריסה שבה חשבון חיוב אחד משלם על כל המשתמשים, רק הסשן של חשבון החיוב עצמו יכול לקרוא למתודה. קריאה עם האסימונים שלו נכשלת עם ForbiddenError והקוד payer_balance_jwt_only.

ב-totals:

• השדה used מסכם את החיוב של כל הרצה. הרצה שעדיין רצה נספרת לפי השריון שלה, והרצה שהקרדיטים עליה הוחזרו לא נספרת.
• השדה purchased כולל את החבילות, את הטעינות ואת הקצאות המנוי.
• השדה granted הוא הקרדיטים החינמיים, פחות מענקים שנלקחו בחזרה.
• השדה refunded הוא מה שחזר על הרצה שהקרדיטים עליה הוחזרו, או מ-Stripe. החלק של השריון שמשתחרר כשהחיוב הסופי של הרצה נמוך ממנו הוא לא החזר.
• השדה runs סופר את ההרצות שחויבו או שעדיין רצות. השדה avgPerRun הוא used חלקי runs, עם ספרה אחת אחרי הנקודה.

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

מחזירה עמוד אחד מתוך כל התנועות ביתרה שלכם, מהחדש לישן (GET /v1/credits/history): הרצות, רכישות, מענקים, החזרים, תיקונים ופקיעות תוקף, כל אחת עם היתרה שאחריה. המתודה transactions() מחזירה רק הרצות, ואילו history() מחזירה את הדוח המלא שמסך חיוב מציג. ב-Nodaro Cloud בלבד, ובפריסה עם חשבון חיוב אחד חל אותו כלל כמו ב-usageSummary().

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

העמוד הוא { data: CreditHistoryEntry[], nextCursor }. בעמוד האחרון השדה nextCursor הוא null.

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(), שורה אחת לכל תנועה, מהחדש לישן, בלי חלוקה לעמודים. יש בה 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?)‎

רושמת בפעולה אחת את ה״כן״ של המשתמש להטבת ההצטרפות (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 קיים.

הטיפוס WelcomeOfferClaimInput הוא האובייקט SignupKeys שהפונקציה collectSignupKeys() מחזירה, ועוד sourceApp, מזהה קצר (slug) של האפליקציה שלכם, עד 40 אותיות קטנות, ספרות ומקפים. מזהה פגום נשמר כאילו לא נשלח, ואף פעם לא נדחה. הקלט מקבל גם locale, שפת הממשק שבה המשתמש ענה. זה המזהה של שפה ש-Nodaro מציע, כגון "en", "ja" או "pt-BR". ההתאמה מדויקת ותלויה ברישיות, ולכן "en-US" או "pt-br" נשמרים כאילו לא נשלחו. השפה נרשמת עם ההסכמה, כשפה של ההסכמה האחרונה.

לטיפוס WelcomeOfferState יש שלושה שדות: popupSeen (החלון הקופץ החד־פעמי הוצג), consentPending (הקרדיטים כבר נמצאים בחשבון, אבל ההסכמה לקבלת מיילים עדיין חסרה) ו-credits (מה שמימוש ההטבה מעניק). הציגו בהטבה את המספר שב-credits במקום מספר קבוע, כי המספר נקבע לפי השרת.

credits.markWelcomeOfferSeen()‎

רושמת שהחלון הקופץ החד־פעמי של הטבת ההצטרפות הוצג (POST /v1/credits/welcome-offer/seen), כך שהשדה welcomeOffer.popupSeen הופך ל-true בכל אפליקציה. קריאה נוספת לא משנה כלום. קריאה שנכשלה פירושה רק שהחלון הקופץ עשוי להופיע פעם נוספת, ולכן אפשר להתעלם משגיאות. חלים אותם כללים כמו ב-claimWelcomeOffer().

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 קורא את התוכניות והמחירים שנמכרים, את המנוי של מי שקורא למתודות ואת אופן החיוב של הפריסה. באפליקציית צד ראשון שמחוברת עם הסשן של המשתמש עצמו (supabaseAuth), המשאב מכסה גם את כל מסך החיוב: רכישות, חשבוניות, הכרטיס השמור, הטעינה האוטומטית והמעבר ל-Stripe Checkout ול-Customer Portal. המתודות שמסומנות לסשן בלבד עונות רק לסשן מחובר. קריאה עם מפתח 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

הפרמטר returnPath הוא נתיב ב-origin שלכם, כגון "/billing" או "/settings/credits?tab=history", ש-Stripe מחזיר אליו את המשתמש. הנתיב מתחיל ב-/ אחד, יכול לכלול מחרוזת שאילתה, ואין בו שם מארח או #. התשלום והטעינה מוסיפים למחרוזת השאילתה שלו 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!)

השדות של BillingPlan:

השדה topUps כולל את חבילות הקרדיטים, { id, credits, price, priceId }, מהקטנה לגדולה. השדה id הוא המזהה של החבילה עצמה, כגון "topup-25". השדה price הוא null כשאי אפשר לציין אותו כרגע. השדה priceId הוא מזהה המחיר ב-Stripe בשביל checkout(), והוא null כשהמחיר null. תמיד אפשר לקנות חבילה כטעינה של price.amount דרך loadCredits(). השדה topUpRange, { min, max, currency }, הוא טווח הסכומים השלמים שאפשר לטעון כקרדיטים, באותו תעריף כמו החבילות. על קניית קרדיטים בלי תוכנית, ראו את הדף API בלי מנוי.

הצגת מודלים עם המחירים שלהם

כך בונים תפריט בחירת מודל לרכיב אחד, עם המחיר ליד כל מודל:

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 בהרצה כדי להשתמש במודל ברירת המחדל של הרכיב. כשמשתמש בוחר מודל, שלחו את המזהה שלו בתור provider ל-client.nodes.runAndWait().