משימות

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

סטטוסים של משימה

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

מעטפת המשימה

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

השדה 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. קרדיטים: חינם.

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

wait_for_job

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

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

מה חוזר: מעטפת המשימה. כל קריאה מחזירה תשובה בתוך 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, שמציג אותן בתצוגת רשת.

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

מה חוזר: עמוד של משימות ו-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.

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

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

diagnose_run

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

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

מה חוזר: בהרצת תהליך, כל רכיב עם מזהה המשימה, הסוג והסטטוס שלו (nodes). זה הכלי היחיד שממפה את הרכיבים של הרצה למזהי המשימות שלהם. לכל רכיב שנכשל יש גם הודעת השגיאה שלו, המודל שלו, הקרדיטים שנגבו בפועל (creditsActual), סוג הכשל ורמז לתיקון. בהרצה שנכשלה ש-run_workflow יכול להמשיך יש גם resumeHint: הקריאה ל-run_workflow שממשיכה אותה מהנקודה שבה נעצרה. בהרצת אפליקציה שנכשלה יש במקומו את הקריאה ל-retry_app_run, כמו ב-get_app_run.

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

הרצה שהסתיימה מחזירה גם את השדה outcome, עם "succeeded" או "nothing_new", כמו ש-get_app_run עושה. לרכיב שההרצה דילגה עליו כי שום דבר לא הגיע לקלט שלו יש skipReason: "empty_input". בהרצה שלא מצאה שום דבר חדש אין כשל להסביר: שום דבר לא השתבש, פשוט לא היה על מה לעבוד.

כשמשימה נכשלת

1. בדקו את retryable. הערך false אומר שאותה בקשה תיכשל שוב אם לא ישנו בה דבר. זה קורה אחרי חסימה בגלל מדיניות התוכן, או כשהמודל דחה את השילוב של ההגדרות וקובצי המדיה בקלט. סירוב שהמודל לא נתן לו סיבה הוא retryable: true.
2. פעלו לפי suggestedProvider. כשמסנן בטיחות חסם את התוצאה ויש בקטלוג מודל חלופי, המשימה מציינת אותו. הריצו את אותו פרומפט ואותם ייחוסים במודל הזה, במקום לנחש מודל אחר.
3. שנו את הבקשה כשהמודל דחה אותה. שגיאה שאומרת שהמודל דחה את ההגדרות האלה פירושה שהאורך, יחס הגובה־רוחב, הרזולוציה או קובץ ייחוס לא מתאימים למודל הזה. שנו אותם, או בחרו מודל שפירוט היכולות שלו ב-list_models מאפשר את השילוב. שגיאה שאומרת שהמודל לא נתן סיבה יכולה להיות זמנית, או לנבוע מקובצי המדיה בקלט, כגון הגודל או הפורמט שלהם. הריצו את הבקשה שוב פעם אחת, ואם היא נכשלת שוב, החליפו את קובצי המדיה.
4. נסו שוב בכל שאר המקרים. שגיאה זמנית מהשירות של המודל נשארת retryable, גם כשהניסוח שלה נשמע כמו בעיה בתקינות הקלט.

פתרונות נוספים בדף פתרון בעיות.