יצורים

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

הנתיבים עובדים בכל המהדורות. הם מקבלים אסימון Bearer: אסימון API אישי (ndr_…), אסימון של אפליקציית OAuth (ndr_app_…), או אסימון הסשן שלכם במהדורת Community. ראו את דף ה-API אימות. ל-CLI אין פקודות ליצורים; השתמשו ב-REST API, ב-SDK או ב-MCP.

נקודות קצה

מה יצור כולל

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

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

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

curl "https://app.nodaro.ai/v1/creatures?limit=50" \
  -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 { creatures, nextCursor } = await client.creatures.list({ limit: 50 })
const { creatures: archived } = await client.creatures.listArchived()

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

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

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

curl -X POST https://app.nodaro.ai/v1/creatures \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Ember",
    "species": "red dragon",
    "description": "Young dragon with copper scales and a chipped left horn",
    "style": "realistic"
  }'

const { id } = await client.creatures.create({
  nodeId: 'scripted',
  name: 'Ember',
  species: 'red dragon',
  description: 'Young dragon with copper scales and a chipped left horn',
  style: 'realistic',
})

await client.creatures.update(id, {
  voice: { voiceId: 'Callum', voiceName: 'Callum', traits: 'gravelly, slow', voiceType: 'premade' },
})

לוחות

לוח הוא גיליון ייחוס צפוף של היצור, למראה אחד או למצב־רוח אחד. רנדרו לוח עם הערכה generate-image/creature-board של רכיב יצירת תמונה, ואז שמרו את הכתובת שלו ב-boards. ראו את דף ה-API ערכות ואת המדריך לוחות ייחוס.

יצירת תמונות ראשיות ווריאנטים

הנתיב POST /v1/generate-creature מתחיל משימה אחת לכל מועמד ומחזיר jobIds; בקשה עם מועמד אחד מחזירה גם jobId. עם attachToCreatureId ו-count של 1, התוצאה הופכת לתמונה הראשית כשהמשימה מסתיימת. כשיש כמה מועמדים, שום דבר לא מצורף ליצור; אשרו את המועמד שאתם מעדיפים. שדה subject אופציונלי של מזהי בוררים מתאר מי מופיע בתמונה, כמו ב-POST /v1/generate-character.

הנתיב POST /v1/generate-creature-asset יוצר וריאנט אחד ומחזיר { jobId }. הערך של assetType הוא angles, poses, variations או custom. כדי להוסיף את התוצאה לקבוצה, שלחו attachToCreatureId, attachToColumn (angles, poses או variations) ו-attachName; וריאנט custom חייב לציין את העמודה שלו.

curl -X POST https://app.nodaro.ai/v1/generate-creature \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "species": "red dragon",
    "count": 1,
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a"
  }'

curl -X POST https://app.nodaro.ai/v1/generate-creature-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "assetType": "poses",
    "variant": "wings spread",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachToColumn": "poses",
    "attachName": "wings spread"
  }'

const { jobIds } = await client.creatures.generate({
  name: 'Ember',
  species: 'red dragon',
  count: 4,
})

await client.creatures.generateAsset({
  name: 'Ember',
  assetType: 'poses',
  variant: 'wings spread',
  attachToCreatureId: id,
  attachToColumn: 'poses',
  attachName: 'wings spread',
})

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

הנתיב POST /v1/generate-creature-motion הופך תמונה של היצור לקליפ, כגון לולאת מנוחה, התגנבות או התקפה, ומחזיר { jobId }. השדה sourceImageUrl נדרש. עם attachToCreatureId ו-attachName, הקליפ מתווסף לסוף motionClips.

curl -X POST https://app.nodaro.ai/v1/generate-creature-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ember",
    "motionPrompt": "slow idle breathing, tail sways, smoke curls from the nostrils",
    "sourceImageUrl": "https://cdn.nodaro.ai/creatures/ember-main.png",
    "attachToCreatureId": "0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a",
    "attachName": "idle"
  }'

await client.creatures.generateMotion({
  name: 'Ember',
  motionPrompt: 'slow idle breathing, tail sways, smoke curls from the nostrils',
  sourceImageUrl: ember.sourceImageUrl!,
  provider: 'kling-turbo',
  duration: 5,
  attachToCreatureId: id,
  attachName: 'idle',
})

המזהה seedance-2-mini הוא Seedance 2 Mini. Seedance 1.5 הוצא משימוש באוקטובר 2026: בקשה שעדיין מציינת seedance רצה ומתומחרת כמו seedance-2-mini.

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

הנתיב POST /v1/creatures/:id/approve-main-image עם { candidateJobId, expectedUpdatedAt? } קובע מועמד שהושלם כתמונה הראשית, וכותב את canonicalDescription באותה קריאה. הנתיב מחזיר { sourceImageUrl, canonicalDescription }. כשכתיבת התיאור נכשלת, התמונה הראשית בכל זאת נקבעת והתיאור ריק; ה-SDK מחזיר null.

הנתיב POST /v1/creatures/:id/llm-caption כותב את התיאור מחדש ומחזיר { canonicalDescription }. הנתיב מחזיר 502 כשלא היה אפשר לכתוב את התיאור, ו-400 main_image_required כשעדיין אין תמונה ראשית. אפשר לחזור על הקריאה לשני הנתיבים בלי חשש. האישור עצמו לא עולה קרדיטים. כתיבת התיאור היא קריאה למודל הראייה Claude Sonnet 4.6, שמחויבת לפי הטוקנים שהיא השתמשה בהם, בתעריף של המודל הזה. ראו את הסעיף איך מחויבות קריאות LLM בדף קרדיטים. אישור אף פעם לא נדחה בגלל קרדיטים. כשהיתרה לא מספיקה לתיאור, התמונה בכל זאת מאושרת, התיאור לא נכתב, והנתיב llm-caption יכול לכתוב אותו מאוחר יותר. על תיאור שהספק חייב עליו משלמים, גם כשהוא חוזר ריק. על תיאור שהספק לא חייב עליו, הקרדיטים מוחזרים.

curl -X POST https://app.nodaro.ai/v1/creatures/0b8d6f4a-2c1e-4b9d-8f3a-7e5c1d9b3f2a/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "1c9e7a5b-3d2f-4c8e-9a4b-8f6d2e1a4c3b" }'

const ember = await client.creatures.get(id)
const approved = await client.creatures.approveMainImage(id, jobIds[0], ember.updatedAt)
if (approved.canonicalDescription === null) await client.creatures.recaption(id)

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

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

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

יצור שמדבר

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

const speech = await client.nodes.runAndWait('text-to-speech', {
  text: 'I knocked the vase off the shelf. I regret nothing.',
  voice: ember.voice!.voiceId,
  provider: ember.voice!.ttsProvider,
  voiceType: ember.voice!.voiceType,
})

const clip = await client.nodes.runAndWait('lip-sync', {
  imageUrl: ember.sourceImageUrl!,
  audioUrl: speech.audioUrl,
  provider: 'kling-avatar',
})

ראו את דף ה-API הרצת רכיב יחיד לפרטים על nodes.runAndWait ועל הנתיבים הגולמיים POST /v1/<node-type>.

הכנסת יצור לשוט

ברכיב יצירת תמונה, העבירו את היצור כייחוס בפורמט מובנה עם source: "wired-creature". היצור מצורף אוטומטית, בניסוח ששומר על האנטומיה, הסימונים והצבעים שלו. אפשר גם להזכיר אותו בפרומפט: האזכור @ember:1 ממקם אותו במקום שבו הקלדתם אותו. תפקיד בוחר מה לקחת מהתמונה, למשל @ember:1:markings. התפקידים הם creature, anatomy, markings, pose, color ו-style.

{
  "prompt": "a wide shot of @ember:1 landing on the castle wall",
  "connectedReferences": [
    { "id": "cr-1", "defaultName": "Ember", "source": "wired-creature", "url": "https://cdn.nodaro.ai/creatures/ember-main.png" }
  ]
}

בתהליך, חברו במקום זאת את רכיב נכס חיה/יצור לרכיב התמונה או הווידאו.

שימוש דרך MCP

ראו את מדריך כלי ה-MCP.

קרדיטים

ב-Nodaro Cloud, על בקשה לתמונה ראשית משלמים את המחיר של מודל התמונה כפול count, והקרדיטים משוריינים לפני שהמשימה הראשונה מתחילה. על וריאנט משלמים את המחיר של מודל התמונה, ועל קליפ תנועה את המחיר של מודל הווידאו ליצירה מתמונה לווידאו. האישור לא עולה קרדיטים. כתיבת התיאור, באישור ובכל קריאה ל-llm-caption, היא קריאה למודל הראייה Claude Sonnet 4.6, שמחויבת לפי הטוקנים שהיא השתמשה בהם. אישור אף פעם לא נדחה בגלל קרדיטים: כשהיתרה לא מספיקה, התיאור לא נכתב.

שגיאות