ערכות

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

הנתיבים עובדים בכל מהדורה. הם מקבלים אסימון Bearer: אסימון API אישי (ndr_…), אסימון של אפליקציית OAuth או אסימון הסשן שלכם. אסימון של אפליקציית OAuth צריך את presets:read לקריאה ואת assets:write לכתיבה. קטלוג הערכות המובנות, GET /v1/node-presets/factory, לא דורש אסימון בכלל. אסימון אישי שמוגבל לתהליכים מסוימים לא יכול לגשת לערכות שלכם (403 forbidden), אבל קורא את הקטלוג כמו כל אחד. ראו את דף ה-API אימות ואת הדף ערכות, שמסביר מה ערכות עושות בעורך.

נקודות קצה

קריאת הערכות שלכם

הנתיב GET /v1/node-presets מחזיר { data: NodePreset[] }, מהחדש לישן. שלחו nodeType, למשל generate-image, כדי לקבל רק את הערכות של סוג רכיב אחד.

curl "https://app.nodaro.ai/v1/node-presets?nodeType=generate-image" \
  -H "Authorization: Bearer $NODARO_API_KEY"

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const presets = await client.presets.list('generate-image')
const cinematic = presets.find((p) => p.name === 'Cinematic Portrait')
const groups = await client.presets.listGroups('generate-image')

{
  "data": [
    {
      "id": "7e2c4a9f-1b3d-4f6a-8c5e-2d9b7a1f3c4e",
      "nodeType": "generate-image",
      "name": "Cinematic Portrait",
      "description": "Warm key light, shallow depth of field",
      "data": {
        "provider": "nano-banana-pro",
        "aspectRatio": "3:4",
        "resolution": "2K",
        "prompt": "cinematic portrait, warm key light, 85mm, shallow depth of field"
      },
      "groupId": null,
      "tags": ["portrait"],
      "sortOrder": 0,
      "minReferences": 0,
      "needsImage": false,
      "previewUrl": null,
      "createdAt": "2026-09-14T08:12:40Z",
      "updatedAt": "2026-09-14T08:12:40Z"
    }
  ]
}

תמונות שערכה עובדת מהן

הריצו ערכה שה-minReferences שלה גדול מ-0 כשמחוברות אליה תמונות ייחוס במספר הזה. בלעדיהן, הפרומפט של הערכה מתאר תמונה שלא קיימת. כשמשתמשים ב-presetId ב-POST /v1/generate-image, שלחו את התמונות ב-referenceImageUrls.

הערכות שבתיקיות גיליון ייחוס, שחקנים ועקביות, עריכה לפי שם, פרטיות פנים, עריכות, שינויי פורטרט ונושא מסוגנן צריכות תמונה אחת, והערכה רשת שחקנים מלאה צריכה שתיים. כך גם כל תבנית פרומפט שמשתמשת ב-{image:N}: מספר התמונות שלה הוא ה-N הגבוה ביותר. ערכה משלכם נספרת באותה דרך, לפי {image:N} ו-{image:N:label} בפרומפט שלה, בטקסט לפני ואחרי הפרומפט ובפרומפט השלילי.

קריאת קטלוג הערכות המובנות

הנתיב GET /v1/node-presets/factory?nodeType=generate-image מחזיר { data: [...] }, הערכות שמגיעות עם Nodaro לסוג הרכיב הזה. כל רשומה היא { id, name, description?, group?, groupKind?, section?, platforms?, data, minReferences, needsImage, previewUrl, previewSrcSet? }. מזהה של ערכה מובנית הוא מהצורה <node-type>/<name>, למשל generate-image/character-board או generate-video/orbit-360.

הקטלוג לא דורש אסימון. הוא זהה לכולם ואין בו נתוני משתמשים, ולכן אפליקציית לקוח יכולה להציג אותו למבקרים שלא התחברו, ולבקש מהם להתחבר רק כשהם יוצרים משהו. התגובה נשלחת עם Cache-Control: public, max-age=300, ואסימון לא תקין או שפג תוקפו שנשלח עם הבקשה לא נלקח בחשבון.

ה-previewUrl של ערכה מובנית הוא תמונת דוגמה בשרת שפניתם אליו, במבנה https://<host>/preset-previews/<nodeType>/<slug>.<hash>.webp, או null כל עוד אין לערכה תמונה. שם הקובץ משתנה בכל פעם שהתמונה משתנה, ולכן אפשר לשמור כתובת במטמון לתמיד.

# The presets that need a photo, and their example pictures. No token needed.
curl -s "https://app.nodaro.ai/v1/node-presets/factory?nodeType=generate-image" \
  | jq '.data[] | select(.needsImage) | {id, minReferences, previewUrl}'

const { data } = await client.presets.listFactory('generate-video')
const orbit = data.find((p) => p.id === 'generate-video/orbit-360')

איפה ערכה מובנית מתויקת

• group הוא התיקייה, כגון "YouTube", "Shorts · TikTok", "Social & Ads", "Business", "Life & Events", "Layout" או "Text".
• section, כשהוא קיים, הוא כותרת משנה בתוך התיקייה: נושא של יוטיוב, כגון "Finance & Crypto", או "Instagram feed".
• platforms, כשהוא קיים, הוא הפלטפורמות שבהן התוצאה מיועדת להתפרסם, מהמתאימה ביותר והלאה: ["TikTok", "Reels", "Shorts"], ["LinkedIn"] או ["Print", "Etsy"].

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

גדלי התמונות

לתמונה של ערכה מובנית יש שני גדלים: תמונת האריח ב-previewUrl, ברוחב 512 פיקסלים, ותמונה למסך מלא ברוחב של עד 1024 פיקסלים, תחת /preset-previews/1024/…. השדה previewSrcSet מציין את שתיהן עם הרוחב שלהן בפועל, מוכן ל-<img srcset>, כך שהדפדפן בוחר לפי המקום שיש לו:

<img src="{previewUrl}" srcset="{previewSrcSet}" sizes="(min-width: 900px) 80vw, 100vw" alt="{name}">

השדה previewSrcSet מופיע רק בערכה ששני הקבצים קיימים בה, ואף פעם לא בערכה משלכם. הרשימה ב-MCP משמיטה אותו.

החלת ערכה

כדי ליצור תמונה אחת עם ערכה, שלחו את המזהה שלה בתור presetId ב-POST /v1/generate-image. השרת מחיל את הערכה כמו שהעורך מחיל אותה על רכיב יצירת תמונה, והשדות שאתם שולחים גוברים עליה. ראו בדף ה-API החלת ערכה ברכיב יצירת תמונה.

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

const node = {
  id: 'portrait-1',
  type: 'generate-image',
  data: { ...cinematic.data, prompt: 'a lighthouse keeper at dawn' },
}

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

דרך MCP, מצאו ערכה עם הכלי list_node_presets וקבלו אותה עם הכלי get_node_preset, או שלחו את ה-presetId שלה ישירות לכלי יצירה כגון generate_image. השרת מחיל אז את הערכה, עוטף את הפרומפט שלכם בטקסט שהערכה מוסיפה לפניו ואחריו, ונותן לכל שדה שאתם שולחים במפורש לגבור עליה. ראו את מדריך כלי ה-MCP.

מועדפים

המועדפים מציגים את הערכות שסימנתם בכוכב בראש רשימת הערכות בעורך. מזהה במועדפים הוא מזהה של ערכה מובנית או ה-uuid של ערכה שלכם. באסימון של אפליקציית OAuth, הקריאה דורשת presets:read, והכתיבה דורשת assets:write.

מזהים של ערכות מובנות כוללים /, ולכן קודדו את presetId בקידוד URL במחרוזת השאילתה של DELETE:

curl -X DELETE "https://app.nodaro.ai/v1/node-presets/favorites?nodeType=generate-image&presetId=generate-image%2Fcharacter-board" \
  -H "Authorization: Bearer $NODARO_API_KEY"

יצירה ועריכה של ערכות

# Save a preset of your own, with one of your images as its picture
curl -s -X POST "https://app.nodaro.ai/v1/node-presets" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeType": "generate-image", "name": "Studio portrait", "data": {"provider": "gpt-image-2", "aspectRatio": "3:4", "prompt": "{image:1:person}, studio portrait, soft key light"}, "previewUrl": "https://cdn.nodaro.ai/images/<jobId>.png"}'

# Rename it, refusing if it changed since you read it
curl -s -X PATCH "https://app.nodaro.ai/v1/node-presets/<presetId>" \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Studio portrait (warm)", "expectedUpdatedAt": "<updatedAt>"}'

const preset = await client.presets.create({
  nodeType: 'generate-image',
  name: 'Studio portrait',
  data: { provider: 'gpt-image-2', aspectRatio: '3:4', prompt: '{image:1:person}, studio portrait' },
})
preset.needsImage // true: the prompt names {image:1}
await client.presets.addFavorite({ nodeType: 'generate-image', presetId: preset.id })

ב-CLI זמינות אותן פעולות כתיבה: הפקודות nodaro presets create, update, delete, import, export, favorites, favorite, unfavorite ו-nodaro presets groups עם create, update ו-delete. דרך MCP, הכלים save_node_preset, delete_node_preset ו-favorite_node_preset מנהלים ערכות.

כללים לכתיבה

• השמות ייחודיים לכל סוג רכיב, בלי הבדל בין אותיות גדולות לקטנות. נתיבי היצירה והעדכון מחזירים 409 name_taken. ייבוא שומר את שתי הערכות, ונותן לחדשה את השם … (imported 2) (יובא 2).
• הגודל של data הוא 64 KB לכל היותר. מפתחות של זמן ריצה, כגון תוצאות, מזהי משימות והתווית של הרכיב, מוסרים. על ערכה מיובאת שלא נשאר בה כלום מדלגים.
• groupId חייב להיות אחת מהתיקיות שלכם, אחרת הכתיבה נדחית עם 400 invalid_group.
• previewUrl חייב להיות אחת מהתמונות שלכם ב-Nodaro: העלאה או תוצאה של יצירה שהסתיימה, בפורמט png, jpg, webp, gif או avif. הקובץ חייב להיות קיים כבר, ולכן קבעו את השדה אחרי שהמשימה שיוצרת את התמונה הסתיימה. כל ערך אחר נדחה עם 400 validation_error, עם שם השדה, למשל presets[3].previewUrl בייבוא.
• הערכה שומרת עותק משלה של התמונה. ה-previewUrl שבתגובה הוא הכתובת של העותק, לא הכתובת ששלחתם, ולכן מחיקת המקור מהספרייה שלכם אף פעם לא שוברת את הערכה.
• expectedUpdatedAt גורם לכך שעדכון או מחיקה נדחים עם 409 conflict אם הערכה השתנתה מאז שקראתם אותה. קבלו אותה מחדש לפני שאתם מנסים שוב.
• ערכה או תיקייה שלא שייכות לכם, או מזהה שהוא לא uuid: התשובה היא 404 not_found.
• בכל חשבון יכולות להיות עד 5,000 ערכות, 500 תיקיות ו-2,000 מועדפים. מעבר לזה, יצירה, ייבוא או הוספה למועדפים נדחים עם 409 limit_reached ולא כותבים כלום. ייבוא שלא נכנס במלואו לא מייבא אף ערכה.
• סידור מחדש אחד מזיז עד 500 ערכות ו-100 תיקיות כשהוא נשלח ממפתח API או מאפליקציית OAuth. סידור גדול יותר נדחה עם 400 validation_error: שלחו את השאר בקריאה נוספת.
• פעולות הכתיבה מוגבלות ל-60 בדקה לכל סט של פרטי גישה, והייבואים ל-10 בדקה. מעבר לזה, הנתיב מחזיר 429 rate_limit_exceeded.

ערכות רינדור של Recast

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

ה-data של ערכת recast-render הוא תמונת מצב מלאה, עם מבנה קשיח:

{
  "schemaVersion": 1,
  "provider": "seedance-2-5",
  "resolution": "480p",
  "segmentSec": "max",
  "renderMethod": "extend",
  "anchorMode": "upfront",
  "citeStyle": "bare",
  "promptTiming": true,
  "textOnly": false,
  "interactive": true,
  "anchorGates": false,
  "musicGates": true,
  "musicSource": "generated"
}

כותבים אותן באותם נתיבים כמו כל ערכה. הן לא צריכות תמונות ואין להן תמונת דוגמה (minReferences: 0, previewUrl: null). שדות לא מוכרים וגרסאות סכמה לא מוכרות נדחים ביצירה, בעדכון ובייבוא. תמונת המצב אף פעם לא כוללת מדיית מקור, ייחוסים של הליהוק, פרומפטים, רצועות שהועלו, אישורי זכויות או תוצאות. החלת ערכה משנה את ההגדרות ומרעננת את אומדן המחיר; היא אף פעם לא מתחילה יצירה. בחירה במוזיקה המקורית או במוזיקה שהועלתה משתמשת במדיה של פרויקט היעד עצמו. לפני שאתם יוצרים, בדקו מה המודל שבחרתם יודע לעשות כרגע.

שגיאות