קרדיטים

קרדיטים הם היחידה שבה משלמים ב-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 פירושו שאין מנוי, אבל נקנו קרדיטים, ואז כל המודלים פתוחים, אין סימן מים ואין תקרה יומית.

הנתיב GET /v1/user/credits, שמאחורי המתודה client.credits.balance() של ה-SDK, מחזיר יותר פרטים:

ההוצאה יורדת קודם מקרדיטי המנוי. קרדיטי המנוי מתאפסים בכל חודש להקצאה החודשית של התוכנית, גם בתוכנית שנתית, וקרדיטי מנוי שלא הוצאו לא עוברים לחודש הבא. קרדיטי טעינה תקפים 12 חודשים מהרכישה.

כשהפריסה מציעה הטבת הצטרפות, התשובה של GET /v1/user/credits כוללת גם welcomeOffer: { popupSeen, consentPending, credits }. השדה credits הוא מספר הקרדיטים שמימוש ההטבה מעניק: הציגו את המספר הזה, ולא מספר קבוע. כל עוד אין הטבה פעילה, השדה הזה לא מופיע. את ההטבה מממשים באפליקציית הווב של Nodaro: שני הנתיבים שלה, POST /v1/credits/welcome-offer/claim ו-POST /v1/credits/welcome-offer/seen, מקבלים רק סשן מחובר בדפדפן, ומחזירים 403 forbidden לאסימון API או לאסימון של אפליקציית OAuth.

איך נגבים קרדיטים

• משוריינים כשמשימה מתחילה. לפני שיצירה רצה, המחיר שלה משוריין. כשהיתרה שלכם לא מכסה את המחיר, הקריאה נדחית עם 402 insufficient_credits עם required, וברוב החשבונות גם עם balance. בהרצת תהליך, המחיר של כל רכיב משוריין כשהרכיב מתחיל, ורכיב שהיתרה שלכם לא מכסה את המחיר שלו נכשל.
• נגבים כשהמשימה מחזירה תוצאה. השריון הופך לחיוב.
• מוחזרים כשהיא לא מחזירה תוצאה. על יצירה שנחסמה במסנן הבטיחות של מודל או במדיניות של פריסה, תמיד מקבלים החזר, וכך גם על משימות שבוטלו. קריאת LLM שמחויבת לפי השימוש היא החריג: על שימוש שהספק כבר חייב עליו משלמים.
• קריאות LLM מחויבות לפי השימוש. בקריאה למודל שפה משוריינים קודם קרדיטים, ואז הקריאה מחויבת לפי הטוקנים שהיא השתמשה בהם, בתעריף של המודל. ראו את הסעיף קריאות LLM.
• המחיר נקבע לפי מה שרץ בפועל. כשהשרת מתקן הגדרה בשביל המודל שנבחר, השריון נקבע לפי הערך המתוקן. ראו בדף ה-API תיקוני פרמטרים.

השדה credit_status של משימה והשדה status של תנועה עוברים את אותם שלבים: reserved, ואחריו committed או refunded. כך אפשר לדעת מהמשימה עצמה אם הקרדיטים שלה חזרו. ראו בדף ה-API הקרדיטים של משימה.

היסטוריית התנועות

הנתיב 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_charged": 50,
      "credits_reserved": 50,
      "credits_used": 50,
      "action": "generate-image",
      "provider": "nano-banana-pro",
      "status": "committed",
      "metadata": { "model": "nano-banana-pro", "from_sub": 50, "from_topup": 0 },
      "payer": "user",
      "workspaceId": null
    }
  ],
  "nextCursor": "2026-09-26T14:03:11.284Z"
}

איזה סכום לקרוא. קודם משוריינים קרדיטים להרצה: זה השריון. אחר כך מגיע החיוב הסופי של ההרצה: נגבה עליה כל השריון או חלק ממנו, והשאר חוזר ליתרה שלכם. בחלק מההרצות החיוב הסופי נמוך מהשריון לעיתים קרובות, למשל כשהשריון מכסה רינדור חוזר אפשרי, כשהאורך נמדד אחרי ההרצה או בהרצה שמחויבת לפי השימוש. לכן השריון הוא לא מה ששילמתם. למשל, בהרצה ששוריינו לה 888 קרדיטים ונגבו עליה 444, הערכים הם credits_charged: 444, credits_reserved: 888, credits_used: 888 ו-status: "committed". 444 הקרדיטים האחרים חזרו ליתרה שלכם.

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

ב-metadata יכולים להופיע רק המפתחות האלה, כשהם רלוונטיים: model, from_sub ו-from_topup (איזו מהיתרות שלכם שילמה), is_app_run, allowance_delta, web_free_mode, status, loop_trim_refunded ו-surround_refine_refunded.

השדה nextCursor הוא null כשאין עוד שורות.

סיכום שימוש

הנתיב GET /v1/credits/usage-summary מסכם את השימוש בקרדיטים בתקופה מסוימת, כמו שמסך חיוב מציג אותו. הוא סופר רק את הכסף האישי שלכם: הרצה שסביבת עבודה שילמה עליה והקרדיטים של ארגון שייכים לארנק אחר. התשובה היא { data: UsageSummary }.

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

ב-SDK זו המתודה client.credits.usageSummary(), וב-CLI הפקודה nodaro billing summary.

כל התנועות ביתרה שלכם

הנתיב GET /v1/credits/history מחזיר את כל התנועות ביתרה שלכם, מהחדש לישן, בצורה { data: HistoryEntry[], nextCursor }: הרצות, רכישות, מענקים, החזרים, תיקונים ופקיעות תוקף.

לשורת החזר, ולשורה של חריגה מעבר לשריון באותה משימה כשהיא מחויבת לפי השימוש, יש charge: null. כך סכימה של charge לאורך רשימה סופרת כל משימה פעם אחת. כדי לדעת כמה הוצאתם, בדקו את charge, לא את amount.

בקובץ ה-CSV יש אותם שדות, שורה אחת לכל תנועה, והמספרים כתובים בו כמספרים. כשהרשימה נקטעה ב-5,000 שורות, השורה האחרונה בקובץ מציינת זאת. ב-SDK אלה המתודות client.credits.history() ו-client.credits.exportHistory(), וב-CLI הפקודה nodaro billing history, עם --csv בשביל הקובץ.

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

דוח חודשי במייל

מי שמפעיל את monthlyStatementEmail ב-GET / PATCH /v1/user/settings מקבל מייל קצר ב-1 בכל חודש, אם הוא שילם במהלך החודש הקודם. כברירת מחדל ההגדרה כבויה. המייל מפרט את מסמכי התשלום של החודש הקודם:

• כמה שולם, בדולרים, אחרי ניכוי החזרים.
• כמה חשבוניות וקבלות היו.
• קישור למסמך החדש ביותר שיש לו קישור. זה קובץ ה-PDF של החשבונית ב-Stripe, או הדף של הקבלה, מבין המסמכים ששולמו ש-GET /v1/billing/invoices מחזיר.
• היתרה.

החודשים הם חודשים קלנדריים לפי UTC. בחודש בלי תשלום לא נשלח מייל.

הדוח החודשי במייל קיים רק ב-Nodaro Cloud, ורק כשבפריסה מוגדר מייל לדוחות. פריסה בלי מייל כזה לא שולחת דבר.

הגדרות משתמש

הנתיב GET /v1/user/settings מחזיר את ההגדרות של האדם המחובר: { data: { tier, publicOutputs, promptTemplates, textTemplates, preferredLocale, mcpPreferences, showRecentNodes, showMostUsedNodes, variableDisplayMode, nodeDoubleClickAction, monthlyStatementEmail } }.

הנתיב PATCH /v1/user/settings משנה את השדות שאתם שולחים, כל אחד מאותם שדות חוץ מ-tier, ומחזיר אותם כפי שנשמרו.

• השדות promptTemplates ו-textTemplates מחליפים את הערך השמור כולו. השדה mcpPreferences ממוזג ציר אחר ציר.
• הערך publicOutputs: false דורש ב-Nodaro Cloud את תוכנית Standard ומעלה. אחרת התשובה היא 403.
• ערך לא תקין נדחה עם 400 validation_error, ועדכון שאין בו מה לשנות נדחה עם 400. כשהפרופיל חסר, התגובה היא 404.

ב-SDK זה המשאב client.userSettings, עם המתודות get() ו-update(patch).

בדיקת המחיר לפני ההרצה

המחירים של המודלים ושל הרכיבים, ו-estimatedCredits, הם המחירים שלפיהם הרצה מחויבת: אותם מספרים שמופיעים על הכפתור הרצה בעורך. ברכיבים קיצוץ וידאו, לולאת וידאו ושילוב סרטונים, ה-creditCost של רכיב הוא במקום זאת המחיר של מדרגה אחת של 5 שניות, והרצה עולה כמה מדרגות כאלה. ב-estimatedCredits, רכיב אפקטי קול לווידאו נספר לפי המחיר של 8 שניות, כי הקליפ שלו נמדד רק כשההרצה מתחילה. בהרצה עצמה נגבה המחיר של האורך שנמדד.

סכום כולל שיש בו רכיב LLM עם חיוב לפי השימוש הוא אומדן. במקרה כזה הנתיב estimate-workflow מוסיף estimate: true, והנתיב GET /v1/api/schema מוסיף estimatedCreditsIsEstimate: true. הציגו סכום כזה כ-≈N. הסכום הוא האומדנים ועוד המחירים הקבועים, אף פעם לא שריון.

כדי לקבל אומדן מחיר מדויק לשלב שהמחיר שלו נקבע לפי אורך הקליפ, רכיב upload-video בגוף הבקשה של estimate-workflow יכול להעביר ב-data שלו את duration של הקליפ (בשניות) ואת fps, לצד ה-url שלו. אז רכיב מסכת וידאו מקבל אומדן לפי האורך שלו בקצב הפריימים הזה, הכלל שלפיו ההרצה שלו מחויבת. האומדן המדויק עובד גם אחרי רכיב קיצוץ וידאו או לולאת וידאו, ואחרי רכיב שילוב סרטונים שכל הקליפים שלו מצהירים על אותו קצב פריימים.

המחיר של מודל יכול להיקבע לפי ההגדרות שלו, ולכן ההגדרות מופיעות במזהים של הווריאנטים, כגון 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": 50, "nano-banana-pro:4K": 66, "gpt-image-2:2K": 42 },
  "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)

מחירים מדויקים להרצות שמתומחרות לפי יחידה

חלק מההרצות מתומחרות לפי יחידה, והמחיר מחושב על ההרצה כולה ומעוגל פעם אחת. לכן מחיר היחידה כפול מספר היחידות יכול לצאת גבוה ממה שההרצה עולה. כדי לקבל אומדן מחיר להרצה כזו, בקשו את המזהה <row>:<N>u, המחיר המדויק של N יחידות של שורת המחיר הזו. גם הנתיב POST /v1/credits/model-costs וגם הנתיב GET /v1/credits/model-cost מחזירים מחיר למזהה כזה.

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

להמרה שלמה של רכיב משנה קול Pro יש מזהה משלה: voice-changer-pro:<slot>,<slot>,…, עם פריט אחד לכל קול שמוחלף. פריט של קול במנוע המרת קול הוא sts-<seconds>, לפי אורך הסטם שלו. פריט של קול במנוע הקראה מחדש הוא respeak-<characters> ב-v3, respeak-v4-<characters> ב-v4, ו-respeak-v4t-<characters> ב-v4 כשהוא מקריא תרגום. בתרגום, שלחו את מספר התווים שבתמלול: השרת מוסיף בעצמו את התוספת לשורה שמרונדרת מחדש. כשהמידה לא ידועה, השתמשו בסוג בלי מספר. למשל, voice-changer-pro:sts-26.76,respeak-v4-1200,respeak-v4t-800. שתי נקודות הקצה מחזירות עבור המזהה את הקרדיטים שמשוריינים להמרה. המחירים של הקולות אחד אחד לא מסתכמים למספר הזה, כי ההמרה מחויבת לפי הסכום שלהם, שמעוגל פעם אחת. יותר מ-8 פריטים, סטם ארוך משעה או פריט פגום מופיעים ב-missing. החבילה @nodaro/shared בונה את המזהה עם voiceChangerProQuoteCreditId(slots), ושם פריט של הקראה מחדש מקבל engine אופציונלי ("v3" או "v4") ודגל translated.

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

ב-CLI, הפקודה nodaro models cost <id…> מחזירה מחיר למזהים באותו אופן, והפקודה nodaro models list מציגה את רמות הקרדיטים של כל מודל.

קריאות LLM

לקריאת LLM אין מחיר קבוע. היא מחויבת לפי הטוקנים שהיא השתמשה בהם בפועל, בתעריף של המודל בשירות שהריץ אותה. ראו את הסעיף איך מחויבות קריאות LLM בדף קרדיטים.

• מפתח המחיר הוא <feature>:<model>, ועוד :direct כשהקריאה רצה ב-API של הספק עצמו, למשל llm-chat:gemini-3.6-flash ו-describe-to-picker:claude-opus-5.5:direct. הפונקציה llmPriceKey(feature, model, reasoningEffort?, advancedMode?) מ-@nodaro/shared/llm-models בונה את המפתח.
• התשובה היא אומדן: קריאה טיפוסית של התכונה הזו במודל הזה. הנתיב POST /v1/credits/model-costs מציין מזהים כאלה ב-estimates, והנתיב GET /v1/credits/model-cost מוסיף estimate: true ל-data שלו. הציגו אומדן כ-≈N. בתשובה לאצווה שיש בה רק מחירים קבועים אין שדה estimates.
• מודל בלי תעריף בשירות שאמור להריץ אותו לא יכול לרוץ. בתשובה לאצווה, המפתח שלו מופיע ב-errors, עם errorCodes: { "<key>": { code: "llm_model_unpriced", message } }. ההרצה עצמה נדחית לפני שמשהו משוריין. ראו בדף ה-API מודל שעדיין אין לו מחיר.
• מפתח של קריאה שמחויבת לפי השימוש, כשהוא מופיע ב-missing, פירושו שהשרת לא מתמחר קריאות LLM לפי מודל. אל תציגו לו מחיר.
• בגריפה של מודעות Meta עם ניתוח AI משוריינים המחיר הקבוע של הגריפה ועוד המחיר של קריאת ניתוח אחת לכל מודעה. בקשו את הניתוח כולו כמזהה אחד, <analysis key>:<items>u. הפונקציה scrapeAnalysisQuoteId ב-@nodaro/shared/social בונה אותו. התשובה היא הסכום של ההרצה כולה, מעוגל כלפי מעלה פעם אחת, ולכן האומדן של קריאה אחת כפול מספר הפריטים יכול לצאת גבוה יותר.

{
  "data": { "llm-chat:gemini-3.6-flash": <credits>, "nano-banana-pro": <credits> },
  "missing": [],
  "errors": [],
  "estimates": ["llm-chat:gemini-3.6-flash"]
}

ביטול. כשמבטלים משימת LLM שמחויבת לפי השימוש, אף פעם לא נגבה כל השריון שלה. משימה שהקריאה שלה כבר התחילה מחויבת לפי מה שהיא השתמשה בו, ושאר הקרדיטים מוחזרים. על משימה שבוטלה לפני שהקריאה שלה התחילה מקבלים החזר, חוץ ממה שניסיון קודם של אותה משימה כבר השתמש בו. קריאה אחת ל-POST /v1/jobs/:id/cancel על משימה שרצה מחזירה inFlight: true ומאפשרת לה להסתיים. ראו בדף ה-API ביטול או מחיקה של משימה.

אומדני מחיר ל-Seedance עם סרטוני ייחוס

הרצת Seedance 2 עם סרטוני ייחוס מחויבת לפי השניות של קליפי הייחוס, ועוד השניות של הפלט. הרצת Kling 4.0 (kling-4) מחויבת לפי הפלט, ועוד הארוך מבין הפלט והקליפים. בשני המקרים, המחיר נקבע לפי האורך בפועל של הקליפים. החישוב הזה חל על רכיב יצירת וידאו כשמחוברים אליו סרטוני ייחוס, ועל האפשרות Seedance 2.5 Edit ברכיב וידאו לווידאו, שקליפ המקור שלה הוא סרטון ייחוס 1. הנתיב POST /v1/credits/seedance-ref-estimate מודד את הקליפים ומתמחר אותם בדיוק כמו השריון של ההרצה. הוא לא יוצר משימה, ושום דבר לא משוריין. הוא דורש אסימון, ומקבל עד 60 בקשות לדקה.

{ "provider": "seedance-2-5", "resolution": "720p", "duration": 8, "referenceVideoUrls": ["https://example.com/clip.mp4"] }

התשובה היא { "data": { "credits", "min", "exact" } }. כשכל הקליפים מצוינים, השדה credits הוא בדיוק הסכום שמשוריין להרצה, והשדה min שווה לו. קליפ שאי אפשר למדוד נספר כקליפ הארוך ביותר שהמודל מקבל, כמו שההרצה סופרת אותו. עם unknownReferenceVideos, השדה exact הוא false: ב-credits כל קליפ לא ידוע מתומחר לפי הקליפ הארוך ביותר שהמודל מקבל, וב-min לפי הקצר ביותר. קליפ שההרצה הייתה דוחה נדחה גם כאן, עם אותה שגיאה של ההרצה, 400 video_too_long. העורך מציג את אותו טווח על הרכיב, כל עוד קליפ מחובר עדיין לא נוצר.

תוכניות ומחירים

הנתיב GET /v1/billing/plans מחזיר את התוכניות ואת חבילות הקרדיטים שנמכרות, וכמה כל אחת עולה. הנתיב ציבורי: הוא לא דורש אסימון ולא קורא אסימון, ולכן דף תמחור יכול לקרוא לו עוד לפני שמישהו מתחבר. כל מי שקורא לו מקבל את אותה תשובה, שנשלחת עם Cache-Control: public, max-age=300. הוא עונה רק ב-Nodaro Cloud. ב-SDK זו המתודה client.billing.plans(), וב-CLI הפקודה nodaro billing plans, בלי צורך בהתחברות.

{
  "data": [
    { "id": "free", "name": "Free", "prices": null,
      "signupCredits": <credits>, "parallelism": <n>, "storageBytes": <bytes> },
    { "id": "basic", "name": "Basic",
      "prices": {
        "monthly": { "priceId": "price_…", "amount": <amount>, "currency": "USD",
                     "credits": { "amount": <credits>, "per": "month" } },
        "yearly":  { "priceId": "price_…", "amount": <amount>, "currency": "USD", "perMonth": <amount>,
                     "credits": { "amount": <credits>, "per": "month" } }
      },
      "signupCredits": null, "parallelism": <n>, "storageBytes": <bytes> }
  ],
  "topUps": [
    { "id": "topup-10", "credits": <credits>, "price": { "amount": <amount>, "currency": "USD" }, "priceId": "price_…" }
  ],
  "topUpRange": { "min": <amount>, "max": <amount>, "currency": "USD" }
}

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

התוכנית שלכם

הנתיב GET /v1/billing/subscription עונה לסשן מחובר, לאסימון API אישי בלי מגבלת תהליכים או לאסימון OAuth של אפליקציה. אסימון מוגבל לתהליכים נדחה עם 403 forbidden. התשובה היא { data, effectiveTier }:

• data הוא המנוי האחרון של החשבון, או null אם לחשבון אף פעם לא היה מנוי. יש בו tier, status (active, trialing, past_due, paused, canceled, incomplete או expired), current_period_start, current_period_end, cancel_at_period_end, cancel_at ו-canceled_at.
• effectiveTier הוא הרמה שלפיה נקבעות היכולות של החשבון. בדרך כלל זה id של תוכנית מ-GET /v1/billing/plans. הערך יכול להיות גם "payg", בחשבון בלי מנוי ועם קרדיטים שנקנו, או רמה שלא נמכרת, כגון "enterprise".

כדי לסמן את התוכנית הנוכחית, השוו את effectiveTier ל-data[].id מרשימת התוכניות. אם אין התאמה, החשבון בתשלום לפי שימוש או ברמה שלא נמכרת. ב-SDK זו המתודה client.billing.subscription(), וב-CLI הפקודה nodaro billing subscription.

רכישה וניהול החיוב

הנתיבים לרכישה ולניהול החיוב עונים רק לסשן מחובר: ה-JWT של Supabase שיש לאפליקציית ווב של צד ראשון. הם דוחים אסימוני API ואסימונים של אפליקציות OAuth עם 403 forbidden. כל אדם מנהל את החיוב שלו ב-app.nodaro.ai/billing, או באפליקציית צד ראשון שקוראת לנתיבים האלה דרך client.billing של ה-SDK.

כל מסמך של GET /v1/billing/invoices הוא { id, kind, number, at, amount: { amount, currency }, credits, status, description, pdfUrl, url }:

• הערך kind: "invoice" הוא תשלום על מנוי. הערכים number, pdfUrl ו-url (דף החשבונית ש-Stripe מארח) מגיעים מ-Stripe.
• הערך kind: "receipt" הוא חבילת קרדיטים או טעינה, עם ה-credits שהוענקו ועם דף הקבלה ש-Stripe מארח ב-url, בלי PDF. החזר הוא קבלה עם status: "refunded", וה-amount וה-credits שלה שליליים.
• השדה status הוא paid, open, void, uncollectible או refunded.
• כל מסמך ש-Stripe כותב — קובץ ה-PDF של החשבונית, דף החשבונית והקבלה — הוא באנגלית, בלי קשר לשפה שבה האדם שילם.

השדה returnPath, בתשלום, בטעינה ובפורטל, הוא הנתיב ש-Stripe מחזיר אליו את האדם, ב-origin שממנו מגיעה הקריאה, כגון /billing או /settings/credits?tab=history. כך אפליקציית צד ראשון ב-origin משלה חוזרת למסך שלה. הנתיב מתחיל ב-/ אחד, יכול לכלול מחרוזת שאילתה, ואין בו שם מארח, לוכסן הפוך או #. כל ערך אחר נדחה עם 400. התשלום והטעינה מוסיפים למחרוזת השאילתה שלו checkout=success או checkout=cancelled, והשדה returnPath גובר על embedded. בלעדיו, משתמשים בדפים /billing ו-/pricing של האפליקציה עצמה.

שינוי תוכנית

הנתיב POST /v1/billing/change-plan מעביר מנוי פעיל לתוכנית אחרת. מה שקורה נקבע לפי כיוון המעבר:

• שדרוג. הפרש המחיר על יתרת תקופת החיוב נגבה מיד. התוכנית החדשה נכנסת לתוקף רק כשהתשלום הזה מצליח.
• קרדיטים בשדרוג. החשבון מקבל את ההפרש בין הקרדיטים החודשיים של שתי התוכניות, פעם אחת בכל תקופת חיוב. מעבר לתוכנית נמוכה יותר וחזרה לתוכנית הגבוהה באותה תקופה לא מוסיפים עוד קרדיטים. חשבונית שדרוג שהחיוב הסופי שלה הוא 0, למשל עם קופון של 100% הנחה או עם יתרה שכיסתה אותה, לא מוסיפה קרדיטים.
• תשלום שדרוג שלא עובר. התוכנית נשארת כמו שהייתה, והתגובה היא 409 עם { error: { code: "plan_change_payment_required", message, invoiceUrl } }. השדה invoiceUrl הוא הדף של Stripe לתשלום החשבונית הזו. השינוי נכנס לתוקף אם החשבונית משולמת לפני שהיא פגה. אותה תגובה חוזרת גם כל עוד שינוי קודם עדיין מחכה לתשלום שלו.
• מעבר לתוכנית נמוכה יותר. ערך הזמן שנותר בתקופה מקוזז מהחשבונית הבאה. הקרדיטים הנוכחיים נשארים עד סוף התקופה.
• מחודשי לשנתי, או משנתי לחודשי. המעבר מתחיל את תקופת החיוב מחדש, אבל לא מוסיף קרדיטים. הקרדיטים החודשיים הבאים מגיעים חודש אחרי המעבר.

תגובות נוספות:

• הקוד 409, כשהמנוי לא פעיל, למשל אחרי תשלום חידוש שנכשל.
• הקוד 404, כשאין לחשבון מנוי.
• הקוד 429, אחרי 5 בקשות לשינוי תוכנית מאותו חשבון בתוך 24 שעות. גם בקשות שנדחו נספרות.

תשלום לפי שימוש

לא צריך מנוי כדי להשתמש ב-API.

• כל רכישה מפעילה אותו. קנייה של חבילת קרדיטים, או טעינה של כל סכום שלם בדולרים מ-$5 עד $1,000 בדף החיוב, מעבירה את החשבון לתשלום לפי שימוש. בטעינות גדולות יותר המחיר לקרדיט טוב יותר.
• הכל פתוח. effectiveTier הופך ל-payg: כל המודלים זמינים, לתוצאות אין סימן מים, ואין תקרת הוצאה יומית.
• הקרדיטים תקפים 12 חודשים מהרכישה.
• לממשקי המפתחים. קרדיטי תשלום לפי שימוש עובדים ב-API, ב-SDK, ב-CLI וב-MCP. העורך בדפדפן דורש מנוי, וחשבון בתשלום לפי שימוש שמוציא בו קרדיטים נדחה עם 403 subscription_required. קריאות עם אסימון אף פעם לא מקבלות את השגיאה הזו.
• במנוי המחיר לקרדיט נמוך יותר כשהשימוש קבוע.

שני דברים שכדאי לדעת:

• התוצאות ציבוריות כברירת מחדל. תוצאות פרטיות הן יכולת של מנוי, מתוכנית Standard ומעלה, ולכן תוצאות של תשלום לפי שימוש מופיעות בגלריה הציבורית. משימות שנוצרות דרך MCP תמיד פרטיות.
• המדיה נשמרת כל עוד החשבון פעיל. אחרי כ-3 חודשים בלי רכישה ובלי הוצאת קרדיטים, קבצים בני יותר מ-60 ימים עלולים להימחק. הוצאה חוזרת של קרדיטים עוצרת את הניקוי. הניקוי מוחק רק קבצים שיצירה שמרה כתוצאה שלה, אף פעם לא קלט שמופיע שוב בתוצאה, ואף פעם לא קובץ שאחד הפריטים בספרייה שלכם עדיין משתמש בו. כשקובץ נמחק, הקישור אליו מוגדר ל-null בכל תוצאת משימה שבה הוא מופיע.

רכישות דורשות סשן מחובר של האדם עצמו: נתיבי החיוב לתשלום, לטעינות, לשינויי תוכנית, לטעינה אוטומטית, להיסטוריית הרכישות, לחשבוניות ולפורטל התשלומים דוחים אסימוני API ואסימוני OAuth. נהלו את החיוב ב-app.nodaro.ai/billing, או ראו את הסעיף רכישה וניהול החיוב.

בדיקת אופן המדידה של הפריסה

שני נתיבים מאפשרים ללקוח לבנות תצוגות של עלויות ושל שימוש בלי להניח איך הפריסה מחייבת:

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: אל תציגו תצוגת עלויות.
• השדה deploymentPayer הוא true כשחשבון חיוב אחד משלם על כל המשתמשים. זהות החשבון הזה אף פעם לא מוצגת.

GET /v1/billing/account מחזיר את סיכום החשבון שלכם בצורה { "data": … }. כששירות החיוב לא יכול לענות, השדה data הוא null: הציגו את זה כלא זמין, אף פעם לא כיתרה של אפס. בסיכום תמיד יש:

פריסה יכולה להוסיף שדות אופציונליים, ולקוח מציג רק את השדות שהוא מקבל: periodStart, generations, spent, payg, daily, reserveValue ו-byCategory. סכומי כסף הם אובייקטים מהצורה { amount, currency }. ב-daily, הערך 0 ב-limit פירושו חסום, לא בלי הגבלה, והשדה daily גובר על dailyAllowance כששניהם קיימים. כל null פירושו לא זמין, אף פעם לא אפס: הציגו מקף.

POST /v1/jobs/cost-summary מסכם את הקרדיטים של אצוות משימות. השדה total_credits, ברמה העליונה ובכל שורת פירוט, הוא מספר או null, והתגובה מציינת את ה-unit שלה וסופרת ב-unavailable את המשימות שהיא לא הצליחה לתמחר. סכום null פירושו שלאף משימה באצווה לא היה חיוב ידוע. הוא לא אומר אפס.

סביבות עבודה וחיוב משותף

• תקציבי סביבות עבודה. התשלום על עבודה בתוך סביבת עבודה של ארגון יורד מהתקציב של סביבת העבודה, לא מהיתרה שלכם, ובתנועות שלה מופיע payer: "workspace". הרצה שחורגת מהתקציב נדחית עם 402 budget_exceeded, והרצה שחורגת מהתקרה האישית שלכם בסביבת העבודה הזו נדחית עם 402 member_cap_exceeded. ראו בדף ה-API סביבות עבודה וארגונים.
• פריסות עם חשבון חיוב אחד. בפריסה שבה חשבון חיוב אחד משלם על כל המשתמשים, GET /v1/user/credits מוסיף allowance: { granted, remaining, enforced }, המכסה האישית שלכם בקרדיטים. הערך enforced: false פירושו שהמכסה מוצגת, אבל לא עוצרת הרצות. השדה allowance הוא null בחשבון החיוב עצמו או כשאי אפשר היה לקרוא את המכסה, ולכן לעולם אל תתייחסו ל-null כאל אפס. כשהפריסה אוכפת מכסות, הרצה שחורגת מהמכסה שלכם נדחית עם 402 user_allowance_exceeded. חשבון החיוב מנהל את המאגר רק מהסשן שלו בדפדפן: קריאות יתרה שלו עם אסימון נדחות עם 403 payer_balance_jwt_only. הוא יכול גם להפעיל טעינה אוטומטית למאגר וליצור מפתחות אינטגרציה לחיוב, לקריאה בלבד. ראו את הסעיף הכלים של חשבון החיוב בדף ארנקים חיצוניים. לפריסות שמאשרות הוצאות דרך ארנק משלהן, ראו את הדף ארנקים חיצוניים.