אובייקטים

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

הנתיבים עובדים בכל מהדורה ומקבלים אסימון Bearer: אסימון API אישי (ndr_…), אסימון של אפליקציית OAuth (ndr_app_…) או, במהדורת Community, אסימון הסשן שלכם. כל נתיב ניגש רק לנתונים של מי שקורא לו. ראו את דף ה-API אימות.

נקודות קצה

מה אובייקט כולל

קבוצות הווריאנטים

אלה שמות הערכות, כפי שה-API מקבל ושומר אותם. באולפן האובייקטים/אביזרים בעברית התגיות שלהן מתורגמות, למשל gold מוצגת כזהב.

תמונות ייחוס

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

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

רשימת אובייקטים

הנתיב GET /v1/objects מחזיר את האובייקטים הפעילים שלכם, מהחדש לישן. הוסיפו archived=true כדי לקבל את הארכיון, או projectId כדי לקבל את האובייקטים של פרויקט אחד. הוסיפו q כדי לקבל רק אובייקטים שהשם או התיאור שלהם כוללים את כל המילים שב-q, בלי הבדל בין אותיות גדולות לקטנות: אותו חיפוש כמו בדף ה-API דמויות. כלי ה-MCP list_objects מקבל את אותו חיפוש בפרמטר search. בלי limit, הנתיב מחזיר את הרשימה המלאה. עם limit (עד 500), הוא מחזיר עמוד אחד ו-nextCursor, ששולחים בחזרה בתור cursor עד שהערך שלו הוא null.

curl "https://app.nodaro.ai/v1/objects?limit=100" \
  -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 page = await client.objects.list({ limit: 100 })
const next = await client.objects.list({ limit: 100, cursor: page.nextCursor! })
const { objects: archived } = await client.objects.listArchived()

nodaro objects list --json
nodaro objects list --archived

הנתיב GET /v1/objects/:id מחזיר אובייקט אחד עם pendingJobs. על אובייקט שבארכיון הוא מחזיר 404 not_found, אותה תשובה כמו על אובייקט שלא קיים. כל רשומה, ברשימה ובקריאה לפי מזהה, כוללת גם את המצב שלה על המדף של Nodaro Keepers: catalog, catalogSort ו-catalogCategory. ברשומות שלכם ובכל עותק, הערכים שלהם הם false, 0 ו-null.

יצירה או עדכון של אובייקט

הנתיב POST /v1/objects יוצר אובייקט כשבגוף הבקשה אין id, ומעדכן את האובייקט כשיש בו id. יצירה דורשת nodeId ו-name; כשאין רכיב על הקנבס, השתמשו בכל תווית בתור nodeId, כגון "scripted".

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

curl -X POST https://app.nodaro.ai/v1/objects \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Antique Lantern",
    "description": "Weathered brass lantern with hand-engraved filigree",
    "category": "tool",
    "style": "realistic"
  }'

const { id } = await client.objects.create({
  nodeId: 'scripted',
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  category: 'tool',
  style: 'realistic',
})

const object = await client.objects.get(id)
await client.objects.update(id, { styleLock: false, expectedUpdatedAt: object.updatedAt })

nodaro objects create "Antique Lantern" --node-id scripted \
  --description "Weathered brass lantern with hand-engraved filigree" \
  --category tool --style realistic

nodaro objects update <id> --style-lock false

יצירה מחזירה { id }. עדכון מחזיר { id, updatedAt }.

מה נעילת סגנון משנה

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

יצירת מועמדים לתמונה הראשית

הנתיב POST /v1/generate-object מתחיל משימה אחת לכל מועמד ומחזיר מיד jobIds, מזהה אחד לכל מועמד. בקשה למועמד יחיד מחזירה גם jobId. בדקו את הסטטוס של המשימות מדי כמה שניות דרך ה-API של המשימות.

עם attachToObjectId וכשהשדה count הוא 1, התוצאה הופכת לתמונה הראשית של האובייקט כשהמשימה מסתיימת. עם כמה מועמדים, שום דבר לא מצורף לאובייקט; אשרו את המועמד שאתם מעדיפים.

curl -X POST https://app.nodaro.ai/v1/generate-object \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Antique Lantern", "count": 4 }'

const { jobIds } = await client.objects.generate({
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  count: 4,
})

nodaro objects generate --name "Antique Lantern" --count 1 \
  --attach-to-object-id <id> --watch

{
  "jobIds": [
    "5e2a8c1f-3b7d-4f9a-a6c2-8d1e4b7f0a3c",
    "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d",
    "7a4c1e3b-5d9f-4b2c-c8e4-1f3a6d9b2c5e",
    "8b5d2f4c-6e1a-4c3d-d9f5-2a4b7e1c3d6f"
  ]
}

גם הנתיבים generate-object-asset ו-generate-object-motion מקבלים את seedPromptHint. כך אפשר לשלב בפרומפט בחירה מקטלוג, כגון רכב או חומר, בלי לחבר בורר.

יצירת וריאנט

הנתיב POST /v1/generate-object-asset יוצר וריאנט אחד ומחזיר { jobId }. שלחו attachToObjectId, attachToColumn ו-attachName כדי שהפריט { name: attachName, url } יתווסף לסוף הקבוצה כשהמשימה מסתיימת.

curl -X POST https://app.nodaro.ai/v1/generate-object-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "assetType": "materials",
    "variant": "gold",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachToColumn": "materials",
    "attachName": "gold"
  }'

await client.objects.generateAsset({
  name: 'Antique Lantern',
  assetType: 'variations',
  variant: 'weathered',
  attachToObjectId: id,
  attachToColumn: 'variations',
  attachName: 'weathered',
})

nodaro objects generate-asset --asset-type materials --variant gold \
  --attach-to-object-id <id> --attach-to-column materials --watch

הנפשת התמונה הראשית

הנתיב POST /v1/generate-object-motion הופך תמונה של האובייקט לקליפ קצר של תנועת מצלמה, כגון סיבוב איטי, ריחוף או הקפת רחפן. השתמשו בקליפים כ-B-roll או כפתיחה של סרטון ארוך יותר. הנתיב מחזיר { jobId }.

השדה sourceImageUrl נדרש ואין לו ערך חלופי, ולכן העבירו בו את התמונה הראשית המאושרת. עם attachToObjectId ו-attachName, הקליפ מתווסף לסוף motionClips כשהוא מוכן; לא שולחים עמודה.

curl -X POST https://app.nodaro.ai/v1/generate-object-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "motionPrompt": "slow 360 rotation, soft golden rim light",
    "sourceImageUrl": "https://cdn.nodaro.ai/objects/lantern-main.png",
    "provider": "kling-turbo",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachName": "rotate-360"
  }'

const lantern = await client.objects.get(id)

await client.objects.generateMotion({
  name: 'Antique Lantern',
  motionPrompt: 'slow 360 rotation, soft golden rim light',
  sourceImageUrl: lantern.sourceImageUrl!,
  provider: 'kling-turbo',
  attachToObjectId: id,
  attachName: 'rotate-360',
})

nodaro objects generate-motion --name "Antique Lantern" \
  --motion-prompt "slow 360 rotation, soft golden rim light" \
  --source-image-url "https://cdn.nodaro.ai/objects/lantern-main.png" \
  --provider kling-turbo --attach-to-object-id <id> --attach-name "rotate-360" --watch

המחיר של קליפ הוא המחיר של המודל ליצירה מתמונה לווידאו:

המזהה seedance-2-mini הוא Seedance 2 Mini. Seedance 1.5 הוצא משימוש באוקטובר 2026: בקשה שעדיין מציינת seedance רצה כ-seedance-2-mini ומחויבת לפי המחיר שלו.

אישור תמונה ראשית

הנתיב POST /v1/objects/:id/approve-main-image קובע מועמד שהושלם כתמונה הראשית, ובאותה קריאה כותב את canonicalDescription: הטקסט שפרומפטים מאוחרים יותר משתמשים בו כדי לתאר את האובייקט. גוף הבקשה הוא { candidateJobId, expectedUpdatedAt? }, והמועמד חייב להיות משימה שלכם בסטטוס completed.

הנתיב מחזיר { sourceImageUrl, canonicalDescription }. כשכתיבת התיאור נכשלת, התמונה הראשית בכל זאת נקבעת, והשדה canonicalDescription הוא מחרוזת ריקה; ה-SDK מחזיר במקומה null. קראו ל-POST /v1/objects/:id/llm-caption כדי לנסות שוב. הנתיב הזה מחזיר { canonicalDescription }; כשאי אפשר לכתוב את התיאור הוא מחזיר 502, וכשעדיין אין תמונה ראשית, 400 main_image_required. הוא לא מקבל expectedUpdatedAt, ולכן תמיד אפשר לחזור על הקריאה בלי חשש. האישור עצמו לא עולה קרדיטים. כתיבת התיאור היא קריאה למודל הראייה Claude Sonnet 4.6, שמחויבת לפי הטוקנים שהיא השתמשה בהם, בתעריף של המודל הזה. ראו את הסעיף איך מחויבות קריאות LLM בדף קרדיטים. אישור אף פעם לא נדחה בגלל קרדיטים. כשהיתרה נמוכה מדי לתיאור, התמונה בכל זאת מאושרת, התיאור לא נכתב, והנתיב llm-caption יכול לכתוב אותו אחר כך. על תיאור שהספק חייב עליו משלמים, גם כשהוא חוזר ריק. על תיאור שהספק לא חייב עליו, הקרדיטים מוחזרים.

curl -X POST https://app.nodaro.ai/v1/objects/2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d" }'

const approved = await client.objects.approveMainImage(id, jobIds[1])
if (approved.canonicalDescription === null) {
  await client.objects.recaption(id)
}

nodaro objects approve-main-image <id> --candidate-job-id <jobId>
nodaro objects recaption <id>

שני הנתיבים approve-main-image ו-llm-caption משנים את האובייקט. עם אסימון של אפליקציית OAuth, הם דורשים את ההרשאה assets:write. בקשה עם אסימון בלי ההרשאה הזו נדחית עם 403 insufficient_scope. אסימון הסשן שלכם ואסימוני API אישיים לא צריכים הרשאה.

העברה לארכיון, שחזור ומחיקה של אובייקט

• העברה לארכיון מחזירה { success: true, archived: true }. העברה לארכיון של אובייקט שכבר בארכיון לא משנה כלום.
• שחזור מחזיר { id, name }. אם יש אובייקט פעיל עם אותו שם, בלי הבדל בין אותיות גדולות לקטנות, Nodaro מוסיף לשם את הסיומת (restored) (שוחזר) ומחזיר את השם החדש.
• מחיקה לצמיתות מחזירה { success: true, permanent: true }, ומסירה את האובייקט ואת כל הקבצים שהוא מצביע עליהם ושייכים לכם: התמונה הראשית, הווריאנטים, הקליפים ותמונות הייחוס. קובץ שנוצר ביצירה של משתמש אחר, או שנמצא בתיקיית ההעלאות או בספרייה של משתמש אחר, נשאר באחסון. הקובץ הזה אף פעם לא נספר במכסת האחסון שלכם, ולכן המחיקה לא מפנה בשבילו מקום במכסה. מחיקה לצמיתות עובדת רק על אובייקט שבארכיון; מחיקה של אובייקט פעיל נדחית עם 400 not_archived. העבירו את האובייקט קודם לארכיון, ואז מחקו אותו.

בחירת וריאנט בהרצת אפליקציה

כשתהליך עם רכיב נכס אובייקט/אביזר מתפרסם כאפליקציה, האובייקט הופך לאחד הקלטים של האפליקציה. העבירו "<bucket>/<variant>", למשל "materials/gold", כדי שהווריאנט הזה ישמש כתמונה הראשית של האובייקט בהרצה. כתבו את שם הווריאנט באותיות קטנות, עם מקפים במקום רווחים: השם polished-brass מתאים לווריאנט בשם Polished Brass. אם הקבוצה או הווריאנט לא מוכרים, ההרצה משתמשת במקום זאת בתמונה הראשית. ראו את דף ה-API תהליכים להרצת אפליקציות.

שימוש באובייקט ביצירות אחרות

העבירו את כתובות התמונות של האובייקט כתמונות ייחוס לרכיב יצירת תמונה או לרכיב יצירת וידאו; בקוד, כתובות מפורשות הן הבחירה הפשוטה ביותר. בתהליך, חברו את רכיב האובייקט לרכיב התמונה, או הזכירו וריאנט בפרומפט, למשל @lantern:1:materials/gold לאובייקט בשם Lantern. כשמחברים אובייקט בלי אזכור, Nodaro מחפש בפרומפט שלכם גם שמות של וריאנטים: "gold finish" (גימור זהב) בוחר את materials/gold. ראו את המדריך אובייקטים ואביזרים.

שימוש דרך MCP

אין כלי MCP ליצירה, לעדכון, להעברה לארכיון, לשחזור או למחיקה של אובייקטים: השינויים האלה נעשים ב-REST, ב-SDK או ב-CLI. ראו את מדריך כלי ה-MCP.

קרדיטים

שגיאות