פייפליינים

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

פייפליינים רצים ב-Nodaro Cloud בלבד; מהדורת Community ומהדורת Business מחזירות 403 edition_required. בהתקנה באירוח עצמי, בנו את אותם שלבים כתהליך, עם רכיבים כגון יצירת תסריט, יצירת תמונה ויצירת וידאו. הנתיבים מקבלים אסימון Bearer; אסימונים של אפליקציות OAuth צריכים את ההרשאות שמפורטות למטה. ראו את דף ה-API אימות.

נקודות קצה

שלבים ומצבים

פייפליין עובר שמונה שלבים לפי הסדר. הפרמטר :stage בנתיב הוא אחד מהשמות האלה.

הערך של mode שבוחרים ביצירה קובע מי מקדם את הפייפליין הלאה:

התחלת פייפליין

הנתיב POST /v1/pipelines יוצר את הפייפליין, משריין את הקרדיטים שלו ומתחיל אותו. התגובה היא 201 עם { id }.

curl -X POST https://app.nodaro.ai/v1/pipelines \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "root_node_id": "0e6b2f7c-4a1d-4c8e-9b3f-5d7a2c1e8f4b",
    "story_prompt": "A lighthouse keeper must restart the light before the storm hits.",
    "format": "short_film",
    "target_duration_seconds": 60,
    "mode": "auto",
    "output_resolution": "720p"
  }'

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

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

const { id } = await client.pipelines.create({
  root_node_id: crypto.randomUUID(),
  story_prompt: 'A lighthouse keeper must restart the light before the storm hits.',
  format: 'short_film',
  target_duration_seconds: 60,
  mode: 'auto',
})

{ "id": "c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c" }

לכל פורמט יש טווח אורכים מותר:

מעקב אחרי פייפליין

הנתיב GET /v1/pipelines/:id מחזיר את המצב של הפייפליין. בדקו את המצב מדי כמה שניות, או פתחו את GET /v1/pipelines/:id/events כדי לקבל את השינויים כאירועי שרת (SSE).

{
  "id": "c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c",
  "status": "running",
  "current_stage": "scene_images",
  "mode": "auto",
  "spent_credits": 412,
  "reserved_credits": 1180,
  "upfront_credit_estimate": 1650,
  "failure_reason": null,
  "current_progress_message": "Rendering keyframe 5 of 9",
  "branched_from_pipeline_id": null,
  "branched_from_stage": null
}

השדה status הוא queued, running, awaiting_approval, completed, failed, cancelled או forked. השדה failure_reason מסביר למה פייפליין בסטטוס failed נכשל.

כשהפייפליין בסטטוס completed, הנתיב GET /v1/pipelines/:id/timeline מחזיר את הסרט כנתונים שאפשר לרנדר או להעביר לעורך:

{
  "fps": 24,
  "width": 1280,
  "height": 720,
  "scenes": [
    { "compositeUrl": "https://cdn.nodaro.ai/pipelines/scene-1.mp4", "durationSeconds": 8.5 },
    { "compositeUrl": "https://cdn.nodaro.ai/pipelines/scene-2.mp4", "durationSeconds": 11 }
  ],
  "musicUrl": "https://cdn.nodaro.ai/pipelines/score.mp3",
  "narrationUrl": "https://cdn.nodaro.ai/pipelines/narration.mp3"
}

בזמן ששלב האנימציה רץ, בציר הזמן מופיע גם animateProgress: { totalShots, shotsDone, percent }. כדי לסיים את העריכה בתוכנת עריכה חיצונית, ראו בדף ה-API ייצוא ציר זמן.

curl https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c \
  -H "Authorization: Bearer $NODARO_API_KEY"

curl https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/timeline \
  -H "Authorization: Bearer $NODARO_API_KEY"

const pipeline = await client.pipelines.get(id)
console.log(pipeline.status, pipeline.current_stage)

const timeline = await client.pipelines.getTimeline(id)
for (const scene of timeline.scenes) {
  console.log(scene.compositeUrl, scene.durationSeconds)
}

אישור או דחייה של שלב

במצבים manual ו-guided, כל שלב עוצר בסטטוס awaiting_approval. הנתיב GET /v1/pipelines/:id/pending-approvals מחזיר את השלבים שממתינים, כל אחד בצורה { stage_name, output }. כדי לקרוא שלב במלואו, השתמשו ב-GET /v1/pipelines/:id/stages/:stage, שמחזיר { status, output, critic_feedback }.

• אישור. הנתיב POST /v1/pipelines/:id/stages/:stage/approve מחזיר { ok: true }, והפייפליין ממשיך. כדי לשנות קודם את הפלט של השלב, שלחו { edits }: JSON Patch שמוחל על הפלט לפני האישור.
• דחייה. אפשר לדחות רק את התסריט. הנתיב POST /v1/pipelines/:id/stages/script/reject עם { feedback } מחזיר { ok: true }, והמנוע כותב את התסריט מחדש לפי ההערה שלכם. בקשה לדחות שלב אחר נדחית עם 400 stage_not_implemented. אפשר לדחות את התסריט פעמיים לכל היותר, ופחות מזה אם מבקר התסריט האוטומטי כבר תיקן אותו.

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/approve \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "edits": [{ "op": "replace", "path": "/title", "value": "The Last Light" }] }'

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/reject \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "feedback": "Make the story darker and more suspenseful." }'

const approvals = await client.pipelines.pendingApprovals(id)
const { output } = await client.pipelines.getStage(id, 'script')

await client.pipelines.approveStage(id, 'script', [
  { op: 'replace', path: '/title', value: 'The Last Light' },
])
// or
await client.pipelines.rejectStage(id, 'script', 'Make the story darker and more suspenseful.')

נקודות אישור בתוך שלב האנימציה

במצבים manual ו-guided, השלב animate_audio_edit יכול לעצור בשתי נקודות אישור משלו:

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

הנתיב POST /v1/pipelines/:id/sub-gates/:gate/approve ממשיך את השלב ומחזיר { ok: true, gate, resumed_at }. הנתיב POST /v1/pipelines/:id/sub-gates/:gate/reject גורם לשלב ולפייפליין להיכשל, והקרדיטים שלא נדרשו מוחזרים. במצב auto, השלב ממשיך בלי לעצור.

שבירות מאץ׳ קאט בשלב תמונות הסצנה

השלב scene_images יכול לעצור בנקודת אישור שלישית, match_cut_break_pending. הוא עוצר בה בכל מצב, כולל auto, כשמאץ׳ קאט מתוכנן בין שני שוטים נשבר. הפלט של השלב מציג את השוטים ב-match_cut_break_pending.

נתיבי ה-sub-gates שלמעלה לא משחררים את נקודת האישור הזו. הם מחזירים 400 invalid_sub_gate, והודעת השגיאה מציינת את הנתיב שכן משחרר אותה. אשרו כל שבירה עם POST /v1/pipelines/:id/entities/:sceneId/helpers/accept_match_cut_break ו-{ "shotId": "<shot id>" }. הפרמטר sceneId הוא ה-id של הסצנה שהשוט נמצא בה, לא ה-metadata.scene_id שלה. הנתיב GET /v1/pipelines/:id/entities?type=scene מחזיר את הסצנות, כל אחת עם השוטים שלה ב-metadata.scene_node_data.shots.

אישור של שבירה דורש את ההרשאה pipelines:approve ולא עולה קרדיטים. הקריאה מחזירה { ok: true, pendingRemaining }, כשהשדה pendingRemaining הוא מספר השבירות שעדיין ממתינות. כשהאחרונה מאושרת, השלב ממשיך. שבירה מאושרת נשארת מאושרת כשהשלב scene_images רץ שוב. הרצה חוזרת של השלב shot_list מתכננת את הסצנות מחדש ומבטלת את כל האישורים, ולכן צריך לאשר שוב כל שבירה שחוזרת.

צ׳אט עם הבמאי

במצב guided, לשלב שממתין לאישור יש צ׳אט. שלחו הודעה של עד 8,000 תווים עם POST /v1/pipelines/:id/stages/:stage/chat ו-{ message }. הבמאי עונה במשפט אחד, ויכול להציע שינוי.

{
  "turnId": "f1a3c5e7-9b2d-4f6a-8c1e-3d5b7f9a2c4e",
  "role": "assistant",
  "content": "I moved the keeper's reason for staying into scene 2 and tightened the ending.",
  "proposed_change": {
    "change_type": "edit_artifact",
    "json_patch": [{ "op": "replace", "path": "/scenes/1/description", "value": "The keeper finds his late wife's log and decides to stay." }]
  }
}

השדה proposed_change הוא null, edit_artifact עם json_patch או suggest_branch עם from_stage ו-reason.

כדי לקבל הצעה, קראו ל-POST /v1/pipelines/:id/stages/:stage/chat/turns/:turnId/apply. הנתיב מחזיר { applied: true, attemptId, newOutput } ומאשר את השלב. כשהשינוי שובר את התוכנית, למשל כשהוא מסיר דמות שסצנה עדיין משתמשת בה, הנתיב מחזיר { applied: false, error }, והבמאי מוסיף הודעה שמסבירה מה לתקן. הצעה לא תקינה, או הצעה לשלב שכבר לא ממתין, נדחית עם 409. הנתיב GET /v1/pipelines/:id/stages/:stage/chat מחזיר { turns }, כלומר את כל השיחה.

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

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/stages/script/chat \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Make the keeper'\''s motivation clearer in scene 2." }'

const reply = await client.pipelines.chatStage(id, 'script', "Make the keeper's motivation clearer in scene 2.")
if (reply.proposed_change) {
  const result = await client.pipelines.applyChatProposal(id, 'script', reply.turnId)
  if (!result.applied) console.log(result.error.code)
}

יצירת הסתעפות של פייפליין גמור

הנתיב POST /v1/pipelines/:id/branch מריץ מחדש פייפליין בסטטוס completed החל משלב אחד, כפייפליין חדש. השלבים שלפני fromStage מועתקים במצב מאושר, השלב שב-fromStage מתחיל לרוץ, והשלבים שאחריו נוצרים מאפס. הפייפליין המקורי נשאר בסטטוס completed.

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

curl -X POST https://app.nodaro.ai/v1/pipelines/c2f8a4e6-1b9d-4f3a-8c7e-6d2b9f1a5e3c/branch \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fromStage": "scene_images" }'

const branch = await client.pipelines.branch(id, { fromStage: 'scene_images' })
console.log(branch.pipelineId, branch.clonedStages)

התגובה היא 201 עם { pipelineId, clonedStages, clonedEntities }: המזהה של הפייפליין החדש, השלבים שהועתקו במצב מאושר ומספר הדמויות, האובייקטים והמיקומים שהועתקו. הערך של fromStage יכול להיות כל שם של שלב מהטבלה שלמעלה.

ביטול או פיצול של פייפליין

• ביטול. הנתיב POST /v1/pipelines/:id/cancel עוצר פייפליין שרץ ומחזיר { ok: true }. הקרדיטים ששוריינו לעבודה שעוד לא רצה מוחזרים. קריאה לפייפליין שכבר הושלם, נכשל או בוטל נדחית עם 409 already_terminal, ושום דבר לא משתנה.
• פיצול. הנתיב POST /v1/pipelines/:id/fork משחרר את הקנבס מהפייפליין. כל רכיב שהפייפליין יצר הופך לרכיב רגיל שאפשר לערוך, הקרדיטים שלא נדרשו מוחזרים, והסטטוס הופך ל-forked. אי אפשר לבטל פיצול. כדי להמשיך עם המנוע, התחילו פייפליין חדש.

קרדיטים

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

שימוש דרך MCP ודרך ה-SDK

ה-SDK עוטף כל נתיב כ-client.pipelines.*. ל-CLI אין פקודות לפייפליינים. עוזרי AI משתמשים בכלי ה-MCP האלה:

כדי לביים סרט דרך עוזר AI, שלב אחר שלב, ראו את הדף במאי הקולנוע.

שגיאות