מיקומים

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

מתודות

client.locations

list(params?)‎

מחזירה את רשימת המיקומים שלכם. כברירת מחדל היא מחזירה רק מיקומים פעילים. החלוקה לעמודים היא אופציונלית: בלי limit מקבלים את הרשימה המלאה ובלי cursor; עם limit, עד 500, מקבלים עמוד אחד ו-nextCursor.

list(params?: { archived?: boolean; q?: string; limit?: number; cursor?: string }): Promise<{
  locations: Location[]
  nextCursor?: string | null
}>

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 מפורטים בדף דמויות: החיפוש כולל רק את 5 המילים הראשונות, ו-%, _ ו-* הם לא תווים כלליים. שלחו את אותו q עם כל cursor.

listArchived(params?)‎

מחזירה את רשימת המיקומים שלכם שבארכיון. המתודה היא קיצור של list({ archived: true }).

listArchived(params?: { limit?: number; cursor?: string }): Promise<{ locations: Location[]; nextCursor?: string | null }>

const { locations: archived } = await client.locations.listArchived()

get(id)‎

מחזירה מיקום אחד, עם pendingJobs, הווריאנטים שעדיין נוצרים, ועם previousCandidates, עד 5 מועמדים קודמים לתמונה הראשית, מהחדש לישן. כדי לקבוע אחד מהם כתמונה הראשית, קראו ל-approveMainImage().

get(id: string): Promise<LocationDetail>

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.

create(input: CreateLocationInput): Promise<{ id: string }>

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

update(id: string, input: UpdateLocationInput): Promise<{ id: string; updatedAt: string }>

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) (שוחזר) ומחזיר את השם שנקבע.

delete(id: string): Promise<{ success: true; archived: true }>
restore(id: string): Promise<{ id: string; name: string }>

await client.locations.delete(locationId)
const { name } = await client.locations.restore(locationId)

generate(input)‎

יוצרת מועמדים לשוט הפותח (POST /v1/generate-location). כש-count גדול מ-1, הקרדיטים לכל המשימות משוריינים לפני שמשימה כלשהי מתחילה, ולכן כשל באמצע הדרך מבטל את האצווה כולה.

generate(input: GenerateLocationInput): Promise<{ jobIds: string[]; jobId?: string }>

// 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 הוא כמו ברכיב יצירת תמונה. גם ערך מהרשימה שהמודל לא תומך בו לא נדחה. Nodaro משתמש במקומו בערך שהמודל תומך בו, או משמיט את ההגדרה כשאין למודל הגדרה כזו. הקרדיטים נקבעים לפי הערך שרץ בפועל, והשדה input_data של המשימה מציג אותו.

generateAsset(input)‎

יוצרת וריאנט אחד של המיקום (POST /v1/generate-location-asset). עם attachToLocationId, attachToColumn ו-attachName, התוצאה מתווספת לקבוצה הזו כשהמשימה מסתיימת.

generateAsset(input: GenerateLocationAssetInput): Promise<{ jobId: string }>

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.

generateSurroundContinuation(input: GenerateSurroundContinuationInput): Promise<{ jobId: string }>

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), בעזרת רכיב יצירת וידאו במצב תמונה לווידאו. למיקום יש קבוצת תנועה אחת, ולכן הקליפ תמיד נכנס ל-atmosphereMotions ואין attachToColumn.

generateMotion(input: GenerateLocationMotionInput): Promise<{ jobId: string }>

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 מעלות.

removeAsset(id: string, data: { column: LocationAttachColumn; url: string }): Promise<{ removed: true }>

await client.locations.removeAsset(locationId, { column: "angles", url: oldViewUrl })

המתודה זורקת NotFoundError כשהכתובת לא נמצאת בקבוצה הזו או כשהמיקום לא שייך לכם.

approveMainImage(id, candidateJobId)‎

קובעת מועמד שהושלם מ-generate() כתמונה הראשית של המיקום. אחר כך מודל ראייה כותב את התיאור של המיקום, והמתודה מחזירה את שניהם.

approveMainImage(id: string, candidateJobId: string): Promise<{ sourceImageUrl: string; canonicalDescription: string | null }>

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

השדה canonicalDescription הוא null כשאי אפשר היה לכתוב את התיאור. התמונה הראשית בכל זאת נקבעת; קראו ל-recaption() כדי לנסות שוב.

recaption(id)‎

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

recaption(id: string): Promise<{ canonicalDescription: string }>

const { canonicalDescription } = await client.locations.recaption(locationId)

המתודה נכשלת עם 400 no_source_image כשאין למיקום תמונה ראשית, ועם 502 כשמודל הראייה נכשל.