מיקומים

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

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

נקודות קצה

מה מיקום כולל

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

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

תמונות ייחוס והסכמה

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

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

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

רשימה וקריאה של מיקומים

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

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

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"

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

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)

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

יצירה או עדכון של מיקום

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

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

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

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,
})

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

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

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

יצירת מועמדים לשוט הפותח

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

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

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

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

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

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

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

יצירת וריאנט

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

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

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

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 -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°"
  }'

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

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

הנפשת השוט הפותח

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

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

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

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

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

הנתיב 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 בדף קרדיטים. אישור אף פעם לא נדחה בגלל קרדיטים. כשהיתרה לא מספיקה לתיאור, התמונה בכל זאת מאושרת, התיאור לא נכתב, והנתיב llm-caption יכול לכתוב אותו מאוחר יותר. על תיאור שהספק חייב עליו משלמים, גם כשהוא חוזר ריק. על תיאור שהספק לא חייב עליו, הקרדיטים מוחזרים.

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

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

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

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

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

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

כשתהליך עם רכיב נכס מיקום מתפרסם כאפליקציה, המיקום הופך לאחד הקלטים של האפליקציה. העבירו "<bucket>/<variant>", למשל "weather/light-rain", כדי שהווריאנט הזה ישמש כתמונה הראשית של המיקום בהרצה. כתבו את שם הווריאנט באותיות קטנות, עם מקפים במקום רווחים. אם הקבוצה או הווריאנט לא מוכרים, ההרצה משתמשת במקום זאת בתמונה הראשית.

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

העבירו את כתובות התמונות של המיקום כתמונות ייחוס לרכיב יצירת תמונה או לרכיב יצירת וידאו; בקוד, כתובות מפורשות הן הבחירה הפשוטה ביותר. בתהליך, חברו את רכיב המיקום לרכיב התמונה, או הזכירו וריאנט בפרומפט, למשל @oldlibrary:1:weather/rain למיקום בשם Old Library. בלי אזכור, Nodaro מחפש שמות של וריאנטים בפרומפט שלכם: "at sunset" (בשקיעה) בוחר וריאנט dusk אם יש לכם כזה. ראו את המדריך מיקומים.

שימוש דרך MCP

העברה לארכיון ושחזור לא זמינים דרך MCP, במכוון. ראו את מדריך כלי ה-MCP.

קרדיטים

שגיאות