דמויות

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

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

נקודות קצה

אימון מודל ייעודי על דמות הוא יכולת של Nodaro Cloud עם נתיבים משלה. ראו את דף ה-API אימון דמויות.

מה דמות כוללת

דמות היא זהות שמורה אחת. השדות שבטבלה חוזרים מ-GET /v1/characters/:id ב-camelCase.

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

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

רשימת דמויות

הנתיב GET /v1/characters מחזיר עמוד אחד של הדמויות שלכם, מהחדש לישן. המשיכו לבקש עמודים עד ש-nextCursor הוא null: בחשבון שיש בו יותר דמויות מגודל העמוד, תגובה אחת אף פעם לא כוללת את כל הדמויות.

CURSOR=""
while :; do
  PAGE=$(curl -s "https://app.nodaro.ai/v1/characters?limit=100${CURSOR:+&cursor=$CURSOR}" \
    -H "Authorization: Bearer $NODARO_API_KEY")
  echo "$PAGE" | jq -r '.characters[] | "\(.id) \(.name)"'
  CURSOR=$(echo "$PAGE" | jq -r '.nextCursor // empty')
  [ -z "$CURSOR" ] && break
done

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

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

const all = []
let cursor: string | undefined
do {
  const page = await client.characters.list({ limit: 100, cursor })
  all.push(...page.characters)
  cursor = page.nextCursor ?? undefined
} while (cursor)

nodaro characters list --limit 100 --json
nodaro characters list --archived

{
  "characters": [
    {
      "id": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
      "name": "Kira",
      "description": "young protagonist with auburn hair",
      "sourceImageUrl": "https://cdn.nodaro.ai/characters/kira-portrait.png",
      "expressions": [{ "name": "smile", "url": "https://cdn.nodaro.ai/characters/kira-smile.png" }]
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA5LTIwVDEwOjAwOjAxWiJ9"
}

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

חיפוש לפי שם או תיאור

הנתיב GET /v1/characters?q=red%20car מחזיר רק את הדמויות שהשם או התיאור שלהן כוללים את כל המילים שב-q, בלי הבדל בין אותיות גדולות לקטנות. לכן הערך red car מוצא גם את "Car, red". הנתיבים GET /v1/locations, GET /v1/objects, GET /v1/creatures ו-GET /v1/faces מקבלים את אותו q ומחפשים באותם שני שדות.

• מילים. הערך של q מפוצל לפי רווחים, והחיפוש כולל רק את 5 המילים הראשונות. כל מילה יכולה להופיע בשם או בתיאור, בכל סדר, אבל כולן חייבות להופיע.
• כל תו במילה נבדק כמו שהוא. התווים %, _ ו-* הם לא תווים כלליים, והפיסוק נשמר: הערך Smith, מתאים רק לטקסט שכולל את הפסיק. השתמשו בקידוד URL רגיל: השאילתה ?q=100%25 מחפשת את 100%.
• ערך ריק פירושו שאין חיפוש. רווחים בהתחלה ובסוף לא נלקחים בחשבון, וכשהערך של q ריק, הרשימה כוללת הכול. ערך של יותר מ-200 תווים נדחה עם 400 validation_error.
• אפשר לשלב את q עם כל מסנן אחר ועם הדפדוף בין העמודים: למשל עם projectId, ועם archived=true כדי לחפש בארכיון. המשיכו לשלוח את אותו q עם כל cursor. התוצאות שומרות על הסדר של הרשימה, מהחדש לישן.
• החיפוש לא כולל את הכיתוב שנוצר, רק את השם ואת התיאור שנתתם.

curl -s -H "Authorization: Bearer $NODARO_API_KEY" "https://app.nodaro.ai/v1/characters?q=maya&limit=20"

ב-SDK, העבירו את q: client.characters.list({ q: 'maya pilot' }). ב-CLI, הריצו nodaro characters list --search "maya pilot". כלי ה-MCP list_characters מקבל את אותו חיפוש בפרמטר search.

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

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

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

curl -X POST https://app.nodaro.ai/v1/characters \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Kira",
    "description": "young protagonist with auburn hair",
    "style": "realistic",
    "seedPrompt": "kira portrait, warm natural lighting"
  }'

const { id } = await client.characters.create({
  nodeId: 'scripted',
  name: 'Kira',
  description: 'young protagonist with auburn hair',
  style: 'realistic',
  seedPrompt: 'kira portrait, warm natural lighting',
})

await client.characters.update(id, { gender: 'female', identityLock: 'soft' })

nodaro characters create --name "Kira" \
  --description "young protagonist with auburn hair" \
  --style realistic --seed-prompt "kira portrait, warm natural lighting"

nodaro characters update <id> --gender female

{ "id": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94", "name": "Kira" }

השדות person ו-wardrobe משפיעים רק על היצירות של הפורטרט ושל הווריאנטים של הדמות עצמה. הם משתמשים באותם קטלוגים כמו הבורר אדם; ראו את הדף קטלוגי הבוררים.

כשתהליך רץ, השדה voice של הדמות ממלא את ההגדרות של כל רכיב טקסט לדיבור שמחובר אחרי הדמות: הקול, סוג הקול והמודל המומלץ. ערך שהוגדר ברכיב טקסט לדיבור עצמו גובר.

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

הנתיב POST /v1/generate-character מתחיל משימה אחת לכל מועמד ומחזיר מיד את המזהים שלהן. בדקו את הסטטוס של כל משימה מדי כמה שניות דרך ה-API של המשימות, עד שהוא completed.

עם attachToCharacterId, כל מועמד שמסתיים נכתב לפורטרט של הדמות, ולכן המועמד שמסתיים אחרון גובר. למועמד יחיד זה כל מה שצריך. כשיש כמה מועמדים, אשרו את המועמד שאתם מעדיפים; האישור מחליף את הפורטרט. כדי שאף מועמד לא ייכתב לפורטרט עד שתאשרו אחד מהם, הוסיפו attachPortrait: false.

curl -X POST https://app.nodaro.ai/v1/generate-character \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "seedPrompt": "kira portrait, warm natural lighting",
    "count": 4,
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94"
  }'

const { jobIds } = await client.characters.generate({
  name: 'Kira',
  seedPrompt: 'kira portrait, warm natural lighting',
  count: 4,
  attachToCharacterId: id,
})

nodaro characters generate <id> --count 4 \
  --seed-prompt "kira portrait, warm natural lighting" --watch

{
  "jobId": "a1c4e8f2-5b3d-4e6a-8f7c-2d9b1e0a3c5f",
  "jobIds": [
    "a1c4e8f2-5b3d-4e6a-8f7c-2d9b1e0a3c5f",
    "b7d2f9a1-6c4e-4a8b-9d3f-3e0c2f1b4d6a",
    "c3e5a7b9-8d1f-4c2e-a6b8-4f1d3a2c5e7b",
    "d9f1b3c5-2e4a-4d6f-b8c1-5a2e4b3d6f8c"
  ]
}

השדות quality ו-resolution קובעים את המחיר של המשימה בדיוק כמו ברכיב יצירת תמונה: הרצה ב-4K או באיכות גבוהה עולה יותר מהרצה של אותו מודל ברמת הבסיס שלו. כשהמודל לא מקבל ערך מהרשימה, הבקשה לא נדחית. Nodaro משתמש במקומו בערך שהמודל תומך בו, או משמיט את ההגדרה כשאין למודל הגדרה כזו. הקרדיטים נקבעים לפי הערך שרץ בפועל. הנתיבים האלה לא מחזירים רשימת adjustments; את הערך שרץ בפועל קוראים ב-input_data של המשימה, מ-GET /v1/jobs/:id.

תיאור מי שמופיע בפורטרט

השדה subject הוא אובייקט אופציונלי של מזהי בוררים שמתארים מי מופיע בתמונה: הגיל, השיער והסטיילינג של אדם, אביזר יד, חומר או חיה. הוא מקבל את אותם מפתחות ואת אותן מגבלות כמו ה-subject של POST /v1/generate-image. Nodaro כותב את הניסוח ומוסיף אותו לפרומפט, מיד אחרי seedPrompt או description ואחרי הבחירות של הדמות עצמה ב-person וב-wardrobe. בחירה שמופיעה בשניהם באותו ניסוח נכתבת פעם אחת. שלחו את המזהים במקום לכתוב את המילים ב-seedPrompt, כדי שכל מקום ב-Nodaro ינסח בחירה אחת באותו אופן.

• השדה subject הוא לא פרומפט בפני עצמו: הנתיב עדיין צריך seedPrompt, referencePhotos או description.
• אין עליו תוספת מחיר.
• שדה subject שהגיל בו הוא של קטין מפעיל את אותם אמצעי הגנה לקטינים כמו הגדרת ה-person של הדמות עצמה.
• הנתיב POST /v1/generate-creature מקבל את אותו subject.

{
  "name": "Kira",
  "seedPrompt": "kira portrait, warm natural lighting",
  "subject": { "type": "woman", "age": "age-30s", "hairBase": "base-short-straight" }
}

יצירת הבעה, זווית, תנוחה או וריאציית תאורה

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

curl -X POST https://app.nodaro.ai/v1/generate-character-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "assetType": "expressions",
    "variant": "smile",
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
    "attachToColumn": "expressions",
    "attachName": "smile"
  }'

await client.characters.generateAsset({
  name: 'Kira',
  assetType: 'bodyAngles',
  variant: 'front',
  attachToCharacterId: id,
  attachToColumn: 'body_angles',
  attachName: 'front',
})

nodaro characters generate-asset <id> --asset-type expressions --variant smile --watch

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

הנפשת הדמות

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

כשמצרפים לדמות, Nodaro בוחר את פריים הפתיחה לפי הסדר הזה:

1. ה-sourceImageUrl שאתם שולחים, שתמיד גובר.
2. הפריט front ב-bodyAngles. פריים של גוף מלא מונפש טוב בהרבה מפורטרט של ראש וכתפיים.
3. כל פריט אחר ב-bodyAngles, מהחדש לישן.
4. פורטרט העוגן.

כדי לקבל את הקליפים הטובים ביותר, צרו זווית גוף front לפני התנועה הראשונה.

curl -X POST https://app.nodaro.ai/v1/generate-character-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kira",
    "motionPrompt": "slow head turn left, soft smile",
    "provider": "kling",
    "attachToCharacterId": "3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94",
    "attachName": "head turn"
  }'

await client.characters.generateMotion({
  name: 'Kira',
  motionPrompt: 'slow head turn left, soft smile',
  provider: 'kling',
  attachToCharacterId: id,
  attachName: 'head turn',
})

nodaro characters generate-motion <id> \
  --motion-prompt "slow head turn left, soft smile" --attach-name "head turn" --watch

המודלים האלה יכולים להנפיש דמות. המחיר הוא המחיר של המודל ליצירה מתמונה לווידאו:

אישור פורטרט

הנתיב POST /v1/characters/:id/approve-portrait קובע מועמד שהושלם כפורטרט העוגן. באותה קריאה, Nodaro בוחן את הפורטרט וכותב את canonicalDescription, הטקסט שפרומפטים מאוחרים יותר משתמשים בו כדי לתאר את הדמות. בלי התיאור הזה, הדמות משתנה הרבה יותר בין סצנות.

המועמד חייב להיות משימה שלכם בסטטוס completed. אם כתיבת התיאור נכשלת, הפורטרט בכל זאת נקבע והשדה canonicalDescription הוא null; קראו לנתיב POST /v1/characters/:id/llm-caption כדי לנסות שוב. אפשר לחזור על הקריאה לשני הנתיבים בלי חשש. האישור עצמו לא עולה קרדיטים. כתיבת התיאור היא קריאה למודל הראייה Claude Sonnet 4.6, שמחויבת לפי הטוקנים שהיא השתמשה בהם, בתעריף של המודל הזה. ראו את הסעיף איך מחויבות קריאות LLM בדף קרדיטים. אישור אף פעם לא נדחה בגלל קרדיטים. כשהיתרה לא מספיקה לתיאור, התמונה בכל זאת מאושרת, התיאור לא נכתב, והנתיב llm-caption יכול לכתוב אותו מאוחר יותר. על תיאור שהספק חייב עליו משלמים, גם כשהוא חוזר ריק. על תיאור שהספק לא חייב עליו, הקרדיטים מוחזרים.

curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/approve-portrait \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "b7d2f9a1-6c4e-4a8b-9d3f-3e0c2f1b4d6a" }'

const { portraitUrl, canonicalDescription } =
  await client.characters.approvePortrait(id, jobIds[1])

if (canonicalDescription === null) {
  await client.characters.recaption(id)
}

nodaro characters approve-portrait <id> --job <jobId>
nodaro characters recaption <id>

{
  "portraitUrl": "https://cdn.nodaro.ai/characters/kira-portrait-2.png",
  "canonicalDescription": "Kira is a woman in her mid-twenties with shoulder-length auburn hair, green eyes and light freckles..."
}

הנתיב llm-caption מחזיר { canonicalDescription }. הנתיב מחזיר 400 no_portrait כשלדמות עדיין אין פורטרט, ו-502 כשלא היה אפשר לכתוב את התיאור.

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

העברה לארכיון, שחזור ושכפול של דמות

• העברה לארכיון. הנתיב DELETE /v1/characters/:id מעביר את הדמות לארכיון ומחזיר { success: true, archived: true }. הדמות יוצאת מרשימת ברירת המחדל, אבל הנתיב GET /v1/characters/:id עדיין מחזיר אותה, ולכן תהליכים שמשתמשים בה ממשיכים לעבוד. ב-Nodaro Cloud, ההעברה לארכיון גם מבטלת אימון שבעיצומו ומסירה את המודל המאומן, והקרדיטים על האימון מוחזרים.
• שחזור. הנתיב POST /v1/characters/:id/restore מחזיר { id, name }. אם בינתיים יש לדמות פעילה אחרת אותו שם, Nodaro מוסיף את הסיומת (restored) (שוחזר) ומחזיר את השם החדש.
• מחיקה לצמיתות. אין נתיב API שמוחק דמות לצמיתות. השתמשו בתצוגת הארכיון בספרייה של העורך.
• שכפול. הנתיב POST /v1/characters/:id/duplicate מחזיר { id, name } של דמות חדשה עם הסיומת (copy) (עותק). העותק משתמש באותן כתובות של תמונות וקליפים כמו המקור, עד שתיצרו אותם מחדש.
• שימוש. הנתיב GET /v1/characters/:id/usage מחזיר { workflowCount, workflows: [{ id, name }] }. בדקו אותו לפני שאתם מעבירים דמות לארכיון.

רצף מלא: יצירה, מועמדים, אישור והוספת וריאנטים

שימוש בדמות ביצירות אחרות

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

בתהליך, חברו את רכיב נכס דמות לרכיב התמונה או הווידאו, או הזכירו את הדמות בפרומפט עם @, למשל @kira:1:smile. המדריך תפקידי ייחוס מסביר את הדקדוק של האזכורים, והמדריך דמויות עקביות את השיטה המלאה.

שימוש דרך MCP

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

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

קרדיטים

ב-Nodaro Cloud, המחירים בקרדיטים של יצירת דמויות זהים למחירים של הרכיבים המקבילים.

המחיר המדויק מופיע בדף של כל מודל. ראו את הדף קרדיטים.

שגיאות

השגיאות משתמשות במעטפת הסטנדרטית, { "error": { "code", "message" } }. ראו את דף ה-API שגיאות.