# משימות

> בדיקה, המתנה, סינון, דירוג ואבחון של משימות Nodaro דרך עוזר AI: מעטפת המשימה, הסטטוסים, משימות שממתינות לבדיקה, ניסיון חוזר ומודלים חלופיים.

Source: https://nodaro.ai/he/docs/mcp/tools/jobs

**כלי המשימות** מאפשרים לעוזר AI לבדוק את המצב של העבודה ש-Nodaro עושה בשבילו. כמעט כל כלי יצירה מתחיל משימה ומחזיר מיד את המזהה שלה. הכלים `get_job` ו-`wait_for_job` מדווחים מתי המשימה מסתיימת ואיפה התוצאה. הכלי `list_jobs` מחזיר רשימה מסוננת של המשימות האחרונות שלכם, `rate_job` מדרג תוצאה, ו-`diagnose_run` מסביר כשל. אף אחד מהם לא עולה קרדיטים.

## סטטוסים של משימה
| סטטוס | משמעות |
| --- | --- |
| `pending`, `queued`, `processing` | המשימה ממתינה או רצה. המשיכו לבדוק. |
| `pending_review` | התוצאה קיימת, אבל הפריסה מעכבת אותה עד שאדם יבדוק אותה. המשיכו לבדוק, ואף פעם אל תריצו את המשימה שוב. |
| `completed` | המשימה הסתיימה. התוצאה נמצאת ב-`outputUrl` וב-`outputData`. |
| `failed` | המשימה נכשלה. בדקו את `retryable` ואת `guidance`. |
| `cancelled` | המשימה בוטלה. |

משימה שממתינה לבדיקה מסתיימת בסטטוס `completed` כשהבודק מאשר אותה, או בסטטוס `failed` עם סיבה שקשורה למדיניות כשהבודק דוחה אותה. לקוח שבודק את מצב המשימה דרך ה-API של `tasks` ב-MCP רואה משימה שממתינה לבדיקה בסטטוס `input_required`: ההחלטה בידי הבודק, ולכן העוזר לא צריך לבקש מכם פרמטרים חדשים.

## מעטפת המשימה
הכלים `get_job` ו-`wait_for_job` מחזירים את אותה תוצאה מובנית: מעטפת המשימה. גם `get_asset` מחזיר אותה, בלי `input` ובלי שני נתוני הקרדיטים.

| שדה | מה יש בו |
| --- | --- |
| `jobId`, `jobType` | מזהה המשימה וסוג המשימה |
| `status`, `progress` | הסטטוס מהטבלה שלמעלה, וההתקדמות בזמן שהמשימה רצה |
| `assetKind` | `image`, `video` או `audio`; null בתוצאה של טקסט או של נתונים |
| `outputUrl` | התמונה, הסרטון או האודיו המוגמרים |
| `width`, `height` | גודל הפלט בפיקסלים, כשהמשימה תיעדה אותו. ראו בהמשך |
| `outputData` | פלט מובנה, כגון תמלול, יישור או ניתוח |
| `input` | מה נשלח למודל בפועל (ראו בהמשך), או null |
| `errorMessage` | השגיאה של משימה שנכשלה |
| `credits` | הקרדיטים ששוריינו למשימה עצמה כשהיא התקבלה. הסכום הזה אף פעם לא משתנה |
| `creditsCharged` | כמה המשימה עלתה אחרי החיוב הסופי של השריון שלה, כולל השלבים שהיא הריצה (`credits_charged` ב-`data` של המטען הטקסטואלי). ראו בהמשך |
| `creditsHeld`, `creditsReleased` | השריון של ההרצה יחד עם השריונות של השלבים שלה, ומה שחזר אחרי החיוב הסופי של כל השריונות בהרצה (`credits_held` ו-`credits_released`). ראו בהמשך |
| `createdAt`, `startedAt`, `completedAt` | חותמות זמן |
| `retryable`, `guidance`, `suggestedProvider` | במשימה שנכשלה, בוטלה או ממתינה לבדיקה: האם אותה בקשה יכולה להצליח, משפט שמסביר מה לעשות ומודל חלופי, כשיש כזה |
| `preview` | הערך הוא `true` ברינדור של רכיב [החלת רשימת עריכה](https://nodaro.ai/docs/nodes/video/apply-edl) שנעשה באיכות תצוגה מקדימה, כש-`outputData.quality` הוא `"proxy"`: החיתוך הפרטי ב-720p לבדיקה, לא הגרסה הסופית |

השדה `creditsCharged` יכול להיות נמוך מ-`credits`. הוא כולל את השלבים שהמשימה הריצה: במשימה שמריצה בשבילכם משימות אחרות, כגון הכנת הייחוס, המסכה והסרטון בהרצה של Nodaro Motion, הקרדיטים על כל שלב נגבים ברגע שהחיוב של השלב נסגר. כשהקרדיטים ששוריינו למשימה עצמה הוחזרו, הערך הוא `0` ועוד הקרדיטים שנגבו על שלבים שהחיוב שלהם כבר נסגר. למשל, בהרצה של Nodaro Motion שהקרדיטים שלה הוחזרו, אבל על שלבי הייחוס והמסכה שלה נגבו קרדיטים, הערכים הם `credit_status: "refunded"` ו-`creditsCharged: 165`. הערך הוא `null` כל עוד השריון של המשימה עצמה פתוח, כששום דבר בהרצה לא שוריין או כשלרגע אי אפשר היה לקרוא את השלבים שלה. ה-`null` הזה אומר ״לא ידוע״, ואף פעם לא סכום נמוך יותר.

השדה `creditsHeld` הוא השריון של ההרצה, כולל השריונות של השלבים. השדה `creditsReleased` הוא מה שחזר אחרי החיוב הסופי של כל השריונות בהרצה, ועד אז הערך שלו הוא `null`. למשל, משימה ששוריינו לה 888 קרדיטים, ובחיוב הסופי נגבו עליה 444, מחזירה `credits: 888`, `creditsCharged: 444`, `creditsHeld: 888` ו-`creditsReleased: 444`.

השדות `width` ו-`height` מופיעים במשימות תמונה שהסתיימו אחרי ש-Nodaro התחיל לתעד את הגודל, ובמשימות של הרכיבים שכבת תמונה, שכבה על וידאו, מסכת וידאו ושילוב לפי מסכה. בתמונה, הערכים האלה הם הגודל של `outputUrl` כפי שהוא שמור, אחרי החלת הסיבוב לפי EXIF. השתמשו בהם כדי לבחור יחס גובה־רוחב לשלב הבא. במשימה שיצרה כמה תמונות יש גם `outputData.images`, עם `{ url, width, height }` לכל תמונה.

השדה `input` הוא חלק בטוח מהבקשה, שמספיק כדי לבדוק מה המודל קיבל. שום דבר מחוץ לרשימה הזו לא נכלל בו:

- השדה `prompt`, הפרומפט בגרסתו הסופית, אחרי שהבוררים, הנושאים והייחוסים שולבו בו, והשדה `userPrompt`, המילים שלכם.
- השדה `negativePrompt`, ומזהי הבוררים `direction` ו-`subject`.
- השדות `provider`, `model`, `duration`, `resolution` ו-`aspectRatio`.
- השדות `imageUrl` ו-`endFrameUrl`, והכתובות של תמונות הייחוס, סרטוני הייחוס ואודיו הייחוס.
- השדה `type` של המשימה.

## `get_job`
מחזיר משימה אחת שלכם לפי המזהה שלה, כמעטפת משימה. השתמשו בו כדי לבדוק משימה כל 5–10 שניות עד שהיא מסתיימת.

**הרשאה:** `jobs:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `job_id` | string | **נדרש.** המזהה שכלי יצירה החזיר. |

**מה חוזר:** מעטפת המשימה.

## `wait_for_job`
ממתין עד שמשימה שלכם מסתיימת, ואז מחזיר את מעטפת המשימה. השתמשו בו במקום בלולאה צפופה של קריאות ל-`get_job`.

**הרשאה:** `jobs:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `job_id` | string | **נדרש.** המשימה שממתינים לה. |
| `timeout_s` | integer | כמה שניות להמתין, עד 45. ברירת המחדל: `45`. הכלי מקבל ערך עד 120, אבל גם אז ממתין 45 שניות. |

**מה חוזר:** מעטפת המשימה. כל קריאה מחזירה תשובה בתוך 45 שניות, כי לקוחות MCP מסיימים קריאה לכלי לפי שעון משלהם, לרוב אחרי 60 שניות. אם המשימה עדיין רצה אז, הסטטוס הוא `timeout`, עם `progress`, `jobType`, `createdAt` ו-`startedAt` של המשימה. זו לא שגיאה: קראו שוב ל-`wait_for_job` עם אותו `job_id`. ההמתנה ממשיכה מהנקודה שבה נעצרה, והמשימה לא מושפעת, ולכן אף פעם אל תריצו את היצירה שוב. יצירת סרטון יכולה לקחת 2–10 דקות, ולכן צפו לכמה קריאות, או בדקו את הסטטוס עם `get_job` כל 5–10 שניות. על משימה שממתינה לבדיקה, הכלי עונה מיד `pending_review`.

## `list_jobs`
מחזיר רשימה של המשימות האחרונות שלכם כנתונים מובנים: סטטוס, סוג, כתובת הפלט, שגיאה, קרדיטים וחותמות זמן. השתמשו בו לשאלות כגון ״כמה יצירות נכשלו אתמול״. כשרוצים לראות את התוצאות, השתמשו ב-[`browse_gallery`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#browse_gallery), שמציג אותן בתצוגת רשת.

**הרשאה:** `jobs:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `kinds` | array | סוגי המדיה שייכללו: כל שילוב של `image`, `video` ו-`audio`. ברירת המחדל: `["image", "video"]`, ולכן אודיו לא נכלל אלא אם מבקשים אותו. |
| `status` | string או array | רק במשימות שלכם. סטטוס אחד, או רשימה של סטטוסים: `pending`, `queued`, `processing`, `pending_review`, `completed`, `failed`, `cancelled`. |
| `types` | array | רק במשימות שלכם. בין 1 ל-20 סוגי משימות, כלומר הנתיב שיצר את המשימה, למשל `generate-image` או `llm-structured`. |
| `sources` | array | רק במשימות שלכם. ממשק אחד או יותר שממנו נוצרה המשימה: `mcp` (לקוח MCP כגון Claude או ChatGPT), `web`, `cli`, `sdk`, `extension`, `app`, `api` או `internal`. |
| `favorited` | boolean | רק במשימות שלכם. הערך `true` מחזיר רק את המשימות שסימנתם כמועדפות, והערך `false` את כל השאר. |
| `rating` | string | רק במשימות שלכם. `good`, `bad`, `rated` (דירוג כלשהו) או `unrated`. |
| `project_id` | string | רק במשימות שלכם. המשימות שנמצאות עכשיו בסשן של הפרויקט הזה, כל אחת פעם אחת. הערך `none` מחזיר את המשימות שנמצאות בסשן שלא שייך לאף פרויקט. |
| `in_session` | boolean | רק במשימות שלכם. הערך `false` מחזיר את המשימות שלא נמצאות באף סשן, שהאפליקציה מציגה תחת **כללי**. הערך `true` מחזיר את המשימות שנמצאות בסשן אחד לפחות. |
| `with_sessions` | boolean | רק במשימות שלכם. בכל משימה מופיעה גם רשימת הסשנים שהיא נמצאת בהם, עם המזהה, הכותרת ומזהה הפרויקט של כל סשן. |
| `scope` | string | `mine` (ברירת המחדל) למשימות שלכם, או `public` לתוצאות ציבוריות אחרונות של משתמשים אחרים. |
| `limit` | integer | מ-1 עד 200. ברירת המחדל: `50`. |
| `cursor` | string | הערך `next_cursor` מהעמוד הקודם. |

**מה חוזר:** עמוד של משימות ו-`next_cursor` לעמוד הבא.

בהיקף הציבורי, הרשימה כוללת את מה שהגלריה הציבורית מציגה, עם אותו סינון תוכן כמו ב-`browse_gallery`, ואף פעם לא כוללת את המזהה של יוצר אחר. בשני ההיקפים, בעמוד יכולות להיות פחות משימות מ-`limit`, ועדיין יהיה בו `next_cursor`. המשיכו לבקש עם `next_cursor` עד שהערך שלו הוא `null`.

במשימות שלכם, המסננים עובדים כמו ב-`GET /v1/jobs` ומשתלבים עם `AND`. הפרמטר `types` מבטל את ברירת המחדל של `kinds`, ולכן גם משימה בלי מדיה, כגון טיוטת `llm-structured`, מופיעה ברשימה. העבירו גם את `kinds` כדי לקבל רק מדיה. עם `scope: "public"`, הכלי דוחה את `types`, `sources`, `favorited`, `rating`, `project_id`, `in_session` ו-`with_sessions`. משימה שנמחקה אף פעם לא מופיעה ברשימה: היא נמצאת ב-[`list_trash`](https://nodaro.ai/docs/mcp/tools/projects-and-workflows#list_trash).

בכל אחת מהמשימות שלכם יש `favorited` (`true` או `false`) ו-`rating` (`"good"`, `"bad"` או `null`). כשלרגע אי אפשר לקרוא אותם, שני השדות לא מופיעים, וזה אומר ״לא ידוע״, לא `false`. בשורות של ההיקף הציבורי אין אף אחד מהם.

בכל אחת מהמשימות שלכם יש `credits`, הסכום ששוריין למשימה עצמה כשהיא התקבלה, שאף פעם לא משתנה, ו-`credits_charged`, כמה היא עלתה אחרי החיוב הסופי של השריון, כולל השלבים שהיא הריצה. החיוב הסופי של משימה יכול להיות נמוך מהשריון שלה, והשאר חוזר ליתרה שלכם. כשהקרדיטים ששוריינו להרצה עצמה הוחזרו, `credits_charged` הוא `0` ועוד הקרדיטים שנגבו על שלבים שהחיוב שלהם כבר נסגר. הערך הוא `null` כל עוד השריון של המשימה עצמה פתוח, כששום דבר בהרצה לא שוריין או כשלרגע אי אפשר היה לקרוא את השלבים שלה. השדה `credits_held` הוא השריון של ההרצה יחד עם השריונות של השלבים שלה, ו-`credits_released` הוא מה שחזר אחרי החיוב הסופי של כל השריונות בהרצה (`null` עד אז). כדי לחשב כמה משימות עלו, סכמו את `credits_charged`, לא את `credits`. בשורות של ההיקף הציבורי אין אף אחד משלושת השדות האלה.

המשימות שלכם כוללות גם את הרינדורים של רכיב החלת רשימת עריכה, לפי סוג הפלט שלהם: הערך `video` לחיתוך והערך `audio` למיקס. רינדור של תצוגה מקדימה כולל `preview: true`. ההיקף הציבורי אף פעם לא מחזיר רינדור של רכיב החלת רשימת עריכה.

## `rate_job`
נותן למשימה שלכם את הדירוג `good` או `bad`, או מוחק את הדירוג שלה. למשימה יש דירוג אחד, ורק הבעלים שלה יכול לדרג אותה. על משימה של אדם אחר, או על מזהה שהוא לא של משימה, הכלי עונה "not found" (לא נמצא).

**הרשאה:** `assets:write`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `job_id` | string | **נדרש.** אחת מהמשימות שלכם. |
| `rating` | string או null | **נדרש.** `good` או `bad`, או `null` כדי למחוק את הדירוג. |

**מה חוזר:** `{ data: { jobId, rating } }`. הדירוג מופיע ב-`list_jobs`, שיכול גם לסנן לפיו, וב-`GET /v1/jobs`.

## `diagnose_run`
מסביר למה הרצת תהליך או משימה בודדת נכשלו. אפשר להעביר כל אחד משני המזהים: הכלי מחפש קודם הרצת תהליך, ואם אין כזו, משימה.

**הרשאה:** `jobs:read`. **קרדיטים:** חינם.

| פרמטר | סוג | הערות |
| --- | --- | --- |
| `id` | string | **נדרש.** מזהה של הרצת תהליך או מזהה משימה. |

**מה חוזר:** בהרצת תהליך, כל רכיב עם מזהה המשימה, הסוג והסטטוס שלו (`nodes`). זה הכלי היחיד שממפה את הרכיבים של הרצה למזהי המשימות שלהם. לכל רכיב שנכשל יש גם הודעת השגיאה שלו, המודל שלו, הקרדיטים שנגבו בפועל (`creditsActual`), סוג הכשל ורמז לתיקון. בהרצה שנכשלה ש-`run_workflow` יכול להמשיך יש גם `resumeHint`: הקריאה ל-[`run_workflow`](https://nodaro.ai/docs/mcp/tools/projects-and-workflows#continue-a-failed-run) שממשיכה אותה מהנקודה שבה נעצרה. בהרצת אפליקציה שנכשלה יש במקומו את הקריאה ל-[`retry_app_run`](https://nodaro.ai/docs/mcp/tools/apps-and-components#retry_app_run), כמו ב-`get_app_run`.

| סוג הכשל | משמעות |
| --- | --- |
| `content_policy` | מסנן בטיחות חסם את הפרומפט או את התוצאה |
| `validation` | ההגדרות או הקלט לא התקבלו |
| `rate_limited` | הבקשה נתקלה במגבלת קצב |
| `timeout` | ההרצה נמשכה זמן רב מדי |
| `post_processing` | המודל מסר תוצאה, אבל שלב שאחריו נכשל |
| `provider_error` | השירות של המודל החזיר שגיאה |
| `unknown` | השגיאה לא מתאימה לאף אחד מהסוגים שלמעלה |

סוג הכשל הוא הערכה לפי טקסט השגיאה, ולכן התייחסו אליו כהכוונה בלבד. הקרדיטים המשוריינים מוחזרים אוטומטית בכל הסוגים חוץ מ-`post_processing`, כי במקרה הזה המודל כבר מסר את העבודה שלו.

הרצה שהסתיימה מחזירה גם את השדה `outcome`, עם `"succeeded"` או `"nothing_new"`, כמו ש-[`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run) עושה. לרכיב שההרצה דילגה עליו כי שום דבר לא הגיע לקלט שלו יש `skipReason: "empty_input"`. בהרצה שלא מצאה שום דבר חדש אין כשל להסביר: שום דבר לא השתבש, פשוט לא היה על מה לעבוד.

## כשמשימה נכשלת
1. **בדקו את `retryable`.** הערך `false` אומר שאותה בקשה תיכשל שוב אם לא ישנו בה דבר. זה קורה אחרי חסימה בגלל מדיניות התוכן, או כשהמודל דחה את השילוב של ההגדרות וקובצי המדיה בקלט. סירוב שהמודל לא נתן לו סיבה הוא `retryable: true`.
2. **פעלו לפי `suggestedProvider`.** כשמסנן בטיחות חסם את התוצאה ויש בקטלוג מודל חלופי, המשימה מציינת אותו. הריצו את אותו פרומפט ואותם ייחוסים במודל הזה, במקום לנחש מודל אחר.
3. **שנו את הבקשה כשהמודל דחה אותה.** שגיאה שאומרת שהמודל דחה את ההגדרות האלה פירושה שהאורך, יחס הגובה־רוחב, הרזולוציה או קובץ ייחוס לא מתאימים למודל הזה. שנו אותם, או בחרו מודל שפירוט היכולות שלו ב-[`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) מאפשר את השילוב. שגיאה שאומרת שהמודל לא נתן סיבה יכולה להיות זמנית, או לנבוע מקובצי המדיה בקלט, כגון הגודל או הפורמט שלהם. הריצו את הבקשה שוב פעם אחת, ואם היא נכשלת שוב, החליפו את קובצי המדיה.
4. **נסו שוב בכל שאר המקרים.** שגיאה זמנית מהשירות של המודל נשארת `retryable`, גם כשהניסוח שלה נשמע כמו בעיה בתקינות הקלט.

פתרונות נוספים בדף [פתרון בעיות](https://nodaro.ai/docs/mcp/troubleshooting).

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

### באיזו תדירות עוזר AI צריך לבדוק את הסטטוס של משימת Nodaro?

עוזר AI צריך לבדוק משימה כל 5–10 שניות עם הכלי get_job, או להשתמש בכלי wait_for_job, שממתין עד 45 שניות בכל קריאה. תמונה מסתיימת בדרך כלל בתוך דקה, וסרטון בתוך 2–10 דקות.

### מה המשמעות של pending_review?

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

### מה העוזר צריך לעשות כשמשימה נכשלת?

כשמשימה נכשלת, העוזר צריך לקרוא את השדות retryable ו-guidance שלה. כש-retryable הוא false, הוא צריך לשנות את ההגדרות או את הקלט לפני ניסיון נוסף. כשבמשימה מופיע השדה suggestedProvider, הוא צריך להריץ את אותו פרומפט ואותם ייחוסים במודל שהשדה מציין.

### האם כלי המשימות עולים קרדיטים?

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