# אימון דמויות

> אמנו מודל בנאמנות גבוהה של דמות ב-REST API, בדקו את מצב האימון, הסירו את המודל, ולמדו מתי רכיב יצירת תמונה משתמש במודל המאומן.

Source: https://nodaro.ai/he/docs/developers/api/character-training

**אימון דמויות** יוצר מודל ייעודי של דמות אחת מהתמונות שלה, לדמיון הקרוב ביותר ברכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image). מתחילים אימון בקריאה אחת, בודקים את הסטטוס שלו מדי כמה שניות עד שהוא מסתיים, ומסירים את המודל כשכבר אין בו צורך. אחרי האימון, רכיב יצירת תמונה משתמש במודל המאומן אוטומטית בכל פעם שפרומפט מזכיר את הדמות הזאת.

אימון דמויות רץ ב-Nodaro Cloud בלבד; בהתקנות באירוח עצמי הנתיבים לא קיימים ומחזירים `404`. בהתקנה באירוח עצמי, שמרו על דמות עקבית בעזרת הפורטרט המאושר ותמונות הייחוס שלה, כמו שמתואר בדף ה-API [דמויות](https://nodaro.ai/docs/developers/api/characters). הנתיבים מקבלים אסימון Bearer ופועלים רק על הדמויות שלכם. ראו את דף ה-API [אימות](https://nodaro.ai/docs/developers/api/authentication).

ה-SDK עוטף את הנתיבים במתודות `client.characters.train`, `trainingStatus` ו-`deleteLora`. ב-CLI, הריצו את הפקודות `nodaro characters train`, `training` ו-`delete-lora`. עוזר AI שמחובר דרך MCP מתחיל אימון עם הכלי `train_character` ובודק את המצב שלו עם הכלי `get_character`. אין כלי MCP שמסיר מודל מאומן.

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

## נקודות קצה
| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `POST` | `/v1/characters/:id/train` | התחלת אימון, עם שריון של 1,650 קרדיטים. |
| `GET` | `/v1/characters/:id/training` | קבלת הסטטוס של האימון. |
| `DELETE` | `/v1/characters/:id/lora` | ביטול אימון שבעיצומו, או הסרת המודל המאומן. |

## לפני האימון
לדמות צריכות להיות לפחות **4 תמונות שונות**. כברירת מחדל, Nodaro אוסף אותן מהדמות לפי הסדר הזה, מסיר כפילויות ומאמן את המודל על עד 20 מהן:

1. הפורטרט המאושר.
2. תמונות הייחוס.
3. ההבעות, התנוחות, זוויות הראש וזוויות הגוף.
4. וריאציות התאורה.

כדי לאמן על חלק מהתמונות, שלחו בגוף הבקשה `{ "selectedImageUrls": [...] }`: עד 200 כתובות URL של תמונות של הדמות עצמה. האימון משתמש אז רק בהן, ולפחות 4 מהן צריכות להישאר. כשהרשימה לא נשלחת או שהיא ריקה, האימון משתמש בכל התמונות שמתאימות לאימון.

גיליונות דמות לא נספרים, כי התצוגות בהם חוזרות על אותן זוויות. כשיש לדמות פחות מ-4 תמונות, צרו קודם כמה זוויות והבעות עם `POST /v1/generate-character-asset`; ראו בדף ה-API [דמויות](https://nodaro.ai/docs/developers/api/characters#generate-an-expression-angle-pose-or-lighting-variant).

## התחלת אימון
הנתיב `POST /v1/characters/:id/train` מתחיל את האימון. כשהאימון מתחיל, משוריינים לו 1,650 קרדיטים. הנתיב מחזיר `202` עם מזהה המשימה של האימון, מזהה האימון ומילת הטריגר של הדמות. אף פעם לא צריך להקליד את מילת הטריגר: Nodaro מוסיף אותה לפרומפטים בעצמו.

**curl**

```bash
curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY"

# Or train on a subset of the character's images
curl -X POST https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/train \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selectedImageUrls": ["https://cdn.nodaro.ai/characters/kira-portrait.png", "https://cdn.nodaro.ai/characters/kira-smile.png", "https://cdn.nodaro.ai/characters/kira-left.png", "https://cdn.nodaro.ai/characters/kira-right.png"]}'
```

**TypeScript SDK**

```ts

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

const training = await client.characters.train(characterId)
// Or a subset: client.characters.train(characterId, { selectedImageUrls: [...] })
```

```json
{
"jobId": "7a9c1e3b-5d2f-4b8a-9c6e-1f3d5b7a9c2e",
"trainingId": "q4m8x2k6p1",
"triggerWord": "TOK_kira_a1b2c3"
}
```

המשימה של האימון, `jobId`, מסתיימת יחד עם האימון בסטטוס `completed`, `failed` או `cancelled`, ולכן אפשר לבדוק את מצב האימון גם עם `GET /v1/jobs/:id/status`.

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

## מעקב אחרי האימון
הנתיב `GET /v1/characters/:id/training` מחזיר את מצב האימון. אימון לוקח כ-15 דקות. בדקו את הסטטוס בערך כל 10 שניות. ל-SDK אין פונקציית עזר שממתינה לסיום.

**curl**

```bash
curl https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/training \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

**TypeScript SDK**

```ts
let training = await client.characters.trainingStatus(characterId)
while (training.status === 'queued' || training.status === 'training') {
await new Promise((resolve) => setTimeout(resolve, 10_000))
training = await client.characters.trainingStatus(characterId)
}
if (training.status !== 'succeeded') console.warn(training.status, training.error)
```

```json
{
"status": "succeeded",
"trainingId": "q4m8x2k6p1",
"error": null,
"trainedAt": "2026-09-20T11:42:08Z",
"version": "b81f4c0e9d27",
"triggerWord": "TOK_kira_a1b2c3",
"imageCount": 12
}
```

| שדה | מה יש בו |
| --- | --- |
| `status` | `untrained`, `queued`, `training`, `succeeded`, `failed` או `cancelled`. הערך `untrained` פירושו שמעולם לא אומן מודל לדמות, שהמודל הוסר או שלא היה אפשר להתחיל אימון. |
| `trainingId` | האימון הנוכחי או האחרון, או `null`. |
| `error` | למה האימון נכשל, או `null`. |
| `trainedAt` | מתי הסתיים האימון המוצלח האחרון, או `null`. |
| `version` | גרסת המודל של האימון המוצלח האחרון, או `null`. |
| `triggerWord` | המילה שמזמנת את הדמות במודל המאומן, או `null`. |
| `imageCount` | כמה תמונות שימשו באימון האחרון, או `null`. |

היצירה משתמשת במודל המאומן **רק כל עוד `status` הוא `succeeded`**. השדות `trainedAt` ו-`version` שומרים על הערכים שלהם גם בזמן אימון מחדש, אחרי אימון שנכשל או בוטל ואחרי אימון שלא היה אפשר להתחיל, אבל באף אחד מהמצבים האלה לא משתמשים במודל. בקשה לדמות שלא שייכת לכם, או לדמות שנמצאת בארכיון, נדחית עם `404 not_found`.

## יצירת תמונות עם המודל המאומן
כשהסטטוס הוא `succeeded`, הריצו את רכיב [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image) עם פרומפט שמזכיר עם `@` בדיוק דמות מאומנת אחת, כשהדמות הזאת מחוברת לרכיב. Nodaro משתמש אז במודל המאומן במקום במודל שנבחר ובתמונות הייחוס:

- **הכול אוטומטי.** מילת הטריגר נכתבת בתחילת הפרומפט בלי שתצטרכו לעשות דבר, והאזכורים עם `@` מוסרים מהטקסט.
- **22 קרדיטים לתמונה.** המחיר של המודל המאומן מחליף את המחיר של המודל שנבחר.
- **דמות מאומנת אחת בכל פעם.** כשהפרומפט מזכיר שתי דמויות מאומנות או יותר, רכיב יצירת תמונה חוזר למודל שנבחר עם תמונות ייחוס.
- **רכיב יצירת תמונה בלבד.** רכיבים אחרים, כגון [עריכת תמונה](https://nodaro.ai/docs/nodes/image/modify-image) ורכיבי הווידאו, ממשיכים להשתמש בתמונות הייחוס של הדמות.

ראו את דף ה-API [הרצת רכיב יחיד](https://nodaro.ai/docs/developers/api/nodes) לבקשה של רכיב יצירת תמונה, ואת המדריך [אימון דמויות](https://nodaro.ai/docs/guides/character-training) לאותה יכולת בעורך.

## אימון מחדש או הסרת המודל
- **אימון מחדש.** אפשר להתחיל אימון שוב בכל רגע אחרי שאימון הצליח, נכשל או בוטל. אימון מחדש עולה 1,650 קרדיטים בכל פעם ומחליף את המודל הקודם.
- **הסרה.** הנתיב `DELETE /v1/characters/:id/lora` מבטל אימון שבעיצומו, והקרדיטים עליו מוחזרים. הנתיב גם מוחק את המודל המאומן ומנקה את שדות האימון של הדמות. הסטטוס הוא אז `untrained`. הנתיב מחזיר `{ ok: true }`, ואי אפשר לבטל את הפעולה. היצירות חוזרות להשתמש בתמונות ייחוס.
- **העברת הדמות לארכיון.** העברת הדמות לארכיון גם מבטלת אימון שבעיצומו ומוחקת את המודל המאומן, והקרדיטים על האימון מוחזרים.

```bash
curl -X DELETE https://app.nodaro.ai/v1/characters/3f6c2a9e-8d41-4b7a-9c35-1e2f7a6b0d94/lora \
  -H "Authorization: Bearer $NODARO_API_KEY"
```

## קרדיטים
| פעולה | קרדיטים |
| --- | --- |
| אימון | 1,650, והקרדיטים מוחזרים כשהאימון נכשל או מבוטל. |
| אימון מחדש | 1,650 בכל פעם. |
| תמונה מהמודל המאומן | 22 לתמונה, במקום המחיר של המודל שנבחר. |

ראו את דף ה-API [קרדיטים](https://nodaro.ai/docs/developers/api/credits) ליתרות ולתנועות.

## שגיאות
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| `400` | `insufficient_training_images` | לדמות יש פחות מ-4 תמונות שונות. השדות `count` ו-`message` בתגובה מציינים כמה תמונות יש לה. הוסיפו זוויות או הבעות ונסו שוב. |
| `400` | — | מזהה או `selectedImageUrls` פגומים. הגוף הוא `{ "message", "issues": [...] }`. |
| `401` | `unauthorized` | האסימון חסר, לא תקין או מבוטל. |
| `402` | `insufficient_credits` | היתרה בחשבון נמוכה מ-1,650 קרדיטים. השדות `required` ו-`balance` מופיעים בתגובה. |
| `403` | `insufficient_scope` | אסימון של אפליקציית OAuth בלי ההרשאה `assets:write`. |
| `404` | `not_found` | אין לכם דמות כזאת, הדמות בארכיון, או שהמופע הוא לא Nodaro Cloud. |
| `409` | `already_training_or_not_found` | אימון של הדמות הזאת כבר ממתין בתור או רץ, או שהדמות לא שייכת לכם או נמצאת בארכיון. |
| `422` | `job_blocked` | מדיניות המשימות של הפריסה דחתה את האימון. |
| `429` | — | יותר מ-3 בקשות להתחלת אימון בדקה מהאסימון הזה. |
| `500` | `claim_failed` | השרת לא הצליח לנעול את האימון לבקשה הזאת. שום דבר לא התחיל: נסו שוב. |
| `502` | `training_dispatch_failed` | השרת לא הצליח להתחיל את האימון. הקרדיטים מוחזרים, והסטטוס הוא `untrained`. |
| `503` | `public_url_not_configured`, `price_not_configured` | האימון לא מוגדר במופע הזה. |
| `503` | `dedup_race_winner_unresolvable` | בקשה זהה כבר הייתה בטיפול, ולא היה אפשר לקרוא את התוצאה שלה. שום דבר לא שוריין לבקשה הזאת: בדקו את הסטטוס לפני שאתם מנסים שוב. |

הדחיות שהנתיבים האלה כותבים בעצמם משתמשות במבנה גוף ישן יותר: הקוד הוא מחרוזת פשוטה, `{ "error": "<code>" }`, לפעמים עם `message` ברמה העליונה. הדחיות של הרשאות, קרדיטים, מגבלת קצב ומדיניות משימות משתמשות במעטפת הרגילה, `{ "error": { "code", "message" } }`. ה-SDK קורא את שני המבנים לתוך `NodaroError.code` ו-`.message`.

## שאלות נפוצות

### כמה תמונות צריך כדי לאמן דמות?

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

### כמה עולה אימון דמות?

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

### כמה זמן לוקח אימון?

אימון דמות לוקח כ-15 דקות. בדקו את הסטטוס עם הנתיב GET /v1/characters/:id/training מדי כמה שניות, עד שהסטטוס הוא succeeded, failed או cancelled.

### מתי רכיב יצירת תמונה משתמש במודל המאומן?

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

### האם אפשר לאמן דמות בהתקנה באירוח עצמי?

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