# מיקומים
> יוצרים מיקומים ושוטים פותחים מקוד TypeScript, מאשרים אחד מהם ומוסיפים וריאנטים של שעות היום, מזג אוויר, עונה, זווית ותנועה.
Source: https://nodaro.ai/he/docs/developers/sdk/locations
**`client.locations`** מאפשר לעשות בסקריפט כל מה שעושים באולפן המיקומים: הוא יוצר ועורך מיקומים, יוצר להם מועמדים לשוט הפותח, מאשר אחד מהם כתמונה הראשית ומוסיף וריאנטים של שעות היום, מזג האוויר, העונות, הזוויות והתאורה, וגם קליפי אווירה. מיקום שומר את התמונה הראשית, את קבוצות הווריאנטים, את תמונות הייחוס ואת התיאור שלו, כך שכל שוט בהמשך יכול להציג את אותו מקום. המתודות קוראות לנקודות הקצה שבדף ה-API [מיקומים](https://nodaro.ai/docs/developers/api/locations). העבודה בעורך מתוארת במדריך [מיקומים](https://nodaro.ai/docs/guides/locations).
## מתודות
| מתודה | מה היא עושה |
| --- | --- |
| [`list(params?)`](#listparams) | רשימת המיקומים שלכם |
| [`listArchived(params?)`](#listarchivedparams) | רשימת המיקומים שלכם שבארכיון |
| [`get(id)`](#getid) | קריאת מיקום אחד, עם המשימות שלו שעדיין רצות |
| [`create(input)`](#createinput) | יצירת מיקום |
| [`update(id, input)`](#updateid-input) | שינוי מיקום |
| [`delete(id)` ו-`restore(id)`](#deleteid-and-restoreid) | העברת מיקום לארכיון או שחזור שלו |
| [`generate(input)`](#generateinput) | יצירת מועמדים לשוט הפותח |
| [`generateAsset(input)`](#generateassetinput) | יצירת וריאנט של שעת יום, מזג אוויר, עונה, זווית או תאורה |
| [`generateSurroundContinuation(input)`](#generatesurroundcontinuationinput) | יצירת התצוגה הבאה בטבעת של 360 מעלות |
| [`generateMotion(input)`](#generatemotioninput) | הנפשת התמונה הראשית לקליפ אווירה |
| [`removeAsset(id, data)`](#removeassetid-data) | הסרת תוצאה אחת מקבוצת וריאנטים |
| [`approveMainImage(id, candidateJobId)`](#approvemainimageid-candidatejobid) | קביעת מועמד כתמונה הראשית |
| [`recaption(id)`](#recaptionid) | כתיבת התיאור של המיקום מחדש |
## client.locations
### list(params?)
מחזירה את רשימת המיקומים שלכם. כברירת מחדל היא מחזירה רק מיקומים פעילים. החלוקה לעמודים היא אופציונלית: בלי `limit` מקבלים את הרשימה המלאה ובלי cursor; עם `limit`, עד 500, מקבלים עמוד אחד ו-`nextCursor`.
```ts
list(params?: { archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
locations: Location[]
nextCursor?: string | null
}>
```
```ts
const { locations } = await client.locations.list()
const { locations: cafes } = await client.locations.list({ q: "café" })
const page = await client.locations.list({ limit: 100 })
const next = await client.locations.list({ limit: 100, cursor: page.nextCursor ?? undefined })
```
המשיכו לבקש עמודים עד ש-`nextCursor` הוא `null`. כללי החיפוש של `q` מפורטים בדף [דמויות](https://nodaro.ai/docs/developers/sdk/characters#listparams): החיפוש כולל רק את 5 המילים הראשונות, ו-`%`, `_` ו-`*` הם לא תווים כלליים. שלחו את אותו `q` עם כל `cursor`.
### listArchived(params?)
מחזירה את רשימת המיקומים שלכם שבארכיון. המתודה היא קיצור של `list({ archived: true })`.
```ts
listArchived(params?: { limit?: number; cursor?: string }): Promise<{ locations: Location[]; nextCursor?: string | null }>
```
```ts
const { locations: archived } = await client.locations.listArchived()
```
### get(id)
מחזירה מיקום אחד, עם `pendingJobs`, הווריאנטים שעדיין נוצרים, ועם `previousCandidates`, עד 5 מועמדים קודמים לתמונה הראשית, מהחדש לישן. כדי לקבוע אחד מהם כתמונה הראשית, קראו ל-`approveMainImage()`.
```ts
get(id: string): Promise
```
```ts
const location = await client.locations.get(locationId)
console.log(location.sourceImageUrl, location.weather, location.atmosphereMotions)
```
מיקום שבארכיון עדיין חוזר לפי המזהה, ולכן רכיבי תהליך שמצביעים עליו ממשיכים להיטען. אובייקט `Location` כולל את התמונה הראשית ב-`sourceImageUrl`, שש קבוצות של וריאנטים (`timeOfDay`, `weather`, `seasons`, `angles`, `lighting` ו-`atmosphereMotions`, כל אחת רשימה של `{ name, url }`), `boards`, `referencePhotos`, `canonicalDescription`, `styleLock` ו-`updatedAt`.
### create(input)
יוצרת מיקום. השדות `name` ו-`nodeId` נדרשים. סקריפט שאין לו רכיב על הקנבס יכול להעביר `"mcp-managed"` בתור `nodeId`.
```ts
create(input: CreateLocationInput): Promise<{ id: string }>
```
```ts
const { id: locationId } = await client.locations.create({
nodeId: "mcp-managed",
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
category: "urban",
style: "realistic",
})
```
### update(id, input)
משנה מיקום. רק השדות שאתם שולחים נכתבים. קבוצות הווריאנטים לא חלק מהקריאה הזו, כי משימות יצירה מוסיפות אליהן בזמן שאתם עובדים. כדי לשנות אותן, השתמשו ב-`generateAsset()` וב-`removeAsset()`.
```ts
update(id: string, input: UpdateLocationInput): Promise<{ id: string; updatedAt: string }>
```
', description: "לוחות הייחוס של המיקום." },
selectedAssetByVariant: { type: 'Record', description: "הגרסה שנבחרה לכל וריאנט." },
piiConsentAt: { type: 'string', description: "חותמת זמן בפורמט ISO 8601 שמתעדת מתי המשתמש אישר שיש לו זכויות על תמונות הייחוס. הגדירו את השדה כשמצרפים את referencePhotos בפעם הראשונה." },
expectedUpdatedAt: { type: 'string', description: "ערך ה-updatedAt שקיבלתם. אם המיקום השתנה מאז, העדכון נדחה עם 409 concurrent_modification." },
}}
/>
```ts
await client.locations.update(locationId, {
canonicalDescription: "A narrow, rain-soaked alley lit by neon signs",
styleLock: false,
piiConsentAt: new Date().toISOString(),
expectedUpdatedAt: location.updatedAt,
})
```
השגיאה `409 concurrent_modification` מגיעה כ-`NodaroError` רגילה עם ה-`code` הזה. טענו את המיקום שוב, מזגו את השינוי שלכם ונסו שוב.
### delete(id) ו-restore(id)
המתודה `delete()` מעבירה מיקום לארכיון, והמתודה `restore()` מחזירה אותו מהארכיון. מחיקה לצמיתות זמינה רק באפליקציה של Nodaro. כששם של מיקום משוחזר זהה לשם של מיקום פעיל, בלי הבדל בין אותיות גדולות לקטנות, השרת מוסיף `(restored)` (שוחזר) ומחזיר את השם שנקבע.
```ts
delete(id: string): Promise<{ success: true; archived: true }>
restore(id: string): Promise<{ id: string; name: string }>
```
```ts
await client.locations.delete(locationId)
const { name } = await client.locations.restore(locationId)
```
### generate(input)
יוצרת מועמדים לשוט הפותח (`POST /v1/generate-location`). כש-`count` גדול מ-1, הקרדיטים לכל המשימות משוריינים לפני שמשימה כלשהי מתחילה, ולכן כשל באמצע הדרך מבטל את האצווה כולה.
```ts
generate(input: GenerateLocationInput): Promise<{ jobIds: string[]; jobId?: string }>
```
```ts
// One candidate, written to the location when it completes
const { jobIds: [jobId] } = await client.locations.generate({
name: "Rainy Tokyo Alley",
description: "Neon-soaked alley with vending machines",
attachToLocationId: locationId,
})
// Four candidates to choose from
const { jobIds } = await client.locations.generate({ name: "Rainy Tokyo Alley", count: 4 })
```
עם `attachToLocationId` וכש-`count` הוא 1, התוצאה הופכת לתמונה הראשית כשהמשימה מסתיימת. אחרת, בחרו מועמד עם `approveMainImage()`. התמחור של `quality` ושל `resolution` הוא כמו ברכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image). גם ערך מהרשימה שהמודל לא תומך בו לא נדחה. Nodaro משתמש במקומו בערך שהמודל תומך בו, או משמיט את ההגדרה כשאין למודל הגדרה כזו. הקרדיטים נקבעים לפי הערך שרץ בפועל, והשדה `input_data` של המשימה מציג אותו.
### generateAsset(input)
יוצרת וריאנט אחד של המיקום (`POST /v1/generate-location-asset`). עם `attachToLocationId`, `attachToColumn` ו-`attachName`, התוצאה מתווספת לקבוצה הזו כשהמשימה מסתיימת.
```ts
generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>
```
```ts
const { jobId } = await client.locations.generateAsset({
name: "Rainy Tokyo Alley",
assetType: "weather",
variant: "storm",
attachToLocationId: locationId,
attachToColumn: "weather",
attachName: "storm",
})
```
### generateSurroundContinuation(input)
יוצרת את התצוגה הבאה בטבעת של 360 מעלות (`POST /v1/generate-surround-continuation`), בהמשך לתצוגה הקודמת. השרת משאיר חצי מהתצוגה הקודמת בדיוק כמו שהוא, משלים את החצי השני ומתאים את הצבעים שלו, כך שתצוגות סמוכות מתחברות זו לזו בלי תפר. המתודה הזו עובדת ב-Nodaro Cloud; במהדורות אחרות הנתיב מחזיר `403 edition_required` לפני כל עיבוד, וה-SDK זורק את התשובה הזו כ-`ForbiddenError`.
```ts
generateSurroundContinuation(input: GenerateSurroundContinuationInput): Promise<{ jobId: string }>
```
```ts
const { jobId } = await client.locations.generateSurroundContinuation({
referenceImageUrl: previousRingView,
direction: "right",
degrees: 45,
provider: "nano-banana-pro",
aspectRatio: "16:9",
attachToLocationId: locationId,
attachToColumn: "angles",
attachName: "Surround 45°",
})
```
### generateMotion(input)
מנפישה את התמונה של המיקום לקליפ אווירה (`POST /v1/generate-location-motion`), בעזרת רכיב [יצירת וידאו](https://nodaro.ai/docs/nodes/video/generate-video) במצב תמונה לווידאו. למיקום יש קבוצת תנועה אחת, ולכן הקליפ תמיד נכנס ל-`atmosphereMotions` ואין `attachToColumn`.
```ts
generateMotion(input: GenerateLocationMotionInput): Promise<{ jobId: string }>
```
```ts
const { jobId } = await client.locations.generateMotion({
name: "Rainy Tokyo Alley",
motionPrompt: "Slow dolly-in, neon signs flicker, light rain falling",
sourceImageUrl: location.sourceImageUrl!,
provider: "kling",
attachToLocationId: locationId,
attachName: "neon dolly-in",
})
```
### removeAsset(id, data)
מסירה תוצאה אחת מקבוצת וריאנטים (`POST /v1/locations/:id/remove-asset`). כל הפריטים עם ה-`url` הזה נמחקים בצעד אחד. אפשר להשתמש בה, למשל, לפני שיוצרים מחדש תצוגה במבט של 360 מעלות.
```ts
removeAsset(id: string, data: { column: LocationAttachColumn; url: string }): Promise<{ removed: true }>
```
```ts
await client.locations.removeAsset(locationId, { column: "angles", url: oldViewUrl })
```
המתודה זורקת `NotFoundError` כשהכתובת לא נמצאת בקבוצה הזו או כשהמיקום לא שייך לכם.
### approveMainImage(id, candidateJobId)
קובעת מועמד שהושלם מ-`generate()` כתמונה הראשית של המיקום. אחר כך מודל ראייה כותב את התיאור של המיקום, והמתודה מחזירה את שניהם.
```ts
approveMainImage(id: string, candidateJobId: string): Promise<{ sourceImageUrl: string; canonicalDescription: string | null }>
```
```ts
const { sourceImageUrl, canonicalDescription } = await client.locations.approveMainImage(locationId, jobIds[0])
```
השדה `canonicalDescription` הוא `null` כשאי אפשר היה לכתוב את התיאור. התמונה הראשית בכל זאת נקבעת; קראו ל-`recaption()` כדי לנסות שוב.
### recaption(id)
כותבת מחדש את התיאור של המיקום מהתמונה הראשית הנוכחית שלו.
```ts
recaption(id: string): Promise<{ canonicalDescription: string }>
```
```ts
const { canonicalDescription } = await client.locations.recaption(locationId)
```
המתודה נכשלת עם `400 no_source_image` כשאין למיקום תמונה ראשית, ועם 502 כשמודל הראייה נכשל.
## שאלות נפוצות
### איך יוצרים מיקום עם ה-SDK של Nodaro?
קראו למתודה client.locations.create עם nodeId ועם שם, צרו שוטים פותחים עם המתודה client.locations.generate ואשרו אחד מהם עם המתודה client.locations.approveMainImage.
### אילו וריאנטים אפשר ליצור למיקום?
המתודה generateAsset יוצרת וריאנטים של שעות היום, מזג האוויר, העונות, הזוויות והתאורה, וגם וריאנטים מותאמים אישית, והמתודה generateMotion יוצרת קליפי אווירה. ב-Nodaro Cloud, המתודה generateSurroundContinuation מוסיפה תצוגות למבט של 360 מעלות.
### איך נמנעים מדריסה של מיקום שמישהו אחר שינה?
העבירו למתודה client.locations.update את השדה expectedUpdatedAt, כלומר את ערך ה-updatedAt שקיבלתם. אם המיקום השתנה, הקריאה נכשלת עם 409 concurrent_modification. טענו את המיקום שוב, מזגו את השינויים ונסו שוב.
### האם אפשר למחוק מיקום לצמיתות עם ה-SDK?
לא. המתודה delete מעבירה את המיקום לארכיון, והמתודה restore מחזירה אותו מהארכיון. מחיקה לצמיתות זמינה רק באפליקציה של Nodaro.