סצנות תלת־ממד

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

רינדור תלת־ממד Pro הוא פעולה נפרדת שיוצרת ומרנדרת שוט מוגמר במשימה אחת בתשלום, בפריסות שיש בהן מנוע בשבילה. מנוע היצירה הבסיסי עובד בכל מהדורה; הזמינות של המנועים המתקדמים ושל רינדור תלת־ממד Pro משתנה מפריסה לפריסה, ולכן בדקו קודם את היכולות של הפריסה. חיוב בקרדיטים קיים רק ב-Nodaro Cloud. הנתיבים מקבלים אסימון Bearer. ראו את דף ה-API אימות.

נקודות קצה

הנתיבים POST /v1/generate-3d-scene ו-POST /v1/edit-3d-scene הם שמות חלופיים של נתיבי היצירה והעריכה, עם אותן בדיקות ואותו חיוב בקרדיטים. גם הנתיב POST /v1/render-video מקבל את planType ואת plan. השמות החלופיים האלה מאפשרים למריץ הרכיבים הכללי של ה-SDK להגיע לאותם נתיבים.

בדיקת היכולות של הפריסה

הנתיב GET /v1/3d-scene/capabilities מדווח על התמיכה במנוע הבסיסי ומחזיר את השדה advanced, שערכו null כשאין מנוע מתקדם זמין. השדה pro מציין אם רינדור תלת־ממד Pro זמין (available), ומפרט את המנועים, פרופילי האיכות, הסגנונות, יחסי הגובה־רוחב ותקרת מעברי התיקון שאפשר להציע. בנו את הבקרות שלכם לפי התשובה הזו, לא לפי רשימת הערכים המלאה.

בקשה למנוע שהפריסה לא יכולה לספק נדחית עם 503 SCENE_CAPABILITY_UNAVAILABLE, עוד לפני בדיקת הקרדיטים. Nodaro אף פעם לא עובר מעצמו ליצירה במנוע הבסיסי. גם הנתיב GET /v1/nodes משמיט את רכיב רינדור תלת־ממד Pro כשהוא לא זמין, ומציין ברכיב יצירת סצנת תלת־ממד את היכולת scene3d-embed-v1 כשההטמעה האינטראקטיבית של התצוגה התלת־ממדית זמינה.

יצירת סצנה

הנתיב POST /v1/3d-scene/generate יוצר סצנה חדשה ומחזיר { jobId }. בדקו את סטטוס המשימה מדי כמה שניות דרך ה-API של המשימות; ב-output_data.scenePlan של המשימה שהושלמה נמצאת הסצנה שאפשר לערוך.

curl -X POST https://app.nodaro.ai/v1/3d-scene/generate \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red suitcase rolls behind a central pillar and reappears. Dolly right over four seconds.",
    "durationSeconds": 4,
    "fps": 24,
    "aspectRatio": "16:9",
    "references": [
      { "id": "suitcase-appearance", "kind": "image", "role": "appearance", "url": "https://cdn.nodaro.ai/uploads/suitcase.png" }
    ]
  }'

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

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const scene = await client.nodes.runAndWait('generate-3d-scene', {
  prompt: 'A red suitcase rolls behind a central pillar and reappears. Dolly right over four seconds.',
  durationSeconds: 4,
  fps: 24,
  aspectRatio: '16:9',
  references: [{ id: 'suitcase-appearance', kind: 'image', role: 'appearance', url: appearanceImageUrl }],
})

nodaro nodes run generate-3d-scene --params-file scene.json --watch --json

• ייחוסים נותנים קירוב בלבד. תמונה לא חושפת גאומטריה שלא רואים בה, והמודל רואה בסרטון קו מנחה לתנועה ולפריסה. בדקו את התצוגה המקדימה לפני הרינדור.
• קליפים שלמים בלבד. ייחוס וידאו מנותח בשלמותו. כדי להשתמש בחלק מקליפ, קצצו אותו קודם ברכיב קיצוץ וידאו; חלון זמן חלקי נדחה עוד לפני שמוציאים קרדיטים.
• גאומטריה שמורה. השדה inputAssets בוחר גרסאות מסוימות של קובצי GLB שכבר יש לכם. השרת בודק בעצמו את הגישה שלכם ואת הגיבוב של הקובץ, ולכן אל תשלחו כתובות URL או גיבובים, והשאירו תמונות וסרטונים ב-references. המנוע הבסיסי דוחה גאומטריה מיובאת לפני כל חיוב.
• קואורדינטות. הסצנות משתמשות במטרים, כשציר Y מצביע למעלה, הסיבובים ברדיאנים והפריימים נספרים מאפס.
• קרדיטים. ב-Nodaro Cloud, יצירה במנוע הבסיסי מחויבת לפי הטוקנים שהקריאה שלה למודל השפה השתמשה בהם: הפרומפט שלכם, התיאורים של הייחוסים, טקסט ניתוח הווידאו אם יש כזה, ותוכנית הסצנה שהמודל כותב. התעריף הוא התעריף של המודל שנבחר, בשירות שטיפל בקריאה. קודם משוריינים קרדיטים. פרומפט ארוך, הרבה ייחוסים או מעבר תיקון עולים יותר. על כשל שהספק חייב עליו משלמים לפי השימוש הזה, ועל כשל שלא חויב הקרדיטים מוחזרים. הנתיב POST /v1/credits/model-costs עם המפתח 3d-scene:<model> מחזיר אומדן של הרצה טיפוסית. ראו את הסעיף איך מחויבות קריאות LLM בדף קרדיטים.

עריכת סצנה

הנתיב POST /v1/3d-scene/edit מקבל את scenePlan, את ה-revisionId שלו בתור expectedRevisionId, ואחד משני אלה: prompt, כלומר הוראה כמו "move the pillar back one meter" (הזז את העמוד מטר אחד אחורה), או operations. עריכה שמצליחה יוצרת גרסה חדשה שה-parentRevisionId שלה הוא הגרסה הישנה; התוכנית ששלחתם נשארת ללא שינוי. בקשה עם גרסה שלא תואמת נדחית. המשימה שהושלמה מחזירה scenePlan ו-changeSummary.

curl -X POST https://app.nodaro.ai/v1/3d-scene/edit \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @edit.json

# edit.json:
# { "scenePlan": { ... }, "expectedRevisionId": "rev_7c2e...",
#   "operations": [{ "op": "set-camera", "changes": { "focalLengthMm": 50 } }] }

const edited = await client.nodes.runAndWait('edit-3d-scene', {
  scenePlan: scene.scenePlan,
  expectedRevisionId: scene.scenePlan.revisionId,
  operations: [{ op: 'set-camera', changes: { focalLengthMm: 50 } }],
})

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

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

שמירת עריכות בסצנה שמורה

בסצנה שמורה בגרסת פורמט 2, הנתיב POST /v1/3d-scene/revisions/:revisionId/edits שומר עריכות דטרמיניסטיות (טרנספורמציות, צבעי חומרים, נראות והיסטי מצלמה) בלי משימה ובלי חיוב על מודל שפה. שלחו newRevisionId, את ה-expectedContentHash של גרסת הבסיס, את operations, ובאופן אופציונלי גם lockedObjectIds. הנתיב מחזיר { scenePlan, changeSummary }.

גיבוב תוכן לא עדכני או מזהה גרסה מתנגש נדחים עם 409. כשבקשה נכשלת בזמן ההעברה, שלחו אותה שוב עם אותו newRevisionId ואותו גוף בקשה. הנתיב דורש הרשאת עריכה בסצנה, ואסימונים של אפליקציות OAuth צריכים את ההרשאה workflows:write. הגרסה החדשה נשמרת בנפרד; בחרו בה בתהליך שלכם בעצמכם, אחרי שבדקתם שאף אחד לא שינה בינתיים את הגרסה הפעילה.

רינדור סצנה ל-MP4

הנתיב POST /v1/render-video/plan עם { "planType": "3d-scene", "plan": scenePlan } מרנדר גרסה מסוימת אחת. המצלמה, גודל הפריים, קצב הפריימים ומשך הסרטון נלקחים מהתוכנית; לא קוראים לאף מודל שפה, והפרומפט לא נקרא שוב. המשימה שהושלמה מחזירה videoUrl, thumbnailUrl, sceneRevisionId ו-renderer: "scene3d/three".

curl -X POST https://app.nodaro.ai/v1/render-video/plan \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"planType\": \"3d-scene\", \"plan\": $(cat scene-plan.json) }"

const clip = await client.nodes.runAndWait('render-video', {
  planType: '3d-scene',
  plan: edited.scenePlan,
})

המחיר של רינדור נקבע לפי ה-width וה-height של התוכנית עצמה:

כל יחס גובה־רוחב שנתיב היצירה מציע מרונדר ב-1920 פיקסלים או פחות, ולכן על סצנה שלא שיניתם את הגודל שלה תמיד משלמים את מחיר הבסיס. המדרגות הגדולות יותר חלות רק כשאתם עצמכם קובעים בתוכנית width ו-height גדולים יותר. המזהים של עלויות המודל הם render-video, render-video:3d-large ו-render-video:3d-xlarge.

שימוש ברינדור כייחוס וידאו

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

1. תמיד תחמו את הייחוס. העבירו את ה-MP4 ב-referenceVideoUrls[N] של רכיב יצירת וידאו, עם כיתוב ב-referenceVideoCaptions[N] שאומר למה להתאים וממה להתעלם. בתהליך, Nodaro מוסיף את הכיתוב הזה בשבילכם. זה הנוסח שלו: "LAYOUT reference only — match its subject positions and blocking, its foreground occlusion, its framing, its camera angle, its camera motion and its timing. Ignore its untextured grey clay placeholder look, its flat placeholder colours, its materials, its lighting and its empty background; none of that is the target look. Take the look from the prompt and from the other references" (ייחוס פריסה בלבד — להתאים למיקומי הנושאים ולהעמדה שבו, להסתרה בקדמת הפריים, למסגור, לזווית המצלמה, לתנועת המצלמה ולתזמון שלו. להתעלם ממראה החימר האפור והזמני ללא טקסטורה, מהצבעים השטוחים הזמניים, מהחומרים, מהתאורה ומהרקע הריק שלו; שום דבר מאלה הוא לא המראה הרצוי. לקחת את המראה מהפרומפט ומהייחוסים האחרים).
2. תנו לכל דמות שצריכה להיראות אמיתית ייחוס דמות משלה. דמות בלי ייחוס כזה נשארת דמות חימר ממלאת מקום. השאירו שתי משבצות ייחוס פנויות לתמונת מיקום או לתמונת סגנון.

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

הרצת רינדור תלת־ממד Pro

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

curl -X POST https://app.nodaro.ai/v1/pro-3d-render/quote \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @pro.json

curl -X POST https://app.nodaro.ai/v1/pro-3d-render \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Idempotency-Key: suitcase-shot-0001" \
  -H "Content-Type: application/json" \
  -d @pro-with-quote.json

const caps = await client.scene3d.capabilities()
if (caps.pro?.available) {
  const params = {
    source: {
      kind: 'prompt' as const,
      prompt: 'A red suitcase rolls behind a central pillar and reappears',
      references: [{ id: 'look', kind: 'image' as const, role: 'appearance' as const, url: appearanceImageUrl }],
    },
    durationSeconds: 30,
    fps: 24,
    aspectRatio: '21:9',
    maxRepairPasses: 2,
    acceptedSceneSchemaVersions: [2],
  }
  const quote = await client.scene3d.quotePro(params)
  console.log(quote.maxCredits, quote.breakdown)
  const shot = await client.scene3d.renderProAndWait({ ...params, quoteId: quote.quoteId })
  console.log(shot.videoUrl, shot.sceneRevisionId)
}

השדה source בגוף הבקשה הוא אחד בדיוק מאלה:

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

מה מחזירה הרצה שהסתיימה

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

בדקו קודם אם השדה metadata.review קיים, ואז בדקו את השדה verdict שלו. הערך refused פירושו שהבדיקה החזותית עדיין הסתייגה מהסצנה כשתקציב התיקונים נגמר, והשדה objections מפרט את ההסתייגויות שלה. הערך unavailable פירושו שהבדיקה לא נתנה הכרעה שאפשר להשתמש בה, כך שאף אחד לא שפט את הסצנה. בשני המקרים השדה validation.status הוא עדיין passed, כי בדיקות החובה אכן עברו. רשימת קודי האזהרה פתוחה; התייחסו לקוד שאתם לא מכירים כאל מידע בלבד. ראו את הדף רינדור תלת־ממד Pro לכל השדות ולכל קודי האזהרה.

כשהרצה נכשלת

שגיאות בשליחת הבקשה הן דחיות: 503 SCENE_CAPABILITY_UNAVAILABLE, 503 price_not_configured (מנהל השרת לא קבע מחיר; שום דבר לא שוריין) ו-400 validation_error. כשלים במהלך ההרצה מופיעים במשימה, והודעת השגיאה מתחילה בקוד:

משימה שנכשלה במנוע מתקדם עדיין יכולה לכלול את מה שהיא בנתה. כשמעבר בנה סצנה, ב-output_data נמצאת הטיוטה: scenePlan, sceneRevisionId, deliveryId, posterAssetId ו-validation עם status: "failed". הטיוטה היא גרסה רגילה שאפשר לערוך או לרנדר. כשאף מעבר לא עבר הידור, אין טיוטה, אבל השדה validation.sourceRetained מציין אם המתכון שנדחה נשמר; קבלו אותו מהמתאר source-json של המסירה, עם הרשאת עריכה, בחינם. אם במקום זאת מריצים שוב את אותו פרומפט, משלמים פעמיים על אותה יצירה.

בהרצת תהליך, התוצאה של רכיב שנכשל ושמר תוצאה מופיעה גם ב-nodeStates[nodeId].output. בדקו אם השדה קיים, לא את הסטטוס, ולעולם אל תראו ב-output קיים סימן להצלחה.

גרסאות הפורמט של הסצנה והקבצים השמורים

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

תוכנית בגרסת פורמט 2 מפרטת כל קובץ לפי assetId אטום, האורך שלו בבייטים וגיבוב ה-SHA-256 שלו; היא אף פעם לא כוללת מפתח אחסון או כתובת URL להורדה. גרסה 2 מקבלת גאומטריית חימר עם אנימציה קשיחה; קבצים עם טקסטורות, עם skinning או עם morph targets נדחים. המגבלות שלה הן 100 ישויות, 200,000 משולשים, 32 שוטים, 64 MiB של קבצי ניגון ו-2,000 צמתי mesh. הפורמט המלא מתואר בדף פורמט תוכנית הסצנה.

לגרסאות שמורות יש נתיבים משלהן. הנתיבים האלה דורשים אסימון Bearer, עונים עם Cache-Control: no-store, ומחזירים 404 לגרסה שנמחקה או שאין אליה גישה:

• הנתיב GET /v1/3d-scene/revisions/:revisionId מחזיר את המניפסט ואת המתארים של הקבצים. קובצי ניגון דורשים הרשאת צפייה בתהליך של הגרסה; קובץ המקור דורש הרשאת עריכה. גרסאות אישיות זמינות רק לבעלים שלהן.
• הנתיב GET /v1/3d-scene/deliveries/:jobId מחזיר את מה שייצוא מסר: sourceKind, את ה-sceneRevisionId המדויק, את הגיבובים של המקור ואת המתארים (הפוסטר, דוח הבדיקה ו-shot-still אחד לכל שוט). הנתיב …/assets/:assetId מחזיר את הבייטים, עם תמיכה בבקשות Range. קריאות דורשות גישה גם למסירה וגם לתהליך המקור, והן לא עולות כלום.

ב-SDK, המתודות client.scene3d.getDelivery, deliveryAssetBytes, retainedRecipe, assetBytes, sourceBytes ו-applyEdits עוטפות את הנתיבים האלה.

שימוש דרך MCP

עוזרי AI משתמשים בכלים generate_3d_scene, edit_3d_scene ו-render_3d_scene עם ההרשאה workflows:execute, ובכלי pro_3d_render בפריסות שיכולות להריץ אותו. ראו את הדף סצנות תלת־ממד דרך MCP. כדי להציג סצנה בדף משלכם, ראו את הדף הטמעת התצוגה התלת־ממדית.

שגיאות