# מיקומים

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

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

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

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

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

## מה מיקום כולל
| שדה | מה יש בו |
| --- | --- |
| `id`, `name`, `description` | המזהה, שם התצוגה והערות על הזהות של המקום. |
| `category` | `indoor`, `outdoor`, `urban`, `nature`, `fantasy`, `sci-fi`, `historical`, `futuristic` או `other`. |
| `style` | `realistic`, `anime`, `3d-pixar` או `illustration`. |
| `sourceImageUrl` | השוט הפותח שמעגן את המיקום. הערך נקבע כשמאשרים מועמד. |
| `canonicalDescription` | תיאור חזותי של בין 80 ל-120 מילים בערך, ש-Nodaro כותב כשהתמונה הראשית מאושרת. עד אז הערך הוא מחרוזת ריקה. |
| `styleLock` | האם הווריאנטים נוצרים מהתמונה הראשית. ברירת המחדל היא `true`. |
| `timeOfDay`, `weather`, `seasons`, `angles`, `lighting`, `atmosphereMotions` | קבוצות הווריאנטים. כל פריט הוא `{ name, url }`; ב-`atmosphereMotions` נמצאים סרטונים. |
| `referencePhotos` | עד 20 תמונות מודבורד, כל אחת `{ kind, url }`. |
| `piiConsentAt` | המועד שבו אישרתם שיש הסכמה לשימוש בתמונות הייחוס, או `null`. |
| `pendingJobs`, `previousCandidates` | רק ב-`GET /v1/locations/:id`: משימות הווריאנטים שעדיין רצות, ועד 5 מועמדים אחרונים לתמונה הראשית, מהחדש לישן. |

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

| קבוצה | מה היא מציגה | ערכות |
| --- | --- | --- |
| `timeOfDay` | אותו שוט בשעה אחרת | `dawn`, `morning`, `noon`, `afternoon`, `golden hour`, `dusk`, `blue hour`, `night`, `midnight` |
| `weather` | אותו שוט במזג אוויר אחר | `clear`, `cloudy`, `light rain`, `heavy rain`, `storm`, `snow`, `blizzard`, `fog`, `mist` |
| `seasons` | אותו שוט בעונה אחרת | `spring`, `summer`, `autumn`, `winter` |
| `angles` | המקום מזווית מצלמה אחרת | `wide`, `medium`, `closeup`, `aerial`, `low-angle`, `eye-level`, `bird's-eye`, `dutch tilt` |
| `lighting` | מערך תאורה אחר | `soft natural`, `harsh sunlight`, `golden`, `blue hour`, `neon`, `candlelit`, `cinematic`, `dramatic chiaroscuro` |
| `atmosphereMotions` | קליפי אווירה בלולאה, עם תנועת מצלמה | `slow dolly-in`, `slow pan-left`, `slow pan-right`, `push up`, `drone fly-over`, `gentle drift`, `parallax`, `static atmospheric` |

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

| `kind` | למה הוא מתאים |
| --- | --- |
| `wide` | מבט רחב יותר על אותו מקום. |
| `interior`, `exterior` | המקום מבפנים כשהתמונה הראשית מציגה אותו מבחוץ, או להפך. |
| `detail` | פרט מאפיין, כגון פסל, שלט או חומר. |
| `moodBoard` | הפלטה או האווירה. |
| `other` | כל דבר אחר. |

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

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

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

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

**curl**

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

curl https://app.nodaro.ai/v1/locations/9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f \
  -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 { locations } = await client.locations.list()
const alley = await client.locations.get(locations[0].id)
console.log(alley.previousCandidates)
```

**CLI**

```bash
nodaro locations list --json
nodaro locations get <id> --json
```

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

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

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/locations \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"nodeId": "scripted",
"name": "Rainy Tokyo Alley",
"description": "Neon-soaked alley with vending machines and wet pavement",
"category": "urban",
"style": "realistic"
}'
```

**TypeScript SDK**

```ts
const { id } = await client.locations.create({
nodeId: 'scripted',
name: 'Rainy Tokyo Alley',
description: 'Neon-soaked alley with vending machines and wet pavement',
category: 'urban',
style: 'realistic',
})

const location = await client.locations.get(id)
await client.locations.update(id, {
referencePhotos: [{ kind: 'wide', url: 'https://cdn.nodaro.ai/uploads/alley-wide.jpg' }],
piiConsentAt: new Date().toISOString(),
expectedUpdatedAt: location.updatedAt,
})
```

**CLI**

```bash
nodaro locations create "Rainy Tokyo Alley" --node-id scripted \
  --description "Neon-soaked alley with vending machines and wet pavement" \
  --category urban --style realistic

nodaro locations update <id> --style-lock false
```

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

יצירה מחזירה `{ id }`.

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

## יצירת מועמדים לשוט הפותח
הנתיב `POST /v1/generate-location` מתחיל משימה אחת לכל מועמד ומחזיר `jobIds`. בקשה למועמד יחיד מחזירה גם `jobId`.

- **מועמד אחד, מצורף למיקום.** עם `attachToLocationId` וכש-`count` הוא 1, התוצאה הופכת לתמונה הראשית כשהמשימה מסתיימת.
- **כמה מועמדים.** שום דבר לא מצורף למיקום. התמונה הראשית הנוכחית נשארת, ומועמדים שהושלמו מופיעים ב-`previousCandidates` בתגובה של `GET /v1/locations/:id`. אשרו את המועמד שאתם מעדיפים.
- **עריכת השוט הנוכחי.** השדה `userPrompt` הוא הוראה חד־פעמית, למשל "add rain and puddles" (הוסף גשם ושלוליות). עם `sourceImageUrl`, תמונת המקור נערכת לפי ההוראה. ההוראה אף פעם לא נשמרת במיקום.

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/generate-location \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"name": "Rainy Tokyo Alley",
"count": 1,
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f"
}'
```

**TypeScript SDK**

```ts
const { jobIds } = await client.locations.generate({
name: 'Rainy Tokyo Alley',
description: 'Neon-soaked alley with vending machines',
count: 4,
})
```

**CLI**

```bash
nodaro locations generate --name "Rainy Tokyo Alley" --count 1 \
  --attach-to-location-id <id> --watch
```

```json
{ "jobId": "4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d", "jobIds": ["4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d"] }
```

| שדה | מה הוא עושה |
| --- | --- |
| `name` | נדרש. שם המיקום. |
| `description`, `category`, `style` | הזהות של המיקום. |
| `count` | מספר המועמדים ליצירה, מ-1 עד 10. ברירת המחדל היא 1. |
| `userPrompt` | הוראה חד־פעמית שמכוונת את היצירה הזו. לא נשמרת אף פעם. |
| `sourceImageUrl` | תמונה לעריכה או כנקודת התחלה. |
| `provider` | מזהה מודל התמונה. השמיטו אותו כדי להשתמש במודל ברירת המחדל. |
| `quality`, `resolution` | רמת הפלט של מודל התמונה, שמתומחרת כמו ברכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image). |
| `attachToLocationId` | צירוף מועמד יחיד למיקום הזה. |

השדות `quality` ו-`resolution` עובדים כמו ב-API של הדמויות. כשהמודל לא מקבל ערך מהרשימה, הבקשה לא נדחית. Nodaro משתמש במקומו בערך שהמודל תומך בו, או משמיט את ההגדרה כשאין למודל הגדרה כזו. הקרדיטים נקבעים לפי הערך שרץ בפועל, והשדה `input_data` של המשימה מציג אותו.

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

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/generate-location-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"name": "Rainy Tokyo Alley",
"assetType": "weather",
"variant": "storm",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachToColumn": "weather",
"attachName": "storm"
}'
```

**TypeScript SDK**

```ts
await client.locations.generateAsset({
name: 'Rainy Tokyo Alley',
assetType: 'timeOfDay',
variant: 'blue hour',
attachToLocationId: id,
attachToColumn: 'time_of_day',
attachName: 'blue hour',
})
```

**CLI**

```bash
nodaro locations generate-asset <id> --asset-type weather --variant storm --watch
```

הערך של `assetType` הוא `timeOfDay`, `weather`, `seasons`, `angles`, `lighting` או `custom`. הערך של `attachToColumn` הוא `time_of_day`, `weather`, `seasons`, `angles` או `lighting`, וכשהווריאנט הוא `custom`, חובה לציין אותו. הנתיב מקבל גם `provider`, `quality`, `resolution` ו-`sourceImageUrl`.

## בניית מבט של 360 מעלות
הנתיב `POST /v1/generate-surround-continuation` בונה מבט של 360 מעלות סביב המקום, תצוגה אחת בכל פעם, למשל כל 45 מעלות. כל קריאה ממשיכה את התצוגה הקודמת. Nodaro מעביר את הקצה של התצוגה הזו לתמונה החדשה, ומשלים רק את שאר התמונה. אחר כך הוא מתאים את החשיפה ואת הצבע של החלק שהושלם לאלה של החלק שהועבר. החלק שהועבר נשאר זהה פיקסל־לפיקסל, ולכן תצוגות סמוכות מתחברות זו לזו במציג פנורמות. הנתיב הזה עובד רק ב-Nodaro Cloud; במהדורות אחרות הוא מחזיר `403 edition_required`.

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/generate-surround-continuation \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"referenceImageUrl": "https://cdn.nodaro.ai/locations/alley-main.png",
"direction": "right",
"degrees": 45,
"provider": "nano-banana-pro",
"aspectRatio": "16:9",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachToColumn": "angles",
"attachName": "Surround 45°"
}'
```

**TypeScript SDK**

```ts
const { jobId } = await client.locations.generateSurroundContinuation({
referenceImageUrl: previousView,
direction: 'right',
degrees: 45,
provider: 'nano-banana-pro',
aspectRatio: '16:9',
attachToLocationId: id,
attachToColumn: 'angles',
attachName: 'Surround 45°',
})
```

| שדה | מה הוא עושה |
| --- | --- |
| `referenceImageUrl` | נדרש. התצוגה הקודמת שממנה ממשיכים. |
| `direction` | נדרש. לסיבוב `right` או `left`, ולהטיה `up` או `down`. |
| `degrees` | הזווית של התצוגה הזו, מ-0 עד 360, שנשמרת עם התוצאה. |
| `carriedFraction` | כמה מהתמונה מועבר מהתצוגה הקודמת, מ-0.1 עד 0.9. ברירת המחדל היא 0.5 בסיבוב ופס דק בהטיה. |
| `provider`, `aspectRatio` | מודל התמונה ויחס הגובה־רוחב. העורך משתמש ב-`nano-banana-pro` וב-`16:9`, כדי שכל תצוגה תתאים לשוט הפותח. |
| `attachToLocationId`, `attachToColumn`, `attachName` | צירוף התצוגה למיקום, בדרך כלל לקבוצה `angles`. |

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

## הנפשת השוט הפותח
הנתיב `POST /v1/generate-location-motion` הופך את השוט הפותח לקליפ אווירה: ערפל נע, דולי איטי, מעוף רחפן. הנתיב מחזיר `{ jobId }`. השדה `sourceImageUrl` נדרש; העבירו בו את התמונה הראשית המאושרת. עם `attachToLocationId` ו-`attachName`, הקליפ מתווסף לסוף `atmosphereMotions`; לא שולחים עמודה.

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/generate-location-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"name": "Rainy Tokyo Alley",
"motionPrompt": "slow dolly-in, neon signs flicker, light rain falling",
"sourceImageUrl": "https://cdn.nodaro.ai/locations/alley-main.png",
"provider": "kling",
"attachToLocationId": "9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f",
"attachName": "neon dolly-in"
}'
```

**TypeScript SDK**

```ts
await client.locations.generateMotion({
name: 'Rainy Tokyo Alley',
motionPrompt: 'slow dolly-in, neon signs flicker, light rain falling',
sourceImageUrl: location.sourceImageUrl!,
provider: 'kling',
attachToLocationId: id,
attachName: 'neon dolly-in',
})
```

**CLI**

```bash
nodaro locations generate-motion --name "Rainy Tokyo Alley" \
  --motion-prompt "slow dolly-in, neon signs flicker, light rain falling" \
  --source-image-url "https://cdn.nodaro.ai/locations/alley-main.png" \
  --provider kling --attach-to-location-id <id> --attach-name "neon dolly-in" --watch
```

| שדה | מה הוא עושה |
| --- | --- |
| `name`, `motionPrompt` | נדרשים. שם המיקום והתנועה שרוצים ליצור. |
| `sourceImageUrl` | נדרש. פריים הפתיחה. |
| `provider` | `kling` (ברירת המחדל), `kling-turbo`, `kling-3.0`, `wan-i2v`, `wan-2.7-i2v` או `seedance-2`. |
| `aspectRatio` | `16:9` (ברירת המחדל), `1:1`, `3:4` או `9:16`. |
| `refineFromVideoUrl` | קליפ קיים לעידון עם הפרומפט החדש, למשל כדי להפוך ערפל לגשם בלי להזיז את המצלמה. השתמשו במודל שתומך בווידאו לווידאו, כגון `wan-i2v`. |
| `attachToLocationId`, `attachName` | המיקום, ושם הקליפ ב-`atmosphereMotions`. |

| Model | Maker | Modes | Credits | Details |
| --- | --- | --- | --- | --- |
| [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 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 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. |
| [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. |
| [Wan 2.7 I2V](https://nodaro.ai/docs/models/video/wan-2-7-i2v) | Alibaba | Image to video | 207 | Wan 2.7 image-to-video — 2–15s at 720p/1080p, supports start+end frame. |
| [Seedance 2](https://nodaro.ai/docs/models/video/seedance-2) | Bytedance | Image to video, Text to video | החל מ-253 | Seedance 2 — premium tier with native audio. Per-second pricing by resolution. |

## אישור תמונה ראשית
הנתיב `POST /v1/locations/:id/approve-main-image` עם `{ candidateJobId }` קובע מועמד שהושלם כתמונה הראשית, וכותב את `canonicalDescription` באותה קריאה. הנתיב מחזיר `{ sourceImageUrl, canonicalDescription }`.

כשכתיבת התיאור נכשלת, התמונה הראשית בכל זאת נקבעת, והשדה `canonicalDescription` הוא מחרוזת ריקה; ה-SDK מחזיר `null`. קראו לנתיב `POST /v1/locations/:id/llm-caption` כדי לנסות שוב. הנתיב הזה מחזיר `{ canonicalDescription }`; כשאי אפשר לכתוב את התיאור הוא מחזיר `502`, וכשעדיין אין תמונה ראשית, `400 no_source_image`. אפשר לחזור על הקריאה לשני הנתיבים בלי חשש. האישור עצמו לא עולה קרדיטים. כתיבת התיאור היא קריאה למודל הראייה 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/locations/9a1d3f5b-7c2e-4a8d-b6f1-3e5c7a9b2d4f/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "4d6f8b1a-3c5e-4f7a-9b2d-6e8a1c3f5b7d" }'
```

**TypeScript SDK**

```ts
const { sourceImageUrl, canonicalDescription } =
await client.locations.approveMainImage(id, jobIds[2])
```

**CLI**

```bash
nodaro locations approve-main-image <id> --candidate-job-id <jobId>
nodaro locations recaption <id>
```

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

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

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

## בחירת וריאנט בהרצת אפליקציה
כשתהליך עם רכיב [נכס מיקום](https://nodaro.ai/docs/nodes/assets/location) מתפרסם כאפליקציה, המיקום הופך לאחד הקלטים של האפליקציה. העבירו `"<bucket>/<variant>"`, למשל `"weather/light-rain"`, כדי שהווריאנט הזה ישמש כתמונה הראשית של המיקום בהרצה. כתבו את שם הווריאנט באותיות קטנות, עם מקפים במקום רווחים. אם הקבוצה או הווריאנט לא מוכרים, ההרצה משתמשת במקום זאת בתמונה הראשית.

## שימוש במיקום ביצירות אחרות
העבירו את כתובות התמונות של המיקום כתמונות ייחוס לרכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image) או לרכיב [יצירת וידאו](https://nodaro.ai/docs/nodes/video/generate-video); בקוד, כתובות מפורשות הן הבחירה הפשוטה ביותר. בתהליך, חברו את רכיב המיקום לרכיב התמונה, או הזכירו וריאנט בפרומפט, למשל `@oldlibrary:1:weather/rain` למיקום בשם Old Library. בלי אזכור, Nodaro מחפש שמות של וריאנטים בפרומפט שלכם: "at sunset" (בשקיעה) בוחר וריאנט `dusk` אם יש לכם כזה. ראו את המדריך [מיקומים](https://nodaro.ai/docs/guides/locations).

## שימוש דרך MCP
| כלי | מה הוא עושה |
| --- | --- |
| `list_locations`, `get_location` | מציאת מיקום וקריאת הכתובות של הווריאנטים שלו. |
| `create_location`, `update_location` | יצירת מיקום או שינוי שדות הזהות שלו. |
| `generate_location` | יצירת תמונה ראשית (`kind: "main"`) או וריאנט (`kind: "asset"`). |
| `generate_location_motion` | הנפשת התמונה הראשית. |
| `approve_main_image`, `recaption_location` | אישור תמונה ראשית, או כתיבת התיאור שלה מחדש. |

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

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

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

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

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

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

### איך מנסים שוטים פותחים חדשים בלי לאבד את השוט הנוכחי?

כדי לנסות שוטים פותחים חדשים, צרו כמה מועמדים בלי לצרף אותם למיקום. התמונה הראשית הנוכחית נשארת עד שתאשרו מועמד, והנתיב GET /v1/locations/:id מחזיר עד 5 מועמדים אחרונים בשדה previousCandidates.

### האם צריך הסכמה כדי להוסיף תמונות ייחוס למיקום?

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

### האם אפשר לבנות מבט של 360 מעלות סביב מיקום?

ב-Nodaro Cloud, הנתיב POST /v1/generate-surround-continuation יוצר את התצוגה הבאה של פנורמה מהתצוגה הקודמת, ושומר על החצי המשותף זהה פיקסל־לפיקסל, כדי שהתצוגות יתחברו זו לזו. כל תצוגה עולה כמו יצירת תמונה אחת.

### אילו מודלים מנפישים מיקום?

שישה מודלי וידאו מנפישים מיקום. מזהי הספק שלהם הם kling (ברירת המחדל, Kling 2.6), kling-turbo, kling-3.0, wan-i2v, wan-2.7-i2v ו-seedance-2. כל קליפ עולה כמו הרצה מתמונה לווידאו באותו מודל.