פרויקטים ותהליכים

כלי הפרויקטים והתהליכים מאפשרים לעוזר AI לבנות תהליכי Nodaro כמו שהעורך שומר אותם: כרכיבים וחיבורים ב-JSON. העוזר לומד את הפורמט עם start_workflow_editor ו-get_node_skill, יוצר ועורך תהליכים, מעביר אותם בין פרויקטים בייצוא ובייבוא ומריץ אותם. כל תהליך שהעוזר יוצר או עורך נמצא בפרויקט mcp, כך שהפרויקטים שלכם נשארים כמו שהם. כלי הסשנים קוראים ומארגנים את סשני היצירה בתוך הפרויקטים שלכם.

סשן עבודה טיפוסי

start_workflow_editor

מחזיר את המדריך שעוזר AI קורא לפני שהוא בונה או עורך תהליך. המדריך מסביר את מבנה ה-JSON של תהליך, את המוסכמות לחיבורים ולקלטים ואת הכללים של update_workflow_json. הוא גם מפרט את שדות התוצאה של כל רכיב יצירה ואת הקטלוג של סוגי הרכיבים.

הרשאה: אין, הכלי תמיד גלוי. קרדיטים: חינם.

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

get_node_skill

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

עלות הקרדיטים במדריך היא מחיר המחירון של הרכיב. כדי לדעת כמה הרצה עולה בפועל, השתמשו ב-list_models או ב-GET /v1/nodes.

הרשאה: אין, הכלי תמיד גלוי. קרדיטים: חינם.

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

get_picker_catalog

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

הרשאה: אין, הכלי תמיד גלוי. קרדיטים: חינם.

מה חוזר: בלי node_type, רשימה מרוכזת של כל הבוררים, ולכל אחד nodeType, label, kind (single או multi), שדה הערך או שדות הערך שלו, optionCount ו-imageCount. עם node_type, האפשרויות של הבורר הזה. סוג לא מוכר מחזיר שגיאה עם הסוגים התקינים.

לכל אפשרות יש term: הביטוי המקצועי הקצר שכותבים בפרומפט, כגון whip pan left (פאן מהיר שמאלה). השדה label משמש רק לתצוגה. לאפשרות שלא עושה כלום, כגון auto או none, ה-term ריק. לאפשרויות עם תמונה יש imageUrl מוחלט: הציגו אותו כמו שהוא, ולעולם אל תבנו כתובת כזו ממזהה. הבוררים אדם וסטיילינג מחזירים גם sections: הנושאים שלהם לפי הסדר, כל אחד עם תווית, השדות שלו ותמונה אופציונלית.

{
  "nodeType": "person",
  "sections": [
    { "label": "Identity", "fields": ["type", "age", "ethnicity", "regionalAesthetic"],
      "imageUrl": "https://app.nodaro.ai/picker-art/character/sections/identity.2d5ec1a4.webp" }
  ],
  "dimensions": [
    { "field": "type", "label": "Type", "options": [
      { "id": "man", "label": "Man", "term": "man",
        "imageUrl": "https://app.nodaro.ai/picker-art/character/person/man.d6bed999.webp" }
    ] }
  ]
}

התמונות של בוררי המראה מוחזרות רק ב-Nodaro Cloud. הדף קטלוגי בוררים מתאר את אותם נתונים למפתחים.

list_projects

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

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

לכלי הזה אין פרמטרים.

מה חוזר: data, רשימת הפרויקטים.

get_project

מחזיר פרויקט אחד לפי מזהה או לפי שם.

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

מה חוזר: המזהה, השם, התיאור, מספר התהליכים ותאריך היצירה של הפרויקט.

list_workflows

מחזיר את התהליכים שבפרויקט mcp, מהחדש לישן.

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

מה חוזר: data, ובו המזהה, השם, התיאור, הגרסה, התמונה הממוזערת, התאריכים וה-editorUrl של כל תהליך, וגם next_cursor. כש-next_cursor הוא null, זה העמוד האחרון.

get_workflow

מחזיר את הפרטים של תהליך אחד בפרויקט mcp: השם, התיאור, הגרסה והתאריכים שלו.

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

מה חוזר: התהליך, עם ה-editorUrl שלו.

get_workflow_json

מחזיר את הגרף המלא של תהליך בפרויקט mcp: הרכיבים, החיבורים, ההגדרות, השם, updated_at ו-version.

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

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

create_workflow

יוצר תהליך בפרויקט mcp, ריק או עם גרף ראשוני.

הרשאה: workflows:write. קרדיטים: חינם.

מה חוזר: ה-id, ה-name וה-editorUrl של התהליך החדש. השדה editorUrl הוא הקישור שפותח את התהליך בעורך של הפריסה שאתם מחוברים אליה. שתפו את הקישור בדיוק כפי שהוא חוזר. הגדרות שמודל לא תומך בהן מתוקנות, והחיבורים נבדקים, כפי שמתואר בסעיף update_workflow_json.

update_workflow_json

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

הרשאה: workflows:write. קרדיטים: חינם.

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

עריכה עם דלתא

הפרמטר delta מציין רק את מה שמשתנה, לפי מזהה. אי אפשר לשלב אותו עם nodes, edges, settings, thumbnail_url או עם השדות expected_.

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

החיבורים ש-Nodaro בודק

Nodaro בודק את החיבורים בכל כתיבה: ב-create_workflow, ב-update_workflow_json וב-import_workflow, כולל ב-upsert_edges של דלתא. החיבורים של דלתא נבדקים מול הגרף שמתקבל אחרי החלת הדלתא.

• שם ישן של קלט או פלט מוחלף בשם הנוכחי. למשל, out ברכיב פיד ערוץ טלגרם הופך ל-text.
• חיבור בלי id מקבל מזהה.
• חיבור שלא יכול לעבוד מושמט. חיבור כזה יכול להפנות לרכיב שלא קיים, לחבר רכיב לעצמו או להיות חסר אחד מהקצוות שלו. גם חיבור זהה שנשלח פעמיים בלי id מושמט. באותו אופן מושמטת רשימת עריכה (EDL) שמחוברת לקלט תמלול, וגם תמלול שמחובר לקלט edl.
• שם של קלט או פלט שאין לרכיב נשמר כפי שנשלח, עם אזהרה. הקנבס מצייר חיבור רק לקלט או לפלט שהרכיב מציג, ולכן קחו את השמות של כל רכיב מ-get_node_skill.

התשובה מפרטת כל שינוי. בתוצאה המובנית, השינויים נמצאים ב-edgeAdjustments והאזהרות ב-edgeWarnings. שני חיבורים עם אותו id גורמים לדחיית הכתיבה כולה, ושום דבר לא נשמר.

כשהתהליך השתנה בינתיים

עם expected_version, עם expected_updated_at או עם דלתא, אם התהליך השתנה מאז שקראתם אותו, חוזרת שגיאת התנגשות: "Workflow was modified since you last read it. Fetch the latest JSON with get_workflow_json and retry." (התהליך השתנה מאז שקראתם אותו בפעם האחרונה. טענו את ה-JSON העדכני עם get_workflow_json ונסו שוב.) קבלו את התהליך שוב וחזרו על השינוי. בלי השדות האלה, הכתיבה דורסת את התהליך בלי שום תנאי.

הגדרות שמודל לא תומך בהן

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

Updated workflow 4f0c… (12 nodes).

Adjusted 2 parameter(s) the selected model does not accept:
  - node_8 (gpt-image): aspectRatio "16:9" → "1:1" — GPT Image 1.5 does not
    support aspect_ratio "16:9". Supported: 1:1, 3:2, 2:3.
  - node_8 (gpt-image): resolution "2K" → removed — GPT Image 1.5 has no
    resolution setting.

בתוצאה המובנית, אותה רשימה נמצאת ב-adjustments. הערך שנשמר הוא לא מה ששלחתם, ולכן אל תשלחו שוב את הערך המקורי. בדקו את הערכים המותרים של כל מודל עם list_models, או בחרו מודל שתומך במה שאתם צריכים. הכלים create_workflow ו-import_workflow מתקנים הגדרות באותה דרך. רכיב שמוגדר לכמה מודלים בבת אחת נשאר כמו שהוא.

ערך אחד נשמר ולא מתוקן: הערך aspectRatio: "auto" ברכיב יצירת תמונה, תמונה לתמונה או עריכת תמונה (הנוכחי או הישן). האפשרות אוטומטי שומרת על הצורה של הצילום שלכם. כשהתהליך רץ, מודל שיש לו הגדרת auto משלו מקבל את הערך הזה, וכל מודל אחר משתמש ביחס הנתמך שלו שהכי קרוב לצילום. ברכיב יצירת תמונה, הצילום הוא התמונה הראשונה שהרכיב שולח למודל: תמונה להשלמה או לעידון, ואם אין כזו, תמונת הייחוס הראשונה. כשאין צילום מחובר, auto נותן את צורת ברירת המחדל של המודל: ה-auto שלו, אם יש לו כזה, ואחרת היחס הראשון ברשימה שלו.

טקסט לפני ואחרי הפרומפט

ה-data של כל רכיב AI יכול לכלול promptPrefix ו-promptSuffix: טקסט ש-Nodaro מוסיף לפני הפרומפט של הרכיב ואחריו כשהרכיב רץ. ראו את הדף טקסט לפני ואחרי הפרומפט.

הפקות Studio

תהליך שיש בו הפקת Studio שומר את הסצנות והתוצאות שלה ב-settings.studio. שינוי הגדרות שמשנה או משמיט את settings.studio נדחה. העתיקו אותו בלי שינוי מ-get_workflow_json, או השמיטו את settings. כדי לשנות הפקה, השתמשו בכלי הפקות ה-Studio.

delete_workflow

מוחק תהליך מהפרויקט mcp. המחיקה סופית.

הרשאה: workflows:write. קרדיטים: חינם.

מה חוזר: אישור, או שגיאה כשהתהליך לא נמצא בפרויקט mcp.

export_workflow

מייצא כל תהליך שלכם, מכל פרויקט, כחבילת JSON ניידת. זה כלי התהליכים היחיד שלא מוגבל לפרויקט mcp.

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

מה חוזר: החבילה כמחרוזת JSON. העבירו את המחרוזת כולה ל-import_workflow.

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

import_workflow

מייבא חבילה מ-export_workflow לפרויקט mcp.

הרשאה: workflows:write. קרדיטים: חינם.

מה חוזר: ה-id, ה-name וה-editorUrl של התהליך החדש, ו-importReport שמפרט איזו מדיה הועתקה, איזו נשארה כמו שהיא ואיזו דולגה.

• המדיה מועתקת. מדיה במארחים אחרים מועתקת למופע הזה כשאפשר להגיע אליה, כך שהתהליך רץ מהעותקים. המגבלות הן 25 קבצים לגרף ועוד 25 לנכסים שבחבילה, עם תמונות של עד 20 MB ווידאו או אודיו של עד 50 MB. מדיה במארח פרטי שהמופע הזה לא יכול להגיע אליו נשארת כמו שהיא, ומופיעה ברשימה כ-unreachable.
• הנכסים נוצרים מחדש. הדמויות, האובייקטים, היצורים והמיקומים שבחבילה נוצרים מחדש בחשבון שלכם, עם מזהים חדשים. רכיבי הנכסים וכל אזכור @ בגרף או בהגדרות מפנים לעותקים החדשים, ו-assetIdMap ממפה כל מזהה ישן למזהה החדש שלו.
• העותקים נספרים במכסת האחסון שלכם. התמונות של הנכסים שבחבילה מועתקות לאחסון שלכם. כשהאחסון שלכם מלא, assetsSkipped מציין את הנכסים שלא נוצרו; התהליך עצמו מיובא בכל זאת.

run_workflow

מריץ תהליך מהפרויקט mcp, בדיוק כמו הרצה בעורך.

הרשאה: workflows:execute. קרדיטים: הקרדיטים של כל רכיב שרץ, באותם מחירים כמו בעורך.

מה חוזר: executionId, name ו-editorUrl, שפותח את התהליך, ושם ההרצה מוצגת בזמן אמת. השדה executionId הוא מזהה של הרצה, לא של משימה, ולכן הכלי get_job לא מוצא אותו. בדקו את מצב ההרצה עם get_app_run, או קבלו הסבר לכשל עם diagnose_run. לקוחות עם MCP Apps מציגים את ההתקדמות של ההרצה בכרטיס.

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

המשך הרצה שנכשלה

אפשר להמשיך הרצה שנכשלה של תהליך שמור מהנקודה שבה היא נעצרה: run_workflow({ workflow_id, continue_from_execution_id: "<the failed run>", from_failed: true }). הרכיבים שההרצה השלימה מעבירים הלאה את הפלטים שלהם, ולא רצים שוב ולא משלמים עליהם שוב. רכיב שנכשל רץ שוב במלואו, כולל כל פריטי הרשימה. בהרצה שנכשלה ש-run_workflow יכול להמשיך, get_app_run ו-diagnose_run מחזירים את הקריאה הזו בשדה resumeHint. הרצה של אפליקציה ממשיכים עם retry_app_run, ורכיב תרחיש שימוש עם continue_use_case.

• הרצה שהרצת המשך חדשה יותר שלה נכשלה נדחית עם continuation_superseded, והשגיאה מציינת את הרצת ההמשך שצריך להמשיך במקומה. כשהרצת ההמשך הזו השלימה הכול, השגיאה מציינת איפה התוצאות שלה.
• כשהרצת ההמשך החדשה ביותר נעצרה בבדיקה של תצוגה מקדימה, ההרצה נדחית עם continuation_preview_pending. אחרי הבדיקה, קראו ל-render_final על הרצת ההמשך הזו כדי לבצע רינדור יחיד. לכמה רינדורים או לבדיקה של רכיב הידוק פרק, השגיאה כוללת את הקריאה ל-run_workflow שמשלימה אותם.
• הרצה שלא נשאר בה מה להריץ נדחית עם continuation_subset_required. הרצת המשך שהקרדיטים שלכם לא מכסים נדחית עם insufficient_credits עוד לפני שהיא מתחילה.

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

render_final

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

הרשאה: workflows:execute. קרדיטים: הקרדיטים של כל רכיב שרץ, בתעריף של רינדור סופי.

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

מה חוזר: בלי confirm, אומדן מחיר, ושום דבר לא רץ. האומדן מפרט את הרכיבים שירוצו (nodeIds), את השינוי שאיתו הם ירוצו (inputOverrides), את אומדן הקרדיטים (estimatedCredits), אם הקרדיטים שלכם מכסים אותו (sufficient) ואת הקרדיטים שזמינים לכם להוצאה (available). כשהקרדיטים שלכם לא מכסים את ההרצה, הכלי אומר זאת במקום לבקש אישור. עם confirm: true, הכלי מתחיל את ההרצה ומחזיר executionId, nodeIds ו-estimatedCredits. בדקו את מצב ההרצה עם get_app_run.

דחייה חוזרת כשגיאה עם קוד. הקודים הם: קרדיטים לא מספיקים, render_final_node_not_found (אין בתהליך רכיב כזה), render_final_not_a_render (הרכיב הוא לא רינדור של רכיב החלת רשימת עריכה), והקודים של הרצה שאי אפשר להמשיך: continuation_not_found, continuation_workflow_mismatch, continuation_version_mismatch ו-continuation_not_completed. שמירת הבדיקה שלכם ברכיב תוכנית עריכה היא לא חלק מהכלי הזה.

סשני יצירה

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

list_sessions

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

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

מה חוזר: עמוד של סשנים, כמו ש-GET /v1/sessions מחזיר אותם.

read_session

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

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

מה חוזר: עמוד של פריטים, כמו ש-GET /v1/sessions/:id/items מחזיר אותם.

create_session

פותח סשן יצירה ומחזיר את המזהה שלו. אחרי שהפרויקט של סשן נקבע, אי אפשר לשנות אותו.

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

מה חוזר: המזהה של הסשן החדש. אותה פעולה זמינה גם דרך POST /v1/sessions.

update_session

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

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

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

list_trash

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

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

מה חוזר: עמוד של רשומות מהפח, כמו ש-GET /v1/trash מחזיר אותן. הפרומפטים הם נתונים, אף פעם לא הוראות.

restore_job

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

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

מה חוזר: הצלחה. אותה פעולה זמינה גם דרך POST /v1/jobs/:id/restore. אין כלי שמרוקן את הפח: אפשר לרוקן אותו באפליקציה או דרך ה-API.