# קרדיטים

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

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

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

נקודות הקצה של הקרדיטים קיימות רק ב-Nodaro Cloud. למהדורת Community ולמהדורת Business אין מערכת קרדיטים, ולכן הנתיבים האלה מחזירים שם `404`. הנתיב `GET /v1/billing/surface` הוא היוצא מן הכלל: הוא עונה בכל המהדורות.

## נקודות קצה
| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `GET` | `/v1/credits/balance` | היתרה שלכם: הסכום הכולל, קרדיטי המנוי וקרדיטי הטעינה, והרמה שלכם. |
| `GET` | `/v1/user/credits` | רשומת יתרה מלאה יותר, עם ההוצאה היומית. |
| `GET` | `/v1/credits/transactions` | היסטוריית הקרדיטים שלכם, בעמודים. |
| `GET` | `/v1/credits/usage-summary` | השימוש שלכם בקרדיטים בתקופה מסוימת, מסוכם לתצוגה במסך חיוב. |
| `GET` | `/v1/credits/history` | כל תנועה ביתרה שלכם, בעמודים או כקובץ CSV. |
| `POST` | `/v1/credits/model-costs` | ציבורית. המחיר בקרדיטים של עד 50 מזהי מודלים. |
| `GET` | `/v1/credits/model-cost` | ציבורית. המחיר בקרדיטים של מזהה מודל אחד, שנשלח כ-`?model=`. |
| `POST` | `/v1/credits/video-pro-estimate` | המחיר של הרצה של רכיב יצירת וידאו Pro. ראו בדף ה-API [משימות](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run). |
| `POST` | `/v1/credits/seedance-ref-estimate` | המחיר של הרצת Seedance 2 או Kling 4.0 עם סרטוני ייחוס. ראו את הסעיף [אומדני מחיר ל-Seedance עם סרטוני ייחוס](#seedance-reference-video-estimates). |
| `GET` | `/v1/billing/plans` | ציבורית. התוכניות וחבילות הקרדיטים שנמכרות, עם המחירים שלהן. |
| `GET` | `/v1/billing/subscription` | המנוי שלכם והרמה שהחשבון שלכם פועל לפיה. |
| `GET` | `/v1/billing/surface` | ציבורית. איך הפריסה הזו מודדת שימוש. |
| `GET` | `/v1/billing/account` | סיכום החשבון שלכם ממערכת החיוב של הפריסה. |
| `GET`, `POST`, `PUT` | `/v1/billing/…` | רכישות, חשבוניות, הכרטיס, הטעינה האוטומטית והתשלום, לסשן מחובר בלבד. ראו את הסעיף [רכישה וניהול החיוב](#buy-and-manage-billing). |
| `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` פירושו שאין מנוי, אבל נקנו קרדיטים, ואז כל המודלים פתוחים, אין סימן מים ואין תקרה יומית.

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

| שדה | משמעות |
| --- | --- |
| `total`, `subscription`, `topup` | הקרדיטים שלכם, כמו למעלה. |
| `dailySpent` | הקרדיטים שהוצאו היום. |
| `dailyLimit` | תקרת ההוצאה היומית שלכם, או `null` כשאין תקרה. |
| `monthlyAllocation` | הקרדיטים שהתוכנית שלכם מעניקה בכל מחזור חיוב. |
| `tier`, `effectiveTier` | הרמה השמורה שלכם והרמה שנאכפת. |
| `features` | היכולות שהרמה שלכם כוללת. |
| `periodEnd` | מתי תקופת החיוב מסתיימת. |
| `appCreditsAllowance` | קרדיטים שהרווחתם משימוש באפליקציות, במסלול החינמי בלבד. |

ההוצאה יורדת קודם מקרדיטי המנוי. קרדיטי המנוי מתאפסים בכל חודש להקצאה החודשית של התוכנית, גם בתוכנית שנתית, וקרדיטי מנוי שלא הוצאו לא עוברים לחודש הבא. קרדיטי טעינה תקפים 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](#llm-calls).
- **המחיר נקבע לפי מה שרץ בפועל.** כשהשרת מתקן הגדרה בשביל המודל שנבחר, השריון נקבע לפי הערך המתוקן. ראו בדף ה-API [תיקוני פרמטרים](https://nodaro.ai/docs/developers/api/workflows#parameter-corrections).

השדה `credit_status` של משימה והשדה `status` של תנועה עוברים את אותם שלבים: `reserved`, ואחריו `committed` או `refunded`. כך אפשר לדעת מהמשימה עצמה אם הקרדיטים שלה חזרו. ראו בדף ה-API [הקרדיטים של משימה](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_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"
}
```

| שדה | משמעות |
| --- | --- |
| `credits_charged` | כמה ההרצה עלתה לכם, אחרי החיוב הסופי. הערך יכול להיות נמוך מהשריון, הוא `0` כשהקרדיטים המשוריינים הוחזרו, והוא `null` כל עוד השריון עדיין פתוח (`status: "reserved"`). כדי לחשב את ההוצאות שלכם, סכמו את השדה הזה. |
| `credits_reserved` | השריון שנלקח כשההרצה התקבלה. הערך הזה אף פעם לא משתנה. |
| `credits_used` | אותו שריון כמו `credits_reserved`, בשם המקורי שלו, שנשמר בשביל אינטגרציות קיימות. הערך לא משתנה אחרי חיוב סופי חלקי, ולכן בהרצות כאלה הוא גבוה מהחיוב. עדיף להשתמש ב-`credits_charged`. |
| `action`, `provider` | מה רץ, ובאיזה מודל. |
| `status` | `reserved`, `committed` או `refunded`. |
| `payer` | `user` כשהתשלום יורד מהיתרה שלכם, `workspace` כשהוא יורד מתקציב של כיתה או של צוות. |
| `workspaceId` | סביבת העבודה שמשלמת, או `null`. |
| `metadata` | פרטים על החיוב של ההרצה. תמיד אובייקט, ו-`{}` כשאין פרטים רלוונטיים. |

**איזה סכום לקרוא.** קודם משוריינים קרדיטים להרצה: זה השריון. אחר כך מגיע החיוב הסופי של ההרצה: נגבה עליה כל השריון או חלק ממנו, והשאר חוזר ליתרה שלכם. בחלק מההרצות החיוב הסופי נמוך מהשריון לעיתים קרובות, למשל כשהשריון מכסה רינדור חוזר אפשרי, כשהאורך נמדד אחרי ההרצה או בהרצה שמחויבת לפי השימוש. לכן השריון הוא לא מה ששילמתם. למשל, בהרצה ששוריינו לה 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 [הקרדיטים של משימה](https://nodaro.ai/docs/developers/api/jobs#credits-of-a-job).

ב-`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 }`.

| פרמטר שאילתה | משמעות |
| --- | --- |
| `from`, `to` | חותמת זמן בפורמט ISO, או תאריך בלבד, למשל `2026-10-01`, שמציין את כל היום הזה לפי UTC. שני הגבולות כלולים בטווח. ברירת המחדל היא 30 הימים האחרונים, עד עכשיו. ההפרש ביניהם יכול להיות שנה לכל היותר, אחרת הקריאה נדחית עם `400`. |
| `bucket` | `day`, `week` או `month`, לסדרה לאורך זמן. ברירת המחדל היא `day`. |

| שדה | משמעות |
| --- | --- |
| `period` | `{ from, to, bucket }`, כפי שהשרת קיבל אותם. |
| `totals` | `{ used, purchased, granted, refunded, runs, avgPerRun }`. פירוט בהמשך. |
| `mostUsed` | השורה הראשונה ב-`byModel`, או `null` כשאין הרצות. |
| `byModel` | שורות `{ model, provider, credits, runs, share }`, ממוינות לפי ההוצאה. השדה `share` הוא החלק מתוך `used`, בין 0 ל-1. |
| `byCategory` | שורות `{ category, credits, runs }`, שבהן `category` הוא `image`, `video`, `audio` או `other`. |
| `overTime` | שורה אחת לכל יחידת זמן בתקופה, כולל יחידות ריקות, מהישן לחדש: `{ bucket, used, purchased, runs }`. השדה `bucket` הוא היום לפי UTC (`2026-10-26`), יום שני של השבוע או החודש (`2026-10`). יחידת הזמן הראשונה יכולה להיות שבוע חלקי או חודש חלקי. |
| `bySession`, `byWorkflow` | שורות `{ id, name, tool, credits, runs, models, lastAt }`, ממוינות לפי ההוצאה: כמה עלה כל סשן או כל תהליך. השדה `name` הוא `null` כשאין שם או כשהסשן או התהליך כבר לא קיימים, והשדה `tool` מופיע רק בסשן. |
| `truncated` | `true` כששליפת נתונים בשרת הגיעה לתקרה של 5,000 שורות, ולכן המספרים נמוכים מדי. בקשו תקופה קצרה יותר. |
| `partial` | `true` כששליפה משנית נכשלה, ולכן קיבוץ מסוים חסר או בלי שמות. הסכומים הכוללים עדיין מלאים. |

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

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

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

| פרמטר שאילתה | משמעות |
| --- | --- |
| `limit` | מ-1 עד 100. ברירת המחדל היא 50. |
| `cursor` | הערך `nextCursor` מהעמוד הקודם. זה ערך אטום: כל מחרוזת אחרת נדחית עם `400`. |
| `kind` | `usage`, `purchase`, `grant`, `refund`, `app`, `adjustment` או `expiry`. |
| `model` | מזהה מודל, בהתאמה מדויקת. |
| `from`, `to` | חותמות זמן בפורמט ISO, כולל הגבולות. |
| `q` | מילים לחיפוש בתיאור. |
| `format` | `json`, או `csv` לכל ההיסטוריה המסוננת כקובץ, עד 5,000 שורות, בלי חלוקה לעמודים. |

| שדה | משמעות |
| --- | --- |
| `id`, `at` | המזהה של השורה, ומתי התנועה קרתה. |
| `kind`, `source` | סוג התנועה. הערך `kind: "app"` מציין קרדיטים שהרווחתם מאפליקציה שפורסמה או ששילמתם על אפליקציה כזו, והערך `adjustment` מציין תיקון של מנהל וכל דבר אחר. השדה `source` הוא המונח שהרשומה עצמה משתמשת בו, כגון `usage`, `one_time_purchase`, `subscription_renewal`, `signup_grant`, `refund`, `app_earnings` או `expiry`. |
| `amount` | סכום התנועה, עם סימן: השריון של הרצה שלילי, ורכישה חיובית. |
| `balanceAfter` | היתרה מיד אחרי התנועה. |
| `pool` | `subscription`, `topup` או `mixed`. |
| `description` | ההערה של הרשומה. |
| `model`, `provider` | בשורה שקשורה למשימה, המודל שרץ. |
| `charge`, `status` | רק ב**שורת השריון** של משימה, כלומר בשורה של השריון שנלקח כשההרצה התקבלה. השדה `charge` הוא כמה ההרצה עלתה בסוף: החיוב הסופי, השריון כל עוד היא רצה, או `0` אחרי שהקרדיטים הוחזרו. השדה `status` הוא `reserved`, `committed` או `refunded`. |
| `job` | בשורה שקשורה למשימה: `{ id, type, status, startedAt, completedAt, durationMs, workflowId, sessionId }`. השדה `type` ושאר השדות הם `null` כשהמשימה כבר לא קיימת. |
| `receiptUrl` | הקבלה של Stripe, ברכישה שיש לה קבלה. |

לשורת החזר, ולשורה של חריגה מעבר לשריון באותה משימה כשהיא מחויבת לפי השימוש, יש `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`](https://nodaro.ai/docs/developers/sdk/client#user-settings), עם המתודות `get()` ו-`update(patch)`.

## בדיקת המחיר לפני ההרצה
| כלי | על מה הוא מחזיר מחיר |
| --- | --- |
| `POST /v1/credits/model-costs` | עד 50 מזהי מודלים בבת אחת. |
| `GET /v1/credits/model-cost` | מזהה מודל אחד. |
| `GET /v1/models` | כל מודל, עם רשומת `pricing` לכל וריאנט. ראו בדף ה-API [גילוי מודלים](https://nodaro.ai/docs/developers/api/nodes#discover-models). |
| `GET /v1/nodes/:type` | ה-`creditCost` של רכיב: מחיר יחיד או טווח. |
| `GET /v1/api/schema` | תהליך שלם, בשדה `estimatedCredits`. ראו בדף ה-API [תהליכים](https://nodaro.ai/docs/developers/api/workflows#run-a-workflow-with-new-input-values). |
| `POST /v1/credits/estimate-workflow` | תהליך שאתם שולחים בצורה `{ nodes, edges? }`. התשובה היא `{ data: { totalCredits, … } }`. |
| `POST /v1/credits/video-pro-estimate` | הרצה של רכיב יצירת וידאו Pro, בלי שריון קרדיטים. ראו בדף ה-API [משימות](https://nodaro.ai/docs/developers/api/jobs#estimate-a-run). |
| `POST /v1/credits/seedance-ref-estimate` | הרצת Seedance 2 או Kling 4.0 עם סרטוני ייחוס, שנמדדים כמו בהרצה עצמה. ראו את הסעיף [אומדני מחיר ל-Seedance עם סרטוני ייחוס](#seedance-reference-video-estimates). |
| `POST /v1/recast/estimate` | הרצת Recast. ראו את דף ה-API [Recast](https://nodaro.ai/docs/developers/api/recast). |
| `POST /v1/pro-3d-render/quote` | הרצה של רכיב רינדור תלת־ממד Pro. ראו את דף ה-API [סצנות תלת־ממד](https://nodaro.ai/docs/developers/api/3d-scenes). |

המחירים של המודלים ושל הרכיבים, ו-`estimatedCredits`, הם המחירים שלפיהם הרצה מחויבת: אותם מספרים שמופיעים על הכפתור **הרצה** בעורך. ברכיבים קיצוץ וידאו, לולאת וידאו ושילוב סרטונים, ה-`creditCost` של רכיב הוא במקום זאת המחיר של מדרגה אחת של 5 שניות, והרצה עולה כמה מדרגות כאלה. ב-`estimatedCredits`, רכיב [אפקטי קול לווידאו](https://nodaro.ai/docs/nodes/video/video-sfx#credits) נספר לפי המחיר של 8 שניות, כי הקליפ שלו נמדד רק כשההרצה מתחילה. בהרצה עצמה נגבה המחיר של האורך שנמדד.

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

כדי לקבל אומדן מחיר מדויק לשלב שהמחיר שלו נקבע לפי אורך הקליפ, רכיב `upload-video` בגוף הבקשה של `estimate-workflow` יכול להעביר ב-`data` שלו את `duration` של הקליפ (בשניות) ואת `fps`, לצד ה-`url` שלו. אז רכיב [מסכת וידאו](https://nodaro.ai/docs/nodes/video/video-mask) מקבל אומדן לפי האורך שלו בקצב הפריימים הזה, הכלל שלפיו ההרצה שלו מחויבת. האומדן המדויק עובד גם אחרי רכיב קיצוץ וידאו או לולאת וידאו, ואחרי רכיב שילוב סרטונים שכל הקליפים שלו מצהירים על אותו קצב פריימים.

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

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

| הרצה | יחידה | מזהה לדוגמה |
| --- | --- | --- |
| בקשה ליצירת דיבור | כל 100 תווים, או חלק מהם, מ-8 ועד התקרה של המודל לבקשה | `elevenlabs-v4:per-100-chars:12u` |
| רינדור של רכיב החלת רשימת עריכה או תצוגת דוברים | כל דקה | `apply-edl:4u` |
| קיצוץ וידאו, לולאת וידאו, שילוב סרטונים, הרכבת וידאו עם קריינות ושילוב לפי מסכה | כל 5 שניות | `trim-video:5u` |
| הרחבה או צילום חוזר ב-LTX 2.3 Pro | כל שנייה; N יכול להיות שבר | `ltx-2.3-pro-retake:per-second:2.5u` |
| דיבוב | כל דקה, או חלק ממנה, 1–30 | `elevenlabs-dubbing:3u`, ולדיבוב לעברית `elevenlabs-dubbing-v2:3u` |

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

להמרה שלמה של רכיב [משנה קול Pro](https://nodaro.ai/docs/nodes/audio/voice-changer-pro#credits) יש מזהה משלה: `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`, כך שמזהה שגוי אחד אף פעם לא מכשיל את כל הבקשה. הציגו עבורם מקף, לא אפס. המחירים שלמעלה הם דוגמה: השתמשו בתשובה שהשרת מחזיר בפועל, או ראו את הדף של כל מודל ב[מודלים](https://nodaro.ai/docs/models).

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

### קריאות LLM
לקריאת LLM אין מחיר קבוע. היא מחויבת לפי הטוקנים שהיא השתמשה בהם בפועל, בתעריף של המודל בשירות שהריץ אותה. ראו את הסעיף [איך מחויבות קריאות LLM](https://nodaro.ai/docs/concepts/credits#llm-calls) בדף קרדיטים.

- **מפתח המחיר** הוא `<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 [מודל שעדיין אין לו מחיר](https://nodaro.ai/docs/developers/api/errors#llm-model-unpriced).
- **מפתח של קריאה שמחויבת לפי השימוש**, כשהוא מופיע ב-`missing`, פירושו שהשרת לא מתמחר קריאות LLM לפי מודל. אל תציגו לו מחיר.
- ב**גריפה של מודעות Meta עם ניתוח AI** משוריינים המחיר הקבוע של הגריפה ועוד המחיר של קריאת ניתוח אחת לכל מודעה. בקשו את הניתוח כולו כמזהה אחד, `<analysis key>:<items>u`. הפונקציה `scrapeAnalysisQuoteId` ב-`@nodaro/shared/social` בונה אותו. התשובה היא הסכום של ההרצה כולה, מעוגל כלפי מעלה פעם אחת, ולכן האומדן של קריאה אחת כפול מספר הפריטים יכול לצאת גבוה יותר.

```text
{
"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 [ביטול או מחיקה של משימה](https://nodaro.ai/docs/developers/api/jobs#cancel-or-delete-a-job).

### אומדני מחיר ל-Seedance עם סרטוני ייחוס
הרצת Seedance 2 עם סרטוני ייחוס מחויבת לפי השניות של קליפי הייחוס, ועוד השניות של הפלט. הרצת Kling 4.0 (`kling-4`) מחויבת לפי הפלט, ועוד הארוך מבין הפלט והקליפים. בשני המקרים, המחיר נקבע לפי האורך בפועל של הקליפים. החישוב הזה חל על רכיב [יצירת וידאו](https://nodaro.ai/docs/nodes/video/generate-video) כשמחוברים אליו סרטוני ייחוס, ועל האפשרות Seedance 2.5 Edit ברכיב [וידאו לווידאו](https://nodaro.ai/docs/nodes/video/video-to-video), שקליפ המקור שלה הוא סרטון ייחוס 1. הנתיב `POST /v1/credits/seedance-ref-estimate` מודד את הקליפים ומתמחר אותם בדיוק כמו השריון של ההרצה. הוא לא יוצר משימה, ושום דבר לא משוריין. הוא דורש אסימון, ומקבל עד 60 בקשות לדקה.

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

| שדה | סוג | משמעות |
| --- | --- | --- |
| `provider` | string | `seedance-2`, `seedance-2-fast`, `seedance-2-mini`, `seedance-2-5` או `kling-4`. בכל מודל אחר הבקשה נדחית עם `400 validation_error`, והודעת השגיאה מציינת את המודלים שמתאימים. |
| `resolution` | string, אופציונלי | כמו שההרצה שולחת אותו. כשהשדה מושמט, משתמשים בברירת המחדל של המודל. |
| `duration` | number, אופציונלי | שניות הפלט. הערך `-1` פירושו האפשרות אוטומטי, שמתומחרת כמו בשריון של ההרצה: אורך הקליפ הראשון מעוגל כלפי מעלה לשנייה שלמה, ועוד שנייה אחת, ואף פעם לא יותר מהקליפ הארוך ביותר של המודל. כל עוד קליפ לא נמדד או לא ידוע, האפשרות אוטומטי מתומחרת לפי הקליפ הארוך ביותר של המודל. כשהשדה מושמט, משתמשים בברירת המחדל של המודל. |
| `draft` | boolean, אופציונלי | מצב הטיוטה של Seedance 2.5, שמתומחר לפי 480p. |
| `referenceVideoUrls` | string[] | קליפי הייחוס שההרצה תשלח, לפי הסדר. |
| `unknownReferenceVideos` | number, אופציונלי | קליפים מחוברים שהקובץ שלהם עדיין לא קיים, כי הרכיב שבמעלה הזרם עוד לא יצר אותם. |

התשובה היא `{ "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`, בלי צורך בהתחברות.

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

| שדה | משמעות |
| --- | --- |
| `data` | התוכניות: המסלול החינמי קודם, ואחריו התוכניות בתשלום, מהקטנה לגדולה. השדה `id` קבוע: `free`, `basic`, `standard`, `pro` או `business`. |
| `prices` | הערך הוא `null` במסלול החינמי. אחרת `monthly` ו-`yearly`: `priceId`, מזהה המחיר ב-Stripe שהתשלום ושינוי תוכנית מקבלים, `amount` ביחידה הראשית של המטבע, `currency` כקוד ISO 4217 ו-`yearly.perMonth`, הסכום השנתי מחולק על פני החודשים שלו. מחיר שאי אפשר למכור כרגע הוא `null`: הציגו אותו כלא זמין, אף פעם לא כחינם. |
| `prices.*.credits` | מה המחיר מעניק: `{ amount, per }`, כש-`per` הוא `"month"` או `"year"`. מחיר שנתי מעניק את הקרדיטים של התוכנית בכל חודש, כמו מחיר חודשי. הערך הוא `null` כשהמחיר לא מציין זאת. |
| `signupCredits` | המענק החד־פעמי של המסלול החינמי בהרשמה. הערך הוא `null` בתוכנית בתשלום, שהקרדיטים שלה מגיעים עם כל מחיר. |
| `parallelism` | כמה רכיבים של תהליך אחד רצים בו־זמנית. |
| `storageBytes` | נפח האחסון למדיה שלכם, בבייטים. |
| `topUps` | חבילות הקרדיטים, `{ id, credits, price, priceId }`, מהקטנה לגדולה. קרדיטי טעינה תקפים 12 חודשים. השדה `price` הוא `null` כשאי אפשר לציין אותו כרגע, ואז גם `priceId`, מזהה המחיר ב-Stripe לתשלום, הוא `null`. |
| `topUpRange` | `{ min, max, currency }`: אפשר לטעון באפליקציה כל סכום שלם בטווח הזה כקרדיטים, באותו תעריף כמו החבילות. |

| סטטוס | קוד | מתי |
| --- | --- | --- |
| `403` | `self_serve_disabled` | הפריסה לא מוכרת למשתמשים שלה. |
| `503` | `stripe_not_configured` | הפריסה לא מקבלת תשלומים בכרטיס. |
| `503` | `plan_prices_unavailable` | אי אפשר היה לקרוא את המחירים. נסו שוב בעוד רגע. |

כדי למכור תוכנית, שלחו את המשתמש לדף התמחור באפליקציה של Nodaro, או התחילו תשלום מאפליקציית צד ראשון. ראו את הסעיף [רכישה וניהול החיוב](#buy-and-manage-billing).

### התוכנית שלכם
הנתיב `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](https://app.nodaro.ai/billing), או באפליקציית צד ראשון שקוראת לנתיבים האלה דרך `client.billing` של ה-SDK.

| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `POST` | `/v1/billing/create-checkout-session` | פותחת את Stripe Checkout לתוכנית או לחבילת קרדיטים: מקבלת `{ priceId, mode?, embedded?, returnPath? }` ומחזירה `{ data: { url } }`. ב-Checkout של תוכנית אפשר להזין קוד הנחה, וב-Checkout של חבילת קרדיטים אי אפשר. רכישת חבילה שהחיוב הסופי שלה הוא 0 לא מעניקה קרדיטים. לתוכנית, נקודת הקצה מחזירה `409` כל עוד יש לחשבון מנוי, פעיל או שהתשלום עליו באיחור. שנו את התוכנית הזו עם `change-plan` במקום זאת. |
| `POST` | `/v1/billing/create-load-session` | פותחת את Stripe Checkout לטעינה של סכום שלם כקרדיטים: מקבלת `{ amountUsd, embedded?, returnPath? }` ומחזירה `{ data: { url, credits } }`. |
| `POST` | `/v1/billing/change-plan` | מעבירה מנוי פעיל לתוכנית אחרת: מקבלת `{ newPriceId }` ומחזירה `{ data: { subscriptionId, tier } }`. ראו את הסעיף [שינוי תוכנית](#change-plan). |
| `POST` | `/v1/billing/manage-subscription` | יוצרת קישור ל-Stripe Customer Portal: מקבלת `{ returnPath? }` ומחזירה `{ data: { url } }`. לפני הרכישה הראשונה היא מחזירה `404`. |
| `GET` | `/v1/billing/auto-recharge` | ההגדרה של הטעינה האוטומטית: `{ data: { enabled, thresholdCredits, amountUsd, failureCount, lastAttemptAt, hasSavedCard } }`. |
| `PUT` | `/v1/billing/auto-recharge` | משנה את ההגדרה: `{ enabled, thresholdCredits?, amountUsd? }`. כדי להפעיל את הטעינה האוטומטית צריך את שני המספרים. |
| `GET` | `/v1/billing/transactions` | היסטוריית הרכישות, מהחדש לישן, 50 הרכישות האחרונות: `{ data: [{ id, stripe_transaction_id, type, amount_usd, credits_granted, tier, created_at, receipt_url }] }`. השדה `type` הוא `subscription`, `topup` או `refund`, וב-`refund` הערך של `credits_granted` שלילי. |
| `GET` | `/v1/billing/payment-method` | פרטי התשלום ששמורים ב-Stripe: `{ data: { card, billingDetails } }`. השדה `card` הוא `{ brand, last4, expMonth, expYear }` או `null`, והשדה `billingDetails` הוא `{ name, email, country }` או `null`. חשבון שעוד לא קנה דבר מקבל את שניהם כ-`null`, אף פעם לא שגיאה. |
| `GET` | `/v1/billing/invoices` | כל תשלום כמסמך, מהחדש לישן, 100 האחרונים מכל מקור. פירוט בהמשך. |

כל מסמך של `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](https://app.nodaro.ai/billing), או ראו את הסעיף [רכישה וניהול החיוב](#buy-and-manage-billing).

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

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

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

| שדה | משמעות |
| --- | --- |
| `plan` | התוכנית שלכם, כמחרוזת. הערך `unknown` הוא תשובה תקפה. |
| `balance` | היתרה שלכם, או `null`. |
| `dailyAllowance` | המכסה היומית שלכם, או `null`. |
| `unit` | היחידה של המספרים האלה. |

פריסה יכולה להוסיף שדות אופציונליים, ולקוח מציג רק את השדות שהוא מקבל: `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 [סביבות עבודה וארגונים](https://nodaro.ai/docs/developers/api/workspaces#budgets-and-usage).
- **פריסות עם חשבון חיוב אחד.** בפריסה שבה חשבון חיוב אחד משלם על כל המשתמשים, `GET /v1/user/credits` מוסיף `allowance: { granted, remaining, enforced }`, המכסה האישית שלכם בקרדיטים. הערך `enforced: false` פירושו שהמכסה מוצגת, אבל לא עוצרת הרצות. השדה `allowance` הוא `null` בחשבון החיוב עצמו או כשאי אפשר היה לקרוא את המכסה, ולכן לעולם אל תתייחסו ל-`null` כאל אפס. כשהפריסה אוכפת מכסות, הרצה שחורגת מהמכסה שלכם נדחית עם `402 user_allowance_exceeded`. חשבון החיוב מנהל את המאגר רק מהסשן שלו בדפדפן: קריאות יתרה שלו עם אסימון נדחות עם `403 payer_balance_jwt_only`. הוא יכול גם להפעיל טעינה אוטומטית למאגר וליצור מפתחות אינטגרציה לחיוב, לקריאה בלבד. ראו את הסעיף [הכלים של חשבון החיוב](https://nodaro.ai/docs/developers/external-wallet#billing-account) בדף ארנקים חיצוניים. לפריסות שמאשרות הוצאות דרך ארנק משלהן, ראו את הדף [ארנקים חיצוניים](https://nodaro.ai/docs/developers/external-wallet).

## שאלות נפוצות

### איך בודקים את יתרת הקרדיטים דרך ה-API?

כדי לבדוק את היתרה, שלחו בקשה לנתיב GET /v1/credits/balance. התשובה כוללת את הסכום הכולל, את קרדיטי המנוי ואת קרדיטי הטעינה, וגם את השדות tier ו-effectiveTier. ב-SDK, המתודה client.credits.balance() מחזירה רשומה מלאה יותר, שכוללת גם את ההוצאה היומית שלכם.

### מתי נגבים קרדיטים על יצירה דרך ה-API?

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

### האם אפשר להשתמש ב-API של Nodaro בלי מנוי?

כן. קנייה של חבילת קרדיטים כלשהי מפעילה תשלום לפי שימוש: כל המודלים פתוחים, אין סימן מים ואין תקרה יומית. קרדיטי תשלום לפי שימוש עובדים ב-API, ב-SDK, ב-CLI וב-MCP, ותקפים 12 חודשים.

### איך יודעים כמה הרצה תעלה לפני שמתחילים אותה?

הנתיב POST /v1/credits/model-costs מחזיר את המחיר בקרדיטים של עד 50 מזהי מודלים, הנתיב GET /v1/models מחזיר את רמות המחיר של כל מודל, והנתיב GET /v1/api/schema נותן אומדן לתהליך שלם. לרכיב יצירת וידאו Pro יש נתיב אומדן משלו.

### למה המחיר של LLM מוצג כ-≈N?

קריאת LLM מחויבת לפי הטוקנים שהיא השתמשה בהם בפועל, בתעריף של המודל. לפני הקריאה, Nodaro יכול רק להעריך קריאה טיפוסית במודל הזה. נקודת הקצה POST /v1/credits/model-costs מציינת מזהים כאלה בשדה estimates, ולכן הציגו אותם כ-≈N.

### האם אפשר להציג את התוכניות והמחירים של Nodaro בדף התמחור שלי?

כן. הנתיב GET /v1/billing/plans ציבורי, ולא צריך בשבילו אסימון. הוא מחזיר את התוכניות, את המחירים החודשיים והשנתיים שלהן, את הקרדיטים שכל תוכנית מעניקה ואת חבילות הקרדיטים. כדי לקנות, האדם צריך סשן מחובר משלו.

### האם נקודות הקצה של הקרדיטים עובדות בהתקנה באירוח עצמי?

לא. למהדורת Community ולמהדורת Business אין מערכת קרדיטים, ולכן נתיבי הקרדיטים מחזירים שם 404, והתיאורים של רכיבים ומודלים לא כוללים את המחירים שלהם בקרדיטים. אתם משלמים ישירות לספקי המודלים.