ה-API של Nodaro Motion

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

בעבר Nodaro Motion נקרא Cast Swap. הנתיבים שלו נשארו תחת /v1/cast-swap. כלי ה-MCP עדיין נקרא cast_swap, ומרחב השמות ב-SDK הוא עדיין client.castSwap.

Nodaro Motion רץ רק ב-Nodaro Cloud. בהתקנה באירוח עצמי, כל נתיב של Nodaro Motion מחזיר 404. הנתיבים מקבלים אסימון Bearer. ראו את דף ה-API אימות.

נקודות קצה

גוף הבקשה

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

תפקיד מציין מישהו, משהו או את המקום שבסרטון, ומקבל 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, או סגנון אמנותי. סגנון אמנותי נחשב רק בהרצה של סגנון בלבד (ראו את הסעיף סגנונות אמנותיים).

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

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

{
  "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 Motion Prism.

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

סגנון

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

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

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

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

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

{ "engines": { "motion-prism": "user", "motion-pulse": "precise" } }

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

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

• השדה styleOnly מציין אם המנוע מקבל הרצות של סגנון בלבד. ראו את הסעיף סגנונות אמנותיים.
• השדה preciseArtStyle מציין אם הרצה בסגנון המדויק מקבלת סגנון אמנותי במנוע הזה.
• השדה preciseArtStyleAlone מציין אם במנוע הזה סגנון אמנותי לבדו יכול להיות השינוי של הרצה בסגנון המדויק, בלי תפקיד, ייחוס או פרומפט. הערך שלו הוא false עד שהמנוע יקבל הרצות כאלה. Nodaro עשוי להריץ בקשה כזו כהרצה בסגנון התנועה, והמפה הזו לא מציינת זאת. ראו את הסעיף סגנון אמנותי בהרצה בסגנון המדויק.

שלוש המפות תלויות רק במנוע, ולכן בדקו אותן יחד עם engines. ב-Nodaro Motion Pulse הערך תמיד false בשלושתן. שרת מגרסה שקדמה להן משמיט אותן: התייחסו לכך כאל false לכל מנוע. במנוע שהתשובה עבורו היא "precise", בקשה שאין בה שום דבר אחר לשנות נדחית עם 400 validation_error. כשיש בה משהו אחר לשנות, כגון תפקיד עם תמונות, ייחוס קבוע, prePrompt או postPrompt, היא רצה ומתומחרת כהרצה בסגנון המדויק. היא שומרת על הסגנון האמנותי כש-preciseArtStyle הוא true. Nodaro עשוי ליצור הרצה בסגנון המדויק עם סגנון אמנותי באותה דרך שבה נוצרת הרצה בסגנון התנועה. כל עוד הוא עושה זאת, בקשה ששומרת על סגנון אמנותי במנוע כזה נוצרת ומתומחרת כהרצה בסגנון התנועה, והמשימה שלה רושמת את הסגנון ששלחתם. בקשה עם style: "motion" לא נדרסת אז בכלל, ולכן אין בתשובה styleForced. אז גם בקשה שאין בה שום דבר אחר לשנות מתקבלת.

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

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

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

סגנונות אמנותיים

השדה direction: { style: "<id>" } מצייר את הסרטון בסגנון אמנותי, כגון pop-art. המזהה הוא אחד המזהים בקטלוג של הבורר סגנון. רק Nodaro Motion Prism מקבל סגנון אמנותי. Nodaro Motion Pulse דוחה סגנון אמנותי עם 400 art_style_needs_prism.

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

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

סגנון אמנותי בהרצה בסגנון המדויק. כש-GET /v1/cast-swap/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/cast-swap/estimate מחזיר { engine, totalCredits, expectedCredits, breakdown, privacyCredits?, settlesLower }. באומדן יש שני סכומים כוללים.

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

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

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

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

בקשות חוזרות

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

איכות מלאה

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

• הרצת טיוטה של Nodaro Motion Prism, כלומר הרצה של Nodaro Motion שנעשתה כטיוטה, או הרצת טרנד שברירת המחדל שלה היא טיוטה. האיכות המלאה מרנדרת מחדש את אותו טייק ב-1080p.
• הרצה של Nodaro Motion Pulse ב-720p. האיכות המלאה יוצרת טייק חדש ב-1080p מהקלטים של ההרצה עצמה. הרצת טרנד נוצרת מחדש מגרסת הטרנד שעליה היא רצה. Nodaro Motion Pulse לא יכול לחדד את אותו טייק, ולכן הטייק החדש לא תואם להרצה ב-720p פריים אחר פריים.

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

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

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

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

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

שגיאות

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

דרך ה-SDK

המשאב client.castSwap עוטף את כל הנתיבים. אפשר גם לייבא אותו מ-@nodaro/sdk/cast-swap.

run(params: CastSwapParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: CastSwapParams): Promise<CastSwapEstimate>
fullQualityEstimate(jobId: string): Promise<CastSwapFullQualityEstimate>
fullQuality(jobId: string, params?: { sessionId?: string }): Promise<CastSwapFullQualityResult>
styleChoice(): Promise<CastSwapStyleChoice> // GET /v1/cast-swap/style-choice, public

הטיפוס CastSwapParams הוא גוף הבקשה שתואר למעלה, כשהשדה engine מוגדר מהטיפוס CastSwapEngine, style מהטיפוס CastSwapStyle ("precise" | "motion") ו-motionLength מהטיפוס CastSwapMotionLength. השדה faceMasking עדיין מוגדר בטיפוסים, כדי שקוד ישן ימשיך לעבוד, אבל הוא מיושן והשרת מתעלם ממנו. המתודה estimate() מחזירה תמיד את מזהי המנועים הנוכחיים. הטיפוס CastSwapEstimate הוא האומדן. המתודה run() שולחת את idempotencyKey ללא שינוי בכותרת Idempotency-Key. בלעדיו, לא נשלחת כותרת. המתודה styleChoice() מחזירה את CastSwapStyleChoice, כלומר { engines: { "motion-prism", "motion-pulse" }, styleOnly?, preciseArtStyle? }. כל מנוע הוא CastSwapStyleChoiceOption: "user", "precise" או "flex". השדות styleOnly ו-preciseArtStyle ממפים כל מנוע לערך בוליאני; התייחסו לערך חסר כאל false. הטיפוס CastSwapParams מקבל direction?: { style: string }, והשדה breakdown של האומדן יכול לכלול את referenceAudio.

const { engines, styleOnly } = await client.castSwap.styleChoice()
if (styleOnly?.["motion-prism"] === true && engines["motion-prism"] !== "precise") {
  await client.castSwap.run({ videoUrl, roles: [], style: "motion", direction: { style: "pop-art" } })
}

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

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

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

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

דרך ה-CLI

nodaro cast-swap full-quality estimate <jobId> [--json]
nodaro cast-swap full-quality run <jobId> [--session <id>] [--json]

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

דרך MCP

כלי ה-MCP הוא cast_swap. הכלי מקבל את אותם שדות בכתיב snake case, למשל pre_prompt, prepare_references, in_preview, engine, style ו-motion_length. הוא מקבל גם art_style, סגנון אמנותי ב-Nodaro Motion Prism: מזהה מהקטלוג של הבורר סגנון, כגון pop-art. הפרמטר עובד בהרצה בסגנון התנועה, ובהרצה בסגנון המדויק כשהמנוע מקבל בה סגנון אמנותי. בלי תמונות לתפקידים ובלי ייחוסים, הוא מעצב מחדש את הקליפ כולו כשהמנוע מקבל הרצות של סגנון בלבד. ראו את הסעיף cast_swap בדף וידאו. הכלי לא מקבל הגדרה להכנת הקליפ. בלי confirm, הוא מחזיר את אומדן המחיר ולא גובה כלום. עם confirm: true, אחרי שהמחיר אושר, הוא מתחיל את ההרצה ומחזיר מזהה משימה. הכלים estimate_full_quality ו-full_quality נותנים אומדן מחיר ומתחילים את גרסת האיכות המלאה של טיוטה או של הרצה של Nodaro Motion Pulse ב-720p.