# ה-API של Video Remake

> Video Remake הוא מה שנקרא לרוב AI motion control או החלפת דמות (character swap): הוא מחליף את האנשים, חיות המחמד, המוצרים או המיקום בסרטון בתמונות שלכם.

Source: https://nodaro.ai/he/docs/developers/api/video-remake

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

Video Remake הוא מה שנקרא לרוב AI motion control או החלפת דמות (character swap). כדי שדמות מתמונת סטילס אחת תבצע את התנועות של סרטון, השתמשו ברכיב [העברת תנועה](https://nodaro.ai/docs/nodes/video/motion-transfer).

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

## נקודות קצה
| שיטה | נתיב | מה היא עושה | עלות |
| --- | --- | --- | --- |
| `POST` | `/v1/video-remake/estimate` | אומדן מחיר להרצה. שום דבר לא נוצר ולא משוריין. | חינם |
| `POST` | `/v1/video-remake` | התחלת הרצה. מחזירה `202 { jobId }`. בדקו את מצב המשימה עם `GET /v1/jobs/:id`. | מחיר ההרצה לפי האומדן |
| `POST` | `/v1/video-remake/:jobId/full-quality/estimate` | אומדן מחיר לגרסת האיכות המלאה של הרצת טיוטה. שום דבר לא נוצר ולא משוריין. | חינם |
| `POST` | `/v1/video-remake/:jobId/full-quality` | השלמת טיוטה ב-1080p, כמשימה חדשה. ראו את הסעיף [איכות מלאה](#full-quality). | מחיר ההרצה לפי האומדן |
| `GET` | `/v1/video-remake/style-choice` | מציינת לכל מנוע אם אתם בוחרים את ה-`style` של הרצה או ש-Nodaro קיבע אותו לסגנון התנועה, אם המנוע מקבל הרצות של סגנון בלבד, ואם הרצה בסגנון המדויק מקבלת סגנון אמנותי. ציבורית: לא צריך להתחבר. ראו את הסעיף [סגנון](#style). | חינם |
| `GET` | `/v1/video-remake/advanced` | מציינת אם הדף של Video Remake מציג את האפשרויות המתקדמות שלו. ציבורית: לא צריך להתחבר. ראו את הסעיף [סגנון](#style). | חינם |

## גוף הבקשה
שני הנתיבים מקבלים את אותו גוף בקשה.

| שדה | מה הוא עושה |
| --- | --- |
| `videoUrl` | נדרש. קליפ המקור, באורך 4–30 שניות. |
| `roles` | נדרש. עד 6 תפקידים של אנשים, תפקיד אחד של מיקום, 3 תפקידים של חיות מחמד ו-3 תפקידים של מוצרים. פרטים בהמשך. |
| `references` | אופציונלי. עד 5 ייחוסים קבועים: דברים שהסרטון צריך להראות ושאף תפקיד לא מחליף. ראו את הסעיף [ייחוסים קבועים](#fixed-references). |
| `prePrompt` | אופציונלי. טקסט משלכם שמוצב בתחילת הפרומפט, לפני ההוראות של התפקידים. חלים עליו אותה מגבלה ואותם אזכורי `{role:N}` כמו על `postPrompt`. |
| `postPrompt` | אופציונלי. טקסט משלכם למודל, עד 4,000 תווים. כדי להזכיר תפקיד, כתבו `{role:N}`, כש-N נספר מ-1 לפי הסדר ב-`roles`, כולל תפקידים ריקים. |
| `preview` | אופציונלי. הערך `true` מרנדר 4 שניות מהקליפ, החל מ-`previewStart`. |
| `previewStart` | אופציונלי. הנקודה שבה התצוגה המקדימה מתחילה, בשניות. ברירת המחדל היא 0. |
| `engine` | אופציונלי. המנוע: `"nodaro-prism"` (Nodaro Prism), ברירת המחדל, או `"nodaro-pulse"` (Nodaro Pulse). ראו את הסעיף [מנועים](#engines). |
| `style` | אופציונלי. איך ההרצה עוקבת אחרי הקליפ: `"precise"`, ברירת המחדל, או `"motion"`. ראו את הסעיף [סגנון](#style). |
| `direction` | אופציונלי, ב-Nodaro Prism בלבד. סגנון אמנותי, `{ style: "<id>" }`, כשהמזהה הוא אחד המזהים בקטלוג של הבורר [סגנון](https://nodaro.ai/docs/nodes/creative-controls/style). ראו את הסעיף [סגנונות אמנותיים](#art-styles). |
| `motionLength` | אופציונלי, ב-Nodaro Pulse בלבד. איפה הקליפ נחתך לשניות שלמות: `"cut-end"`, ברירת המחדל, או `"cut-start"`. |
| `resolution` | אופציונלי. `"480p"`, ברירת המחדל, `"720p"` או `"1080p"`. ב-Nodaro Pulse: `"720p"`, ברירת המחדל שלו, או `"1080p"`. |
| `draft` | אופציונלי. כבוי כברירת מחדל, ולכן הרצה ב-480p היא הרצה רגילה. הערך `true` יוצר טיוטה ב-480p, שאת אותו טייק שלה אפשר להשלים אחר כך ב-1080p ב[איכות מלאה](#full-quality). הערך `true` מעל 480p נדחה. ל-Nodaro Pulse אין טיוטה. |
| `prepareReferences` | אופציונלי. ברירת המחדל היא `true`. ראו את הסעיף [הכנת הייחוסים](#reference-preparation). |
| `quality` | מיושן. הערך `"draft"` עדיין עובד, ופירושו טיוטה ב-480p. השתמשו במקומו ב-`resolution` וב-`draft`. |
| `sessionId`, `origin` | אופציונלי. הסשן שבו התוצאה תישמר, ותווית המקור של האפליקציה שלכם. |

תפקיד מציין מישהו, משהו או את המקום שבסרטון, ומקבל 0–3 תמונות של נושא אחד או של מקום אחד. בקשה מקבלת לכל היותר 30 תמונות בסך הכול.

- **אדם:** `{ kind: "person", name?, images, body?, outfit?, hair? }`. השדה `name` מציין מי בסרטון, למשל `"the woman dancing"` (האישה שרוקדת).
- **חיית מחמד:** `{ kind: "pet", name?, images, body?, coat? }`.
- **מוצר:** `{ kind: "product", name?, images, shape?, finish? }`.
- **המיקום:** `{ kind: "location", name?, images }`. שם ברירת המחדל הוא `"the setting"` (מקום ההתרחשות).

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

הערך של כל תכונה (`body`, `outfit`, `hair`, `coat`, `shape`, `finish`) הוא `"new"`, ברירת המחדל, שלוקח את התכונה מהתמונות שלכם, או `"original"`, ששומר עליה כמו בסרטון.

תפקיד בלי תמונות (מערך ריק או `null`) שומר על הנושא או על המקום כמו בסרטון. נדרש לפחות אחד מאלה: תפקיד עם תמונות, ייחוס, `prePrompt` או `postPrompt`, או סגנון אמנותי. סגנון אמנותי נחשב רק בהרצה של סגנון בלבד (ראו את הסעיף [סגנונות אמנותיים](#art-styles)).

כל תפקיד יכול לקבל גם שתי הגדרות שחלות רק על תצוגה מקדימה. הרצה מלאה מתעלמת משתיהן.

- השדה `previewName` הוא השם שמשמש במקום `name` בתצוגה מקדימה.
- הערך `inPreview: false` משאיר את התפקיד מחוץ לתצוגה המקדימה. התמונות שלו לא נשלחות ולא עוברות הכנה, ולא משלמים עליהן. אזכור `{role:N}` שומר על המספר שלו ומקבל את הערך של `previewName` של התפקיד, או, אם אין כזה, את `name` שלו.

```json
{
"videoUrl": "https://example.com/clip.mp4",
"roles": [
{ "kind": "person", "name": "the woman dancing", "images": ["https://example.com/me.jpg"], "outfit": "original" }
],
"preview": true
}
```

## מנועים
השדה `engine` בוחר את המנוע שמפיק את התוצאה. השמיטו אותו כדי להישאר עם Nodaro Prism.

| מנוע | רזולוציות | טיוטה | איכות מלאה |
| --- | --- | --- | --- |
| `"nodaro-prism"`, Nodaro Prism (ברירת המחדל) | 480p (ברירת המחדל), 720p, 1080p | ב-480p, עם `draft: true` | מרנדר מחדש ב-1080p את הטייק של הטיוטה עצמה |
| `"nodaro-pulse"`, Nodaro Pulse | 720p (ברירת המחדל), 1080p | לא | אין: הריצו שוב ב-1080p |

- **Nodaro Pulse** יוצר טייק חדש לפי הקליפ והתמונות שלכם.
- ב-Nodaro Pulse, הערך `draft: true` נדחה עם `draft_unsupported`, והערך `"480p"` נדחה עם `resolution_unsupported`.
- Nodaro Pulse מרנדר שניות שלמות, ולכן הקליפ נחתך לשניות שלמות. השדה `motionLength` קובע איפה: הערך `"cut-end"` משמיט את שבר השנייה שבסוף, והערך `"cut-start"` משמיט אותו בהתחלה. Nodaro Prism מתעלם מ-`motionLength`.
- בשני המנועים, תצוגה מקדימה היא 4 שניות החל מ-`previewStart`.
- Nodaro Pulse מקבל לכל היותר 10 תמונות להרצה, בכל התפקידים והייחוסים הקבועים יחד. בקשה עם יותר תמונות נדחית עם `too_many_images`. Nodaro Prism מקבל עד 30.
- המשימה רושמת את המנוע שלה ב-`input_data.engine`, והפלט של משימה שהושלמה מציין אותו ב-`engine`.

## סגנון
השדה `style` קובע איך ההרצה עוקבת אחרי הקליפ. השמיטו אותו כדי להישאר בסגנון המדויק.

- הערך `"precise"`, ברירת המחדל, עוקב אחרי הקליפ בדיוק.
- הערך `"motion"` עוקב אחרי התנועה שבקליפ ולוקח את המראה של האנשים, חיות המחמד והמוצרים מהתמונות שלכם. סגנון התנועה עוקב אחרי הקליפ בחופשיות רבה יותר מהסגנון המדויק.

שני הסגנונות שומרים על הסאונד ועל האורך של הקליפ. המחיר של סגנון התנועה יכול להיות שונה מהמחיר של הסגנון המדויק. שלחו את אותו `style` ל-`POST /v1/video-remake/estimate` כדי לראות את המחיר המדויק.

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

Nodaro יכול לקבע את הסגנון של מנוע לכולם לסגנון התנועה. כל הרצה וכל אומדן במנוע הזה הם אז בסגנון התנועה, בלי קשר לערך של `style`. הנתיב `GET /v1/video-remake/style-choice` מציין לכל מנוע מה המצב, ולא דורש התחברות:

```json
{ "engines": { "nodaro-prism": "user", "nodaro-pulse": "precise" } }
```

כל ערך הוא `"user"` (אתם בוחרים, כמו שמתואר למעלה), `"precise"` או `"flex"` (סגנון התנועה, כלומר `style: "motion"`, שמקובע כמו שמתואר למעלה). הערך `"precise"` לא משנה שום בקשה. האפליקציות של Nodaro עצמו מריצות במנוע הזה את הסגנון המדויק ומסתירות את בחירת הסגנון. כל הרצה וכל אומדן במנוע הזה משתמשים ב-`style` שנשלח, כמו במנוע שהתשובה עבורו היא `"user"`. הציגו באפליקציה שלכם בחירת סגנון רק למנוע שהתשובה עבורו היא `"user"`.

באותה תשובה יש עוד שלוש מפות, כל אחת בצורה `{ "nodaro-prism": boolean, "nodaro-pulse": boolean }`:

- השדה `styleOnly` מציין אם המנוע מקבל הרצות של סגנון בלבד. ראו את הסעיף [סגנונות אמנותיים](#art-styles).
- השדה `preciseArtStyle` מציין אם הרצה בסגנון המדויק מקבלת סגנון אמנותי במנוע הזה.
- השדה `preciseArtStyleAlone` מציין אם במנוע הזה סגנון אמנותי לבדו יכול להיות השינוי של הרצה בסגנון המדויק, בלי תפקיד, ייחוס או פרומפט. הערך שלו הוא `false` עד שהמנוע יקבל הרצות כאלה. Nodaro עשוי להריץ בקשה כזו כהרצה בסגנון התנועה, והמפה הזו לא מציינת זאת. ראו את הסעיף [סגנון אמנותי בהרצה בסגנון המדויק](#art-styles).

שלוש המפות תלויות רק במנוע, ולכן בדקו אותן יחד עם `engines`. ב-Nodaro Pulse הערך תמיד `false` בשלושתן. שרת מגרסה שקדמה להן משמיט אותן: התייחסו לכך כאל `false` לכל מנוע. במנוע שהתשובה עבורו היא `"flex"`, כל הרצה היא בסגנון התנועה.

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

**האפשרויות המתקדמות בדף של Video Remake.** הדף של Video Remake מציע שני שדות של גוף הבקשה, `prepareReferences` ו-`prePrompt`, רק תחת האפשרויות המתקדמות שלו. האפשרויות האלה מוסתרות, אלא אם Nodaro מפעיל אותן, בהגדרה אחת לכל הדף ולכל המנועים. הנתיב `GET /v1/video-remake/advanced` לא דורש התחברות ומחזיר `{ show: boolean }`, כך שאפליקציה שבנויה על ה-API הזה יכולה להציג או להסתיר את אותן אפשרויות. התשובה מתארת רק את הדף: כל הרצה וכל אומדן מקבלים את `prepareReferences` ואת `prePrompt`, בלי קשר למה שהיא אומרת. התשובה עשויה לפגר בדקה לכל היותר. ל-SDK עדיין אין מתודה בשבילה, ולכן קראו לנתיב עם `client.request()`.

כל עוד האופן שבו Nodaro מכין הרצות בסגנון התנועה במנוע מגביל את הקליפ, הרצה מלאה בסגנון התנועה נדחית עם `clip_too_long_for_style` כשהקליפ ארוך מ-27.9 שניות. ב-Nodaro Pulse, האורך נמדד אחרי שהקליפ נחתך לשניות שלמות. תצוגה מקדימה לא מוגבלת.

## סגנונות אמנותיים
השדה `direction: { style: "<id>" }` מצייר את הסרטון בסגנון אמנותי, כגון `pop-art`. המזהה הוא אחד המזהים בקטלוג של הבורר [סגנון](https://nodaro.ai/docs/nodes/creative-controls/style). רק Nodaro Prism מקבל סגנון אמנותי. Nodaro Pulse דוחה סגנון אמנותי עם `400 art_style_needs_prism`.

**עיצוב מחדש של קליפ שלם (סגנון בלבד).** הרצה בסגנון התנועה (`style: "motion"`) יכולה לקבל סגנון אמנותי בלי שום דבר להחלפה: בלי תפקיד עם תמונות ובלי ייחוס קבוע. ההרצה עדיין מתקבלת, כי הסגנון האמנותי הוא השינוי שלה. הטקסט ב-`prePrompt` או ב-`postPrompt` עדיין מתווסף. ההרצה מעצבת מחדש את הקליפ כולו ושומרת על האנשים, המקומות, התנועה והסאונד.

- ההרצה מחויבת לפי מה שהיא מריצה: התשלום הבסיסי והסרטון, בלי החלק `privacy`. החלק `referenceAudio` מופיע רק כשההגדרה של Nodaro למנוע מריצה את השלב הזה, והחלק `prompt` רק כשההגדרה נותנת למודל שפה לכתוב את הפרומפט. שלחו את אותו גוף בקשה ל-`POST /v1/video-remake/estimate` כדי לראות את המחיר.
- כברירת מחדל, סגנון אמנותי בשחור־לבן יוצא מונוכרומטי. Nodaro עשוי במקום זאת להריץ הרצות כאלה כמו שהוא מריץ הרצות אחרות עם סגנון אמנותי, באותו מחיר שלהן ובלי להפוך אותן למונוכרומטיות.
- תצוגה מקדימה עוברת באותו מסלול כמו ההרצה המלאה שלה. תצוגה מקדימה שמשאירה בחוץ את כל התפקידים עם תמונות (`inPreview: false`) עוברת במסלול של ההרצה המלאה שלה, והסגנון האמנותי נחשב לשינוי של התצוגה המקדימה.
- הציעו את האפשרות הזו רק כש-`GET /v1/video-remake/style-choice` מחזיר `styleOnly: true` למנוע. כל עוד התשובה עבור Nodaro Prism היא `false`, סגנון אמנותי בלי שום דבר אחר לשנות נדחה עם `400 validation_error`. סגנון אמנותי עם `prePrompt` או `postPrompt` מתקבל, אבל רץ כמו כל הרצה אחרת עם סגנון אמנותי.
- ההרצה עדיין חייבת להיות בסגנון התנועה. מנוע שהתשובה עבורו היא `"precise"` לא משנה שום בקשה, ולכן הרצה בסגנון התנועה בו מעצבת מחדש את הקליפ כמו במנוע שהתשובה עבורו היא `"user"`.

**סגנון אמנותי בהרצה בסגנון המדויק.** כש-`GET /v1/video-remake/style-choice` מחזיר `preciseArtStyle: true` למנוע, גם הרצה בסגנון המדויק מקבלת סגנון אמנותי. Nodaro עשוי ליצור אותה באותה דרך שבה נוצרת הרצה בסגנון התנועה, שבה הסגנון האמנותי נשמר על פני התמונה כולה באופן אמין הרבה יותר. במקרה כזה:

- המשימה עדיין רושמת את הסגנון ששלחתם: השדה `input_data.style` לא קיים, או שהערך שלו הוא `"precise"`. מי שמקבל את המשימה שוב, או שולח שוב את אותו גוף בקשה, מבקש את אותה הרצה.
- האומדן שלה (כשהוא נשלח עם אותו גוף בקשה), המחיר שלה, האיכות המלאה שלה וההתנהגות שלה כהרצה של סגנון בלבד הם של הרצה בסגנון התנועה.
- כשאין בה שום דבר אחר לשנות, היא מתקבלת כהרצה של סגנון בלבד.
- הנתיב `style-choice` לא מציג איזה מהמקרים חל. בדקו את האומדן כדי לדעת כמה הרצה עולה.
- משימות שנוצרו כך לפני שהסגנון נשמר רושמות `input_data.style: "motion"`.

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

- הסגנון האמנותי לבדו לא נחשב כאן לשינוי. הרצה בסגנון המדויק בלי תפקיד עם תמונות, בלי ייחוס קבוע, בלי `prePrompt` ובלי `postPrompt` עדיין נדחית עם `400 validation_error`. כדי רק לעצב מחדש קליפ שלם, השתמשו בהרצה בסגנון התנועה (סגנון בלבד, למעלה).
- המחיר משתנה רק כשההגדרה של Nodaro להרצות האלה מציירת קודם מחדש את התמונות של התפקידים בסגנון האמנותי. האומדן, כשהוא נשלח עם אותו גוף בקשה, מציג זאת.
- המשימה רושמת את הסגנון האמנותי ב-`input_data.direction`.
- כש-`preciseArtStyle` הוא `false`, או כששרת מגרסה שקדמה לו משמיט אותו, הרצה בסגנון המדויק עם סגנון אמנותי נדחית עם `400 art_style_needs_flex`.

מזהה שלא נמצא בקטלוג נדחה עם `400 unknown_art_style`, ומודבורד שמור נדחה עם `400 art_style_not_supported`. הקוד `400 art_style_needs_flex` מוחזר גם לסגנון אמנותי בהרצת טרנד, ובהרצה בסגנון התנועה שההגדרה של Nodaro כותבת לה פרומפט של הסגנון המדויק. ההגדרה הזו היא לא הסגנון המקובע, והנתיב `style-choice` לא מציג אותה.

## ייחוסים קבועים
ב-`references` יש עד 5 דברים שהסרטון צריך להראות ושאף תפקיד לא מחליף. כל אחד מהם בצורה `{ images, line }`:

- ב-`images` יש 1–3 תמונות של דבר אחד.
- השדה `line` מתאר מה הדבר הזה, בין 1 ל-500 תווים, למשל `"the glass she drinks from"` (הכוס שממנה היא שותה).
- המשתנה `{image}` בשורה מייצג את התמונה הראשונה של הייחוס הזה, למשל `"Use {image} for the sky"` (השתמש ב-`{image}` לשמיים). בשורה בלי `{image}`, Nodaro מוסיף אותו בסוף.

הייחוסים נשלחים כמו שהם, ואף פעם לא עוברים הכנה. התמונות שלהם נספרות במגבלה של 30. ייחוס לבדו מספיק להרצה: אף תפקיד לא צריך תמונות. שורה לא יכולה להזכיר תפקיד עם `{role:N}`, כי שורה מתארת את הדבר עצמו.

## הכנת הייחוסים
אלא אם `prepareReferences` הוא `false`, מודל תמונה הופך קודם את התמונות של כל תפקיד של אדם, חיית מחמד או מוצר לתמונת ייחוס נקייה אחת. הסרטון נוצר אז מהתמונות האלה.

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

שלחו `prepareReferences: false` כדי להשתמש בתמונות שלכם כמו שהן.

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

בפלט של משימה שהושלמה יש `privacy: { applied, reason }`. השדה `applied` מציין אם הסרטון נוצר מהקליפ המוכן, והשדה `reason` מציין למה.

## אומדן המחיר
הנתיב `POST /v1/video-remake/estimate` מחזיר `{ engine, totalCredits, expectedCredits, breakdown, privacyCredits?, settlesLower }`. באומדן יש שני סכומים כוללים.

- השדה `totalCredits` הוא הסכום שמשוריין כשההרצה מתחילה.
- השדה `expectedCredits` הוא החיוב הצפוי על ההרצה. הוא אף פעם לא גבוה מ-`totalCredits`. ההרצה מחויבת לפי העלות בפועל.
- ב-Nodaro Prism, המודל בוחר את אורך הסרטון, ולכן הקרדיטים לסרטון משוריינים לפי הפלט הארוך ביותר האפשרי. החיוב הצפוי הוא בערך לפי אורך הקליפ בקלט, ועוד אותו אורך בפלט. הערך `settlesLower: true` מציין זאת: החיוב הסופי צפוי להיות נמוך מ-`totalCredits`, בערך `expectedCredits`.
- ב-Nodaro Pulse, שני הסכומים שווים ו-`settlesLower` הוא `false`. Nodaro Pulse מרנדר בדיוק את האורך שהתבקש.
- השדה `engine` הוא המנוע שהאומדן מתייחס אליו.

השדה `breakdown` מפרט את החלקים של האומדן, לתצוגה בלבד:

| חלק | מה הוא |
| --- | --- |
| `base` | ההרצה עצמה. |
| `references` | הכנת הייחוסים. הערך הוא 0 כשההכנה כבויה או כשאין מה להכין. |
| `motion` | הסכום שמשוריין לסרטון. ב-Nodaro Pulse, מה שהסרטון עולה. |
| `motionExpected` | החיוב הצפוי על הסרטון, אף פעם לא גבוה מ-`motion`. ב-Nodaro Prism בלבד. |
| `privacy` | הכנת הקליפ, כשההגדרה של המנוע עושה זאת. החלק הזה נכלל בשני הסכומים כשהוא רץ תמיד, ולא נכלל באף אחד מהם כשמדובר בניסיון החוזר שמתואר למטה. |
| `prompt` | הפרומפט שמודל שפה כותב להרצה, כשההגדרה של המנוע מבקשת פרומפט כזה. |
| `referenceAudio` | הכנת הסאונד של הקליפ למודל הווידאו, כשההגדרה של המנוע מריצה את השלב הזה. |

השדות `motion` ו-`motionExpected` הם חלופות, ולכן בדקו את הסכומים הכוללים, ואף פעם לא את סכום החלקים בפירוט.

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

## בקשות חוזרות
כשאתם שולחים שוב בקשה להרצה, שלחו את אותה כותרת `Idempotency-Key`, באורך 8–200 תווים. התגובה לבקשה חוזרת בתוך כ-10 שניות היא `200 { jobId, deduped: true }`, עם הכותרת `X-Dedup-Hit: 1`. התגובה לבקשה חוזרת מאוחרת יותר היא `202 { jobId }`, עם המשימה של ההרצה הראשונה. בשני המקרים לא מתחילה הרצה חדשה ולא נגבים קרדיטים. בלי מפתח, כל בקשה היא הרצה חדשה.

## איכות מלאה
אפשר להשלים **טיוטה** של Nodaro Prism שהסתיימה ב**איכות מלאה**. טיוטה היא הרצה של Video Remake או של טרנד שנוצרה ב-480p עם `draft: true`. האיכות המלאה מרנדרת מחדש את אותו טייק ב-1080p, מותאם לקליפ ועם האודיו המקורי של הקליפ. התוצאה היא משימה חדשה שמקושרת לטיוטה, והטיוטה עצמה נשארת.

רק לטיוטה יש איכות מלאה. הרצה רגילה, כולל הרצה ב-480p שנוצרה בלי `draft: true`, נדחית עם `409 not_a_draft`. כדי להשלים טייק של 480p ב-1080p בהמשך, צרו אותו עם `draft: true`. Nodaro Pulse לא יוצר טיוטות, ולכן אין לו איכות מלאה: הריצו אותו שוב ב-1080p. גרסת איכות מלאה של Pulse שנוצרה לפני השינוי הזה נשארת ברשימה כהרצה בפני עצמה.

הערך של השדה `kind` באומדן הוא `"same-take"`. שרת ישן יותר משמיט את `kind`, ופירוש הדבר זהה. איכות מלאה זמינה במשך 7 ימים אחרי שהטיוטה הושלמה.

| שיטה | נתיב | מה היא עושה |
| --- | --- | --- |
| `POST` | `/v1/video-remake/:jobId/full-quality/estimate` | אומדן מחיר, בחינם: שום דבר לא נוצר ולא משוריין. מחזירה `{ kind, totalCredits, breakdown, availableUntil }`. |
| `POST` | `/v1/video-remake/:jobId/full-quality` | התחלת האיכות המלאה. מחזירה `202 { jobId }`. כשהאיכות המלאה של ההרצה הזו כבר רצה או הסתיימה, היא מחזירה `200 { jobId, existing: true }`, ולא מתחילה הרצה חדשה ולא נגבים קרדיטים. מקבלת גוף בקשה אופציונלי `{ sessionId }`. |

הפרמטר `:jobId` הוא מזהה המשימה של הטיוטה. באומדן, `totalCredits` הוא `breakdown.base`, השלבים של משימת האיכות המלאה עצמה, ועוד `breakdown.motionHd`, הרינדור ב-1080p של הטייק של הטיוטה. השדה `motionHd` הוא 0 כשניסיון קודם שנכשל להשלים את הטיוטה הזו כבר סיים את הרינדור הזה: משתמשים שוב ברינדור, ומשלמים רק על ההשלמה. השדה `availableUntil` הוא המועד שבו 7 הימים נגמרים. המחיר נקבע לפי הטיוטה, ולכן קבלו קודם אומדן מחיר.

לכל טיוטה יש גרסת איכות מלאה אחת. המשימה מזוהה לפי הטיוטה, ולכן בקשה חוזרת או בקשה מקבילה מקבלות את אותה משימה, ואין שימוש ב-`Idempotency-Key`. אחרי ניסיון שנכשל או שבוטל, אפשר לבקש שוב כמה פעמים. המשימה החדשה שומרת על ה-`origin` של הטיוטה, והשדה `sessionId` משייך אותה לאחד הסשנים שלכם.

כל דחייה מגיעה לפני שנגבים קרדיטים. גוף התגובה הוא `{ error: { code, message } }`.

| סטטוס | `code` | מתי |
| --- | --- | --- |
| `401` | `unauthorized` | אין משתמש מאומת. |
| `402` | `insufficient_credits` | אין לכם מספיק קרדיטים. רק בנתיב ההתחלה. בסביבת עבודה, במקום הקוד הזה יכול לחזור קוד המגבלה שדחתה את הבקשה: `budget_exceeded`, `member_cap_exceeded` או `user_allowance_exceeded`. |
| `404` | `not_found` | המשימה לא שלכם, או שהיא לא הרצה של Video Remake. וגם `sessionId` שאין לכם הרשאה להשתמש בו, רק בנתיב ההתחלה. |
| `409` | `not_completed` | ההרצה עוד לא הסתיימה. |
| `409` | `not_a_draft` | ההרצה היא לא טיוטה של Nodaro Prism. היא הרצה רגילה, כולל הרצה ב-480p שנוצרה בלי `draft: true`, או הרצה של Nodaro Pulse, שלא יוצר טיוטות: הריצו אותו שוב ב-1080p. |
| `409` | `full_quality_pending` | לא סופי, ולכן נסו שוב מאוחר יותר. בגוף התגובה יש `retryable: true`. הרינדור ב-1080p של הטיוטה הזו מניסיון קודם נמצא בבדיקה, או שעוד לא התחיל. |
| `409` | `full_quality_unavailable` | סופי. אי אפשר להשלים את ההרצה באיכות מלאה: שום דבר לא נשמר לרינדור מחדש, אי אפשר לקרוא את מועד הסיום שלה, או שההשלמה ב-1080p דוחה את הטיוטה הזו. רק בנתיב ההתחלה, גם כשכל הניסיונות נכשלו, או כשאי אפשר להתחיל אף ניסיון להרצה הזו. |
| `410` | `draft_expired` | עברו יותר מ-7 ימים מאז שהטיוטה הושלמה, או שכבר אי אפשר להשלים את הטיוטה באיכות מלאה. |
| `422` | `job_blocked` | מדיניות המשימות של הפריסה חסמה את הבקשה. רק בנתיב ההתחלה. |
| `503` | `job_read_failed` | כרגע אי אפשר היה לקרוא את הטיוטה. בגוף התגובה יש `retryable: true`. נסו שוב. |
| `503` | `estimate_unavailable` | כרגע אי אפשר לתת אומדן מחיר לרינדור ב-1080p. נסו שוב בעוד רגע. |
| `503` | `host_too_old` | גרסת הפלטפורמה הזו לא יכולה להריץ איכות מלאה. |

הבחינו בין `full_quality_pending` ל-`full_quality_unavailable` לפי הקוד, לא לפי ההודעה.

## שגיאות
כל דחייה מגיעה לפני שנגבים קרדיטים. גוף התגובה הוא `{ error: { code, message } }`.

| סטטוס | `code` | מתי |
| --- | --- | --- |
| `400` | `validation_error` | גוף הבקשה לא תקין: אין בו תפקיד עם תמונות, ייחוס, `prePrompt`, `postPrompt` או סגנון אמנותי (סגנון אמנותי נחשב רק כש-`styleOnly` הוא `true`); או שיש בו יותר מ-5 ייחוסים, ייחוס בלי תמונה או עם יותר מ-3, יותר תפקידים מסוג מסוים ממה שמותר, יותר מ-3 תמונות בתפקיד, יותר מ-30 תמונות בסך הכול, `draft: true` ב-720p או ב-1080p, `prePrompt` או `postPrompt` של יותר מ-4,000 תווים, `origin` לא תקין או ערך `style` שהוא לא `"precise"` וגם לא `"motion"`. |
| `400` | `draft_unsupported` | `draft: true` עם `engine: "nodaro-pulse"`, שאין לו טיוטה. |
| `400` | `resolution_unsupported` | `resolution: "480p"` עם `engine: "nodaro-pulse"`. |
| `400` | `output_format_unsupported` | בקשה לפלט MOV מ-`engine: "nodaro-pulse"`. רק הרצה של Nodaro Prism יכולה להחזיר פלט כזה. |
| `400` | `too_many_images` | יותר מ-10 תמונות בהרצה של Nodaro Pulse, בכל התפקידים והייחוסים הקבועים יחד. |
| `400` | `raw_reference_token` | ב-`name` או ב-`previewName` של תפקיד, ב-`line` של ייחוס, ב-`prePrompt` או ב-`postPrompt` יש סימון ייחוס גולמי: `{image:`, `{video:` או `{audio:`, בלי הבדל בין אותיות גדולות לקטנות. |
| `400` | `invalid_role_mention` | הטקסט ב-`prePrompt` או ב-`postPrompt` מזכיר את `{role:N}` עם N מחוץ לטווח שבין 1 למספר התפקידים. וגם כל `{role:N}` ב-`line` של ייחוס. |
| `400` | `no_roles_in_preview` | תצוגה מקדימה שלא הייתה משנה כלום, לפי מה שהיא שולחת: לא נשאר בה תפקיד עם תמונות, ואין בה ייחוס קבוע, `prePrompt`, `postPrompt` או סגנון אמנותי. תצוגה מקדימה שכל התפקידים הושארו מחוצה לה עדיין רצה כשיש בה ייחוס, פרומפט או, כש-`styleOnly` הוא `true`, סגנון אמנותי. |
| `400` | `prompt_too_long` | הפרומפט היה יוצא ארוך מדי. כשלתפקיד אין תמונות, המשתנה `{role:N}` מוחלף בשם של התפקיד, ולכן פרומפטים שכל אחד מהם בתוך 4,000 תווים עדיין יכולים לחרוג יחד מהמגבלה של המנוע. המגבלה של Nodaro Pulse היא 8,000 תווים. |
| `400` | `unsafe_url` | הערך של `videoUrl`, של תמונת תפקיד או של תמונת ייחוס הוא לא כתובת http או https ציבורית. |
| `400` | `video_unreadable` | אי אפשר היה לקרוא את אורך הקליפ. הקובץ הוא לא סרטון שאפשר לנגן. |
| `400` | `clip_out_of_range` | הקליפ קצר מ-4 שניות או ארוך מ-30 שניות. |
| `400` | `clip_too_long_for_style` | רק עם `style: "motion"`, כל עוד האופן שבו Nodaro מכין הרצות בסגנון התנועה במנוע מגביל את הקליפ. הרצה מלאה שהקליפ שלה ארוך מ-27.9 שניות. ההודעה היא "This clip is too long for Motion. Use a shorter clip or choose Precise." (הקליפ הזה ארוך מדי לסגנון התנועה. השתמשו בקליפ קצר יותר או בחרו בסגנון המדויק). |
| `400` | `prompt_parts_not_allowed` | גוף הבקשה שולח `promptParts`. רק פלטפורמת Nodaro עצמה יכולה לשלוח אותו, לפרומפט של טרנד. |
| `400` | `prompt_style_not_allowed` | גוף הבקשה שולח `promptStyle`. רק פלטפורמת Nodaro עצמה יכולה לשלוח אותו. הניסוח של הרצה נקבע לפי ה-`style` שלה. |
| `400` | `preview_out_of_range` | התצוגה המקדימה חורגת מסוף הקליפ. הערך `previewStart` ועוד 4 צריך להיות לכל היותר אורך הקליפ. |
| `400` | `unnamed_role_needs_picture` | תפקיד של אדם, חיית מחמד או מוצר בלי `name` ובלי תמונה. תפקיד בלי שם מקבל שם לפי התמונה הראשונה שלו, ולכן הוא צריך תמונה. |
| `400` | `art_style_needs_prism` | סגנון אמנותי עם `engine: "nodaro-pulse"`, שלא מקבל סגנון אמנותי. |
| `400` | `art_style_needs_flex` | סגנון אמנותי בהרצה בסגנון המדויק כש-`preciseArtStyle` הוא לא `true`, בהרצת טרנד, או בהרצה בסגנון התנועה שההגדרה של Nodaro כותבת לה פרומפט של הסגנון המדויק. |
| `400` | `unknown_art_style` | הערך `direction.style` הוא לא מזהה מהקטלוג של הבורר סגנון. |
| `400` | `art_style_not_supported` | השדה `direction` מציין מודבורד שמור, שהרצה של Video Remake לא יכולה לקבל. |
| `400` | `role_name_required` | הרצת טרנד עם תפקיד שאין לו שם. לתפקידים של טרנד יש תמיד שם. |
| `401` | `unauthorized` | אין משתמש מאומת. |
| `402` | `insufficient_credits` | אין לכם מספיק קרדיטים להרצה. רק ב-`POST /v1/video-remake`. כשבאומדן יש `privacyCredits`, הקרדיטים הנדרשים הם השריון ועוד `privacyCredits`. בסביבת עבודה, במקום הקוד הזה יכול לחזור קוד המגבלה שדחתה את הבקשה: `budget_exceeded`, `member_cap_exceeded` או `user_allowance_exceeded`. |
| `404` | `not_found` | השדה `sessionId` מציין סשן שאין לכם הרשאה להשתמש בו. רק ב-`POST /v1/video-remake`. |
| `422` | `job_blocked` | מדיניות המשימות של הפריסה חסמה את הבקשה. רק ב-`POST /v1/video-remake`. |
| `503` | `host_too_old` | גרסת הפלטפורמה הזו לא יכולה להריץ את Video Remake. |
| `503` | `estimate_unavailable` | כרגע אי אפשר לתת אומדן מחיר. נסו שוב בעוד רגע. רק ב-`/estimate`. |

## דרך ה-SDK
המשאב `client.videoRemake` עוטף את כל הנתיבים. אפשר גם לייבא אותו מ-`@nodaro/sdk/video-remake`.

```ts
run(params: VideoRemakeParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: VideoRemakeParams): Promise<VideoRemakeEstimate>
fullQualityEstimate(jobId: string): Promise<VideoRemakeFullQualityEstimate>
fullQuality(jobId: string, params?: { sessionId?: string }): Promise<VideoRemakeFullQualityResult>
styleChoice(): Promise<VideoRemakeStyleChoice> // GET /v1/video-remake/style-choice, public
```

הטיפוס `VideoRemakeParams` הוא גוף הבקשה שתואר למעלה, כשהשדה `engine` מוגדר מהטיפוס `VideoRemakeEngine`, `style` מהטיפוס `VideoRemakeStyle` (`"precise" | "motion"`) ו-`motionLength` מהטיפוס `VideoRemakeMotionLength`. השדה `faceMasking` עדיין מוגדר בטיפוסים, כדי שקוד ישן ימשיך לעבוד, אבל הוא מיושן והשרת מתעלם ממנו. הטיפוס `VideoRemakeEstimate` הוא האומדן. המתודה `run()` שולחת את `idempotencyKey` ללא שינוי בכותרת `Idempotency-Key`. בלעדיו, לא נשלחת כותרת. המתודה `styleChoice()` מחזירה את `VideoRemakeStyleChoice`, כלומר `{ engines: { "nodaro-prism", "nodaro-pulse" }, styleOnly?, preciseArtStyle? }`. כל מנוע הוא `VideoRemakeStyleChoiceOption`: `"user"`, `"precise"` או `"flex"`. השדות `styleOnly` ו-`preciseArtStyle` ממפים כל מנוע לערך בוליאני; התייחסו לערך חסר כאל `false`. הטיפוס `VideoRemakeParams` מקבל `direction?: { style: string }`, והשדה `breakdown` של האומדן יכול לכלול את `referenceAudio`.

```ts
const { engines, styleOnly } = await client.videoRemake.styleChoice()
if (styleOnly?.["nodaro-prism"] === true) {
await client.videoRemake.run({ videoUrl, roles: [], style: "motion", direction: { style: "pop-art" } })
}
```

```ts
const params: VideoRemakeParams = {
videoUrl,
roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
preview: true,
resolution: "480p",
}
const quote = await client.videoRemake.estimate(params)
const { jobId } = await client.videoRemake.run(params, { idempotencyKey: crypto.randomUUID() })
```

בדקו את מצב המשימה עם `client.jobs.get(jobId)`. המשימה של תצוגה מקדימה שומרת את כל הקלטים ב-`input_data` שלה, כך שאפשר להריץ אותה שוב עם `preview: false` כדי לרנדר את הקליפ המלא עם אותן בחירות.

כדי להשלים הרצה ב-1080p, קבלו אומדן מחיר עם המתודה `fullQualityEstimate(draftJobId)`, שהיא חינמית, ואז קראו למתודה `fullQuality(draftJobId)`. הערך של השדה `kind` באומדן, מהטיפוס `VideoRemakeFullQualityKind`, הוא `"same-take"`. התוצאה היא `{ jobId, existing? }`. הערך `existing: true` פירושו שהאיכות המלאה של ההרצה הזו כבר רצה או הסתיימה, ולא נגבו קרדיטים. דחייה כוללת קוד מהטיפוס `VideoRemakeFullQualityRefusalCode`. עם `full_quality_pending`, הערך של `err.details.retryable` הוא `true`: נסו שוב מאוחר יותר.

```ts
const quote = await client.videoRemake.fullQualityEstimate(draftJobId) // free
const { jobId, existing } = await client.videoRemake.fullQuality(draftJobId)
```

## דרך ה-CLI
```bash
nodaro video-remake full-quality estimate <jobId> [--json]
nodaro video-remake full-quality run <jobId> [--session <id>] [--json]
```

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

## דרך MCP
כלי ה-MCP הוא [`video_remake`](https://nodaro.ai/docs/mcp/tools/video#video_remake). הכלי מקבל את אותם שדות בכתיב snake case, למשל `pre_prompt`, `prepare_references`, `in_preview`, `engine`, `style` ו-`motion_length`. הוא מקבל גם `art_style`, סגנון אמנותי ב-Nodaro Prism: מזהה מהקטלוג של הבורר [סגנון](https://nodaro.ai/docs/nodes/creative-controls/style), כגון `pop-art`. הפרמטר עובד בהרצה בסגנון התנועה, ובהרצה בסגנון המדויק כשהמנוע מקבל בה סגנון אמנותי. בלי תמונות לתפקידים ובלי ייחוסים, הוא מעצב מחדש את הקליפ כולו כשהמנוע מקבל הרצות של סגנון בלבד. ראו את הסעיף [`video_remake`](https://nodaro.ai/docs/mcp/tools/video#video_remake) בדף וידאו. הכלי לא מקבל הגדרה להכנת הקליפ. בלי `confirm`, הוא מחזיר את אומדן המחיר ולא גובה כלום. עם `confirm: true`, אחרי שהמחיר אושר, הוא מתחיל את ההרצה ומחזיר מזהה משימה. הכלים `estimate_full_quality` ו-`full_quality` נותנים אומדן מחיר ומתחילים את גרסת האיכות המלאה של טיוטה או של הרצה של Nodaro Pulse ב-720p.

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

### מה עושה Video Remake?

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

### האם Video Remake הוא motion control או החלפת דמות?

כן. Video Remake הוא מה שנקרא לרוב AI motion control או החלפת דמות (character swap). התנועה, המסגור, התזמון והסאונד של הקליפ נשארים, והאנשים, חיות המחמד, המוצרים או המיקום מגיעים מהתמונות שלכם. כדי שדמות מתמונת סטילס אחת תבצע את התנועות של סרטון, השתמשו ברכיב העברת תנועה.

### מה האורך המותר של סרטון המקור?

סרטון המקור של Video Remake צריך להיות באורך של בין 4 ל-30 שניות. קליפ קצר או ארוך יותר נדחה עם clip_out_of_range לפני שנגבים קרדיטים.

### איך יודעים כמה תעלה הרצה של Video Remake?

כדי לדעת כמה תעלה הרצה של Video Remake, קראו לנתיב POST /v1/video-remake/estimate עם אותו גוף בקשה שתריצו. הקריאה הזו חינמית, והיא מחזירה את totalCredits, הסכום שמשוריין כשההרצה מתחילה, ואת expectedCredits, החיוב הצפוי על ההרצה. בדקו את שני הסכומים הכוללים, ואף פעם לא את סכום החלקים בפירוט.

### האם אפשר לנסות את המראה לפני שמרנדרים את כל הקליפ?

כן. ב-Video Remake, שלחו את preview עם הערך true כדי לרנדר 4 שניות מהקליפ, החל מ-previewStart. תצוגה מקדימה עולה פחות, והמשימה שלה שומרת את כל הקלטים, כך שאפשר להריץ אותה שוב עם preview בערך false.

### האם אפשר להשלים הרצת טיוטה באיכות מלאה?

כן, בתוך 7 ימים מסיום הטיוטה. צרו את ההרצה ב-Nodaro Prism ב-480p, עם draft בערך true. אחר כך הנתיב POST /v1/video-remake/:jobId/full-quality מרנדר מחדש את אותו טייק ב-1080p, כמשימה חדשה. קבלו קודם אומדן מחיר בחינם, דרך נתיב האומדן.

### באילו מנועים Video Remake יכול להשתמש?

Video Remake משתמש בשני מנועים. Nodaro Prism הוא ברירת המחדל, והוא מרנדר ב-480p, ב-720p או ב-1080p, ויוצר טיוטה ב-480p כששולחים את draft עם הערך true. שלחו את engine עם הערך nodaro-pulse כדי להשתמש ב-Nodaro Pulse, שמרנדר ב-720p או ב-1080p, אין לו טיוטה, והוא יוצר טייק חדש לפי הקליפ והתמונות שלכם.

### האם אפשר לבחור אם הפנים בקליפ יוסתרו?

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

### האם Video Remake עובד בהתקנה באירוח עצמי?

לא. Video Remake רץ רק ב-Nodaro Cloud. בהתקנה באירוח עצמי, כל נתיב שלו מחזיר 404.
