# אובייקטים

> ניהול אביזרים ומוצרים מקוד ב-REST API: יצירה והעברה לארכיון, תמונות ראשיות, וריאנטים של חומר וזווית, קליפי תנועה ואישור התמונה הראשית.

Source: https://nodaro.ai/he/docs/developers/api/objects

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

הנתיבים עובדים בכל מהדורה ומקבלים אסימון Bearer: אסימון API אישי (`ndr_…`), אסימון של אפליקציית OAuth (`ndr_app_…`) או, במהדורת Community, אסימון הסשן שלכם. כל נתיב ניגש רק לנתונים של מי שקורא לו. ראו את דף ה-API [אימות](https://nodaro.ai/docs/developers/api/authentication).

## נקודות קצה
| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `GET` | `/v1/objects` | רשימת האובייקטים שלכם. |
| `GET` | `/v1/objects/:id` | קבלת אובייקט אחד עם המשימות שלו שעדיין רצות. |
| `POST` | `/v1/objects` | יצירת אובייקט, או עדכון אובייקט כשבגוף הבקשה יש `id`. |
| `DELETE` | `/v1/objects/:id` | העברת אובייקט לארכיון. אפשר לשחזר אותו. |
| `DELETE` | `/v1/objects/:id?permanent=true` | מחיקה לצמיתות של אובייקט שבארכיון ושל הקבצים שלו. |
| `POST` | `/v1/objects/:id/restore` | שחזור אובייקט מהארכיון. |
| `POST` | `/v1/generate-object` | יצירת מועמדים לתמונה הראשית. |
| `POST` | `/v1/generate-object-asset` | יצירת וריאנט אחד של זווית, חומר או וריאציה, או וריאנט מותאם אישית. |
| `POST` | `/v1/generate-object-motion` | הנפשת התמונה הראשית לקליפ תנועה. |
| `POST` | `/v1/objects/:id/approve-main-image` | אישור מועמד כתמונה הראשית וכתיבת התיאור של האובייקט. |
| `POST` | `/v1/objects/:id/llm-caption` | כתיבת התיאור מחדש מהתמונה הראשית הנוכחית. |

## מה אובייקט כולל
| שדה | מה יש בו |
| --- | --- |
| `id`, `name`, `description` | המזהה, שם התצוגה והערות על הזהות של האובייקט. |
| `category` | `furniture`, `vehicle`, `weapon`, `food`, `clothing`, `electronics`, `nature`, `tool`, `animal` או `other`. |
| `style` | `realistic`, `anime`, `3d-pixar` או `illustration`. |
| `sourceImageUrl` | התמונה הראשית שמעגנת את האובייקט. הערך נקבע כשמאשרים מועמד. |
| `canonicalDescription` | תיאור חזותי של בין 80 ל-120 מילים בערך, ש-Nodaro כותב כשהתמונה הראשית מאושרת. עד אז הערך הוא מחרוזת ריקה. |
| `styleLock` | האם וריאנטים נוצרים מהתמונה הראשית. ברירת המחדל היא `true`. |
| `angles`, `materials`, `variations`, `motionClips` | קבוצות הווריאנטים. כל פריט הוא `{ name, url }`; ב-`motionClips` נמצאים סרטונים. |
| `referencePhotos` | עד 20 תמונות מודבורד, כל אחת `{ kind, url }`. |
| `pendingJobs` | רק ב-`GET /v1/objects/:id`: משימות הווריאנטים של האובייקט שעדיין רצות. |

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

| קבוצה | מה היא מציגה | ערכות |
| --- | --- | --- |
| `angles` | האובייקט מנקודת מבט אחרת | `front`, `side`, `top`, `back`, `three-quarter`, `detail`, `in-context`, `exploded`, `perspective` |
| `materials` | האובייקט בחומר אחר | `wood`, `metal`, `glass`, `plastic`, `fabric`, `stone`, `ceramic`, `leather`, `paper`, `gold`, `silver`, `copper`, `marble` |
| `variations` | מצב או סגנון אחר | `clean`, `weathered`, `damaged`, `ornate`, `minimal`, `broken`, `antique`, `futuristic`, `holographic`, `dirty`, `polished` |
| `motionClips` | קליפים בלולאה של תנועת מצלמה | `rotate-360`, `hover`, `spin-slow`, `parallax`, `pulse`, `drift`, `dolly-around`, `push-in`, `drone-orbit` |

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

| `kind` | למה הוא מתאים |
| --- | --- |
| `front` | מבט נקי מהחזית. |
| `side` | פרופיל מהצד. שימושי לכלי רכב, לרהיטים ולנשק. |
| `detail` | תקריב של מאפיין ייחודי, כגון חריטה או ציר. |
| `context` | האובייקט במקומו, ביד או מותקן, כדי להראות את הגודל שלו. |
| `moodBoard` | הפלטה או האווירה. |
| `other` | כל דבר אחר. |

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

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

**curl**

```bash
curl "https://app.nodaro.ai/v1/objects?limit=100" \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts

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()
```

**CLI**

```bash
nodaro objects list --json
nodaro objects list --archived
```

הנתיב `GET /v1/objects/:id` מחזיר אובייקט אחד עם `pendingJobs`. על אובייקט שבארכיון הוא מחזיר `404 not_found`, אותה תשובה כמו על אובייקט שלא קיים. כל רשומה, ברשימה ובקריאה לפי מזהה, כוללת גם את המצב שלה על המדף של [Nodaro Keepers](https://nodaro.ai/docs/developers/api/community#keepers): `catalog`, `catalogSort` ו-`catalogCategory`. ברשומות שלכם ובכל עותק, הערכים שלהם הם `false`, `0` ו-`null`.

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

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

**curl**

```bash
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"
}'
```

**TypeScript SDK**

```ts
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 })
```

**CLI**

```bash
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 }`.

<TypeTable
type={{
id: { type: 'string (uuid)', description: 'האובייקט לעדכון. השמיטו אותו כדי ליצור אובייקט.' },
nodeId: { type: 'string', description: 'נדרש ביצירה. הרכיב על הקנבס שהאובייקט שייך אליו, או תווית כלשהי כשאין רכיב כזה.' },
name: { type: 'string', description: 'נדרש ביצירה.' },
description: { type: 'string', description: 'מה מייחד את האובייקט, בין משפט אחד לשלושה משפטים.' },
category: { type: 'string', description: 'furniture, vehicle, weapon, food, clothing, electronics, nature, tool, animal או other.' },
style: { type: 'string', description: 'realistic, anime, 3d-pixar או illustration.' },
styleLock: { type: 'boolean', description: 'יצירת וריאנטים מהתמונה הראשית המאושרת.', default: 'true' },
referencePhotos: { type: 'array', description: 'עד 20 תמונות מודבורד, כל אחת בצורה ‎{ kind, url }‎.' },
canonicalDescription: { type: 'string', description: 'ערך שמחליף את התיאור ש-Nodaro כתב.' },
sourceImageUrl: { type: 'string', description: 'קביעת התמונה הראשית ישירות.' },
projectId: { type: 'string (uuid)', description: 'הפרויקט שבו לשמור את האובייקט.' },
expectedUpdatedAt: { type: 'string (ISO 8601)', description: 'בעדכון: הכתיבה נדחית עם 409 אם האובייקט השתנה מאז חותמת הזמן הזו.' },
}}
/>

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

## יצירת מועמדים לתמונה הראשית
הנתיב `POST /v1/generate-object` מתחיל משימה אחת לכל מועמד ומחזיר מיד `jobIds`, מזהה אחד לכל מועמד. בקשה למועמד יחיד מחזירה גם `jobId`. בדקו את הסטטוס של המשימות מדי כמה שניות דרך [ה-API של המשימות](https://nodaro.ai/docs/developers/api/jobs).

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

**curl**

```bash
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 }'
```

**TypeScript SDK**

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

**CLI**

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

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

| שדה | מה הוא עושה |
| --- | --- |
| `name` | נדרש. שם האובייקט, מ-1 עד 200 תווים. |
| `description` | הערות על הזהות של האובייקט, עד 2,000 תווים. |
| `category`, `style` | הקטגוריה והסגנון החזותי של האובייקט. |
| `count` | מספר המועמדים ליצירה, מ-1 עד 10. ברירת המחדל היא 1. |
| `provider` | מזהה מודל התמונה. השמיטו אותו כדי להשתמש במודל ברירת המחדל. |
| `seedPromptHint` | קטע פרומפט שמשולב בפרומפט, עד 2,000 תווים, למשל `antique brass` (פליז עתיק) מהבורר [חומר](https://nodaro.ai/docs/nodes/creative-controls/material). |
| `sourceImageUrl` | תמונה שממנה מתחילים. |
| `aspectRatio` | יחס הגובה־רוחב של התמונה הראשית. |
| `attachToObjectId`, `expectedUpdatedAt` | צירוף מועמד יחיד לאובייקט הזה, ואם רוצים, רק כשהאובייקט לא השתנה. |

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

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

**curl**

```bash
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"
}'
```

**TypeScript SDK**

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

**CLI**

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

| שדה | מה הוא עושה |
| --- | --- |
| `name` | נדרש. שם האובייקט. |
| `assetType` | נדרש. `angles`, `materials`, `variations` או `custom`. |
| `variant` | נדרש. הווריאנט ליצירה, מ-1 עד 100 תווים. |
| `description` | תיאור של הווריאנט הזה, עד 1,000 תווים. כשמצרפים לאובייקט ומשמיטים אותו, Nodaro כותב טיוטה מהתיאור הקנוני של האובייקט ומהשם של הווריאנט. שלחו תיאור משלכם כדי לדלג על הטיוטה. |
| `provider`, `sourceImageUrl`, `aspectRatio` | מודל התמונה, התמונה שממנה יוצרים את הווריאנט ויחס הגובה־רוחב. |
| `attachToObjectId`, `attachToColumn`, `attachName` | לאן התוצאה נשמרת. הערך של `attachToColumn` הוא `angles`, `materials` או `variations`, וכשהווריאנט הוא `custom`, חובה לציין אותו. |

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

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

**curl**

```bash
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"
}'
```

**TypeScript SDK**

```ts
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',
})
```

**CLI**

```bash
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
```

| שדה | מה הוא עושה |
| --- | --- |
| `name`, `motionPrompt` | נדרשים. שם האובייקט והתנועה שרוצים ליצור. |
| `sourceImageUrl` | נדרש. פריים הפתיחה. |
| `provider` | `kling-turbo` (ברירת המחדל), `kling`, `kling-3.0`, `minimax`, `hailuo-2.3`, `wan-i2v`, `seedance-2-mini` או `bytedance-lite`. |
| `aspectRatio` | `1:1` (ברירת המחדל, מסגור ממורכז של מוצר), `3:4`, `16:9`, `9:16` או `4:3`. |
| `refineFromVideoUrl` | קליפ קיים לעידון עם הפרומפט החדש, במקום להתחיל שוב מהתמונה. הקומפוזיציה נשמרת; השתמשו במודל שתומך בווידאו לווידאו, כגון `wan-i2v`. |
| `attachToObjectId`, `attachName` | האובייקט, ושם הקליפ ב-`motionClips`. |

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

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [Kling 2.5 Turbo Pro](https://nodaro.ai/docs/models/video/kling-2-5-turbo-pro) | Kuaishou | Image to video, Text to video | החל מ-121 | Faster Kling — good quality at lower cost. Supports end frame. |
| [Kling 2.6](https://nodaro.ai/docs/models/video/kling-2-6) | Kuaishou | Image to video, Text to video | החל מ-152 | Kling 2.6 I2V — strong motion realism. 5s/10s, optional native audio. |
| [Kling 3.0](https://nodaro.ai/docs/models/video/kling-3-0) | Kuaishou | Image to video, Text to video | החל מ-297 | Premium Kling 3.0 — variable 3-15s duration, native audio, 720P/1080P. |
| [Hailuo 02 I2V Pro](https://nodaro.ai/docs/models/video/hailuo-02-i2v-pro) | MiniMax | Image to video, Text to video | 158 | Hailuo 02 Pro — strong photoreal motion, fixed 5-second clips. Supports end frame. |
| [Hailuo 2.3 Standard](https://nodaro.ai/docs/models/video/hailuo-2-3-standard) | MiniMax | Image to video | החל מ-83 | Cheaper Hailuo 2.3 tier — good baseline quality. |
| [Wan 2.6 I2V](https://nodaro.ai/docs/models/video/wan-2-6-i2v) | Alibaba | Image to video | החל מ-193 | Wan 2.6 image-to-video — 5/10/15s at 720p/1080p. |
| [Seedance 2 Mini](https://nodaro.ai/docs/models/video/seedance-2-mini) | Bytedance | Image to video, Text to video | החל מ-132 | Budget Seedance 2 tier — 480p/720p only, per-second pricing by resolution. |
| [Bytedance Lite I2V](https://nodaro.ai/docs/models/video/bytedance-lite-i2v) | Bytedance | Image to video, Text to video | 63 | Cheapest Bytedance video tier with end-frame support. |

המזהה `seedance-2-mini` הוא [Seedance 2 Mini](https://nodaro.ai/docs/models/video/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](https://nodaro.ai/docs/concepts/credits#llm-calls) בדף קרדיטים. אישור אף פעם לא נדחה בגלל קרדיטים. כשהיתרה נמוכה מדי לתיאור, התמונה בכל זאת מאושרת, התיאור לא נכתב, והנתיב `llm-caption` יכול לכתוב אותו אחר כך. על תיאור שהספק חייב עליו משלמים, גם כשהוא חוזר ריק. על תיאור שהספק לא חייב עליו, הקרדיטים מוחזרים.

**curl**

```bash
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" }'
```

**TypeScript SDK**

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

**CLI**

```bash
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 אישיים לא צריכים הרשאה.

## העברה לארכיון, שחזור ומחיקה של אובייקט
| פעולה | curl | SDK ל-TypeScript | CLI |
| --- | --- | --- | --- |
| העברה לארכיון | `DELETE /v1/objects/:id` | `client.objects.delete(id)` | `nodaro objects delete <id>` |
| שחזור | `POST /v1/objects/:id/restore` | `client.objects.restore(id)` | `nodaro objects restore <id>` |
| מחיקה לצמיתות | `DELETE /v1/objects/:id?permanent=true` | `client.objects.permanentDelete(id)` | `nodaro objects delete <id> --permanent` |

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

## בחירת וריאנט בהרצת אפליקציה
כשתהליך עם רכיב [נכס אובייקט/אביזר](https://nodaro.ai/docs/nodes/assets/object) מתפרסם כאפליקציה, האובייקט הופך לאחד הקלטים של האפליקציה. העבירו `"<bucket>/<variant>"`, למשל `"materials/gold"`, כדי שהווריאנט הזה ישמש כתמונה הראשית של האובייקט בהרצה. כתבו את שם הווריאנט באותיות קטנות, עם מקפים במקום רווחים: השם `polished-brass` מתאים לווריאנט בשם Polished Brass. אם הקבוצה או הווריאנט לא מוכרים, ההרצה משתמשת במקום זאת בתמונה הראשית. ראו את דף ה-API [תהליכים](https://nodaro.ai/docs/developers/api/workflows) להרצת אפליקציות.

## שימוש באובייקט ביצירות אחרות
העבירו את כתובות התמונות של האובייקט כתמונות ייחוס לרכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image) או לרכיב [יצירת וידאו](https://nodaro.ai/docs/nodes/video/generate-video); בקוד, כתובות מפורשות הן הבחירה הפשוטה ביותר. בתהליך, חברו את רכיב האובייקט לרכיב התמונה, או הזכירו וריאנט בפרומפט, למשל `@lantern:1:materials/gold` לאובייקט בשם Lantern. כשמחברים אובייקט בלי אזכור, Nodaro מחפש בפרומפט שלכם גם שמות של וריאנטים: "gold finish" (גימור זהב) בוחר את `materials/gold`. ראו את המדריך [אובייקטים ואביזרים](https://nodaro.ai/docs/guides/objects).

## שימוש דרך MCP
| כלי | מה הוא עושה |
| --- | --- |
| `list_objects`, `get_object` | מציאת אובייקט וקריאת הכתובות של הווריאנטים שלו. |
| `generate_object` | יצירת תמונה ראשית או וריאנט. |
| `approve_object_main_image`, `recaption_object` | אישור תמונה ראשית, או כתיבת התיאור שלה מחדש. |
| `generate_object_motion` | הנפשת התמונה הראשית. |

אין כלי MCP ליצירה, לעדכון, להעברה לארכיון, לשחזור או למחיקה של אובייקטים: השינויים האלה נעשים ב-REST, ב-SDK או ב-CLI. ראו את [מדריך כלי ה-MCP](https://nodaro.ai/docs/mcp/tools).

## קרדיטים
| נתיב | מחיר ב-Nodaro Cloud |
| --- | --- |
| `POST /v1/generate-object` | המחיר של מודל התמונה כפול `count`. הקרדיטים לכל המועמדים משוריינים לפני שהמשימה הראשונה מתחילה. |
| `POST /v1/generate-object-asset` | המחיר של מודל התמונה, לכל וריאנט. |
| `POST /v1/generate-object-motion` | המחיר של מודל הווידאו מתמונה לווידאו, לכל קליפ. |
| `approve-main-image` | האישור לא עולה קרדיטים. כתיבת התיאור שלו היא קריאה למודל ראייה, שמחויבת לפי הטוקנים שהיא השתמשה בהם. |
| `llm-caption` | אותה קריאה למודל ראייה, שמחויבת באותו אופן. |

## שגיאות
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| `400` | `validation_error` | שדה חסר או לא תקין. |
| `400` | `not_archived` | נשלחה בקשה למחיקה לצמיתות של אובייקט שלא נמצא בארכיון. |
| `400` | `main_image_required` | הקריאה ל-`llm-caption` נשלחה לפני שהייתה לאובייקט תמונה ראשית. |
| `401` | `unauthorized` | האסימון חסר, לא תקין או מבוטל. |
| `402` | `insufficient_credits` | ב-Nodaro Cloud בלבד. אין בחשבון מספיק קרדיטים לשריון. |
| `404` | `not_found` | אין לכם אובייקט פעיל עם המזהה הזה. |
| `409` | `concurrent_modification` | השדה `expectedUpdatedAt` כבר לא תואם. קבלו את האובייקט מחדש, מזגו את השינויים ונסו שוב. |
| `502` | — | אי אפשר היה לכתוב את התיאור הקנוני. נסו שוב. |

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

### מהו אובייקט ב-API של Nodaro?

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

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

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

### האם אפשר למחוק אובייקט לצמיתות דרך ה-API?

כן. העבירו את האובייקט קודם לארכיון עם DELETE /v1/objects/:id, ואז קראו ל-DELETE /v1/objects/:id?permanent=true. המחיקה לצמיתות מסירה את האובייקט ואת הקבצים שלו, והיא נדחית כשהאובייקט לא בארכיון.

### אילו מודלים יכולים להנפיש אובייקט?

שמונה מודלי וידאו יכולים להנפיש אובייקט. מזהי הספק שלהם הם kling-turbo (ברירת המחדל, Kling 2.5 Turbo Pro), kling, kling-3.0, minimax, hailuo-2.3, wan-i2v, seedance-2-mini ו-bytedance-lite. כל קליפ עולה כמו הרצה מתמונה לווידאו באותו מודל.

### למה GET /v1/objects/:id מחזיר 404 לאובייקט שהועבר לארכיון?

אובייקטים שבארכיון מוסתרים מקריאה לפי מזהה. קבלו את הרשימה שלהם עם GET /v1/objects?archived=true, ושחזרו אובייקט עם POST /v1/objects/:id/restore.