# פייפליינים

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

Source: https://nodaro.ai/he/docs/developers/api/pipelines

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

פייפליינים רצים ב-Nodaro Cloud בלבד; מהדורת Community ומהדורת Business מחזירות `403 edition_required`. בהתקנה באירוח עצמי, בנו את אותם שלבים כתהליך, עם רכיבים כגון [יצירת תסריט](https://nodaro.ai/docs/nodes/video/generate-script), [יצירת תמונה](https://nodaro.ai/docs/nodes/image/generate-image) ו[יצירת וידאו](https://nodaro.ai/docs/nodes/video/generate-video). הנתיבים מקבלים אסימון Bearer; אסימונים של אפליקציות OAuth צריכים את ההרשאות שמפורטות למטה. ראו את דף ה-API [אימות](https://nodaro.ai/docs/developers/api/authentication).

## נקודות קצה
| שיטה | נתיב | הרשאה | מה היא עושה |
| --- | --- | --- | --- |
| `POST` | `/v1/pipelines` | `pipelines:execute` | יצירת פייפליין והתחלתו. |
| `GET` | `/v1/pipelines` | `pipelines:read` | רשימת הפייפליינים שלכם, מהחדש לישן. |
| `GET` | `/v1/pipelines/:id` | `pipelines:read` | קבלת הסטטוס, השלב הנוכחי והקרדיטים. |
| `GET` | `/v1/pipelines/:id/events` | `pipelines:read` | הזרמת האירועים של הפייפליין כאירועי שרת (SSE). |
| `GET` | `/v1/pipelines/:id/stages/:stage` | `pipelines:read` | קבלת הסטטוס, הפלט והמשוב של המבקר על שלב אחד. |
| `GET` | `/v1/pipelines/:id/pending-approvals` | `pipelines:read` | רשימת השלבים שממתינים לאישור. |
| `GET` | `/v1/pipelines/:id/timeline` | `pipelines:read` | קבלת הסרט המורכב: הסצנות, האורכים והאודיו. |
| `GET` | `/v1/pipelines/:id/entities?type=` | `pipelines:read` | רשימת הדמויות, האובייקטים, המיקומים או הסצנות של הפייפליין. |
| `POST` | `/v1/pipelines/:id/stages/:stage/approve` | `pipelines:approve` | אישור שלב, עם עריכות אם רוצים. |
| `POST` | `/v1/pipelines/:id/stages/:stage/reject` | `pipelines:approve` | דחיית התסריט עם משוב, כדי שייכתב מחדש. |
| `POST` | `/v1/pipelines/:id/sub-gates/:gate/approve` | `pipelines:approve` | אישור באחת מנקודות האישור שבתוך שלב האנימציה. |
| `POST` | `/v1/pipelines/:id/sub-gates/:gate/reject` | `pipelines:approve` | דחייה בנקודת האישור הזו ועצירת הפייפליין. |
| `POST` | `/v1/pipelines/:id/entities/:sceneId/helpers/accept_match_cut_break` | `pipelines:approve` | אישור של שבירת מאץ׳ קאט אחת בשלב תמונות הסצנה. |
| `POST` | `/v1/pipelines/:id/stages/:stage/chat` | `pipelines:approve` | שליחת הודעה לבמאי (מצב מונחה). |
| `GET` | `/v1/pipelines/:id/stages/:stage/chat` | `pipelines:read` | קריאת הצ׳אט של שלב. |
| `POST` | `/v1/pipelines/:id/stages/:stage/chat/turns/:turnId/apply` | `pipelines:approve` | החלת שינוי שהבמאי הציע. |
| `POST` | `/v1/pipelines/:id/branch` | `pipelines:execute` | הרצה מחדש של פייפליין שהושלם, החל משלב מסוים, כפייפליין חדש. |
| `POST` | `/v1/pipelines/:id/fork` | `pipelines:execute` | עצירת הפייפליין ושמירת הקנבס שלו כרכיבים רגילים. |
| `POST` | `/v1/pipelines/:id/cancel` | `pipelines:execute` | ביטול פייפליין שרץ והחזר הקרדיטים שלא נדרשו. |

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

| שלב | מה הוא מפיק |
| --- | --- |
| `script` | תוכנית הסיפור: הכותרת, הסצנות, השחקנים, המיקומים והאביזרים. |
| `characters` | דמות לכל תפקיד בליהוק. |
| `objects` | האביזרים שהסיפור צריך. |
| `locations` | המקומות שהסיפור מתרחש בהם. |
| `shot_list` | השוטים של כל סצנה, עם בחירות המצלמה והרציפות שלהם. |
| `scene_images` | פריים מפתח לכל שוט. |
| `animate_audio_edit` | השוטים המונפשים, עם דיאלוג, קריינות, מוזיקה ועריכה. |
| `post_merge` | הסרט הסופי, אחרי המיזוג. |

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

| מצב | מה קורה |
| --- | --- |
| `manual` (ברירת המחדל) | כל שלב עוצר בסטטוס `awaiting_approval`. אתם מאשרים, עורכים או דוחים אותו, והפייפליין ממשיך. |
| `auto` | המנוע מריץ כל שלב בעצמו. מבקרים אוטומטיים בודקים את התסריט, מוודאים שלא חסרים שחקנים, מיקומים או אביזרים, ובודקים את פריימי המפתח. אחרי 3 הכרעות חוסמות ברצף, הפייפליין נכשל והקרדיטים שלא נדרשו מוחזרים. הוא עוצר רק ב[שבירת מאץ׳ קאט](#match-cut-breaks-in-the-scene-images-stage), עד שכל שבירה מאושרת. בינתיים הסטטוס נשאר `running`, והנתיב `pending-approvals` מציג את השלב `scene_images`. |
| `guided` | כמו `manual`, ובנוסף צ׳אט עם הבמאי בשלבים `script` ו-`post_merge`. |

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

**curl**

```bash
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"
}'
```

**TypeScript SDK**

```ts

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',
})
```

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

<TypeTable
type={{
story_prompt: { type: 'string', description: 'על מה הסרט, עד 4,000 תווים.', required: true },
format: { type: "'trailer' | 'short_film' | 'music_video' | 'reel' | 'commercial'", description: 'סוג הסרט. הוא קובע את האורך המותר.', required: true },
target_duration_seconds: { type: 'integer', description: 'אורך הסרט בשניות, בתוך הטווח של הפורמט. לכל היותר 600.', required: true },
root_node_id: { type: 'string', description: 'מזהה לשורש הפייפליין. כשאף רכיב על הקנבס לא התחיל את הפייפליין, שלחו כל מזהה ייחודי, למשל UUID חדש.', required: true },
mode: { type: "'manual' | 'auto' | 'guided'", description: 'מי מקדם את הפייפליין הלאה.', default: 'manual' },
output_resolution: { type: "'480p' | '720p' | '1080p' | '4K'", description: 'הרזולוציה של הסרט הסופי.', default: '720p' },
language: { type: 'string', description: 'השפה של התסריט ושל הדיאלוג.', default: 'en' },
workflow_id: { type: 'string (uuid)', description: 'תהליך שלכם שבו הסרט ייבנה.' },
style_directives: { type: 'object', description: 'הוראות סגנון לכל הסרט.' },
config: { type: 'object', description: 'הגדרות אופציונליות שגוברות על ההגדרות של הפייפליין. ביניהן המתגים music_enabled, narration_enabled ו-lipsync_enabled, כל אחד מהם true כברירת מחדל, והשדות image_model, video_model ו-script_llm, שבוחרים את המודלים.' },
max_cost_credits: { type: 'integer', description: 'תקרה לקרדיטים שהפייפליין יכול להוציא.' },
}}
/>

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

| פורמט | הקצר ביותר | הארוך ביותר |
| --- | --- | --- |
| `reel` | 7 שנ׳ | 90 שנ׳ |
| `commercial` | 10 שנ׳ | 90 שנ׳ |
| `trailer` | 30 שנ׳ | 180 שנ׳ |
| `short_film` | 12 שנ׳ | 600 שנ׳ |
| `music_video` | 30 שנ׳ | 600 שנ׳ |

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

```json
{
"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` מחזיר את הסרט כנתונים שאפשר לרנדר או להעביר לעורך:

```json
{
"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 [ייצוא ציר זמן](https://nodaro.ai/docs/developers/api/studio-productions#export-a-timeline-to-an-editing-app).

**curl**

```bash
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"
```

**TypeScript SDK**

```ts
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**

```bash
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." }'
```

**TypeScript SDK**

```ts
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 }`. הבמאי עונה במשפט אחד, ויכול להציע שינוי.

```json
{
"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`.

| שלב | מה הבמאי יכול להציע | הודעות |
| --- | --- | --- |
| `script` | עריכה של התוכנית (JSON Patch על הכותרת, הסצנות, השחקנים, המיקומים או האביזרים), או הסתעפות כשהשינוי מבני מדי לתיקון עם JSON Patch. | 20 לכל פייפליין |
| `post_merge` | אבחון של הסרט הסופי והסתעפות משלב מוקדם יותר. אי אפשר להחיל JSON Patch על הסרט עצמו. | 8 לכל פייפליין |

כדי לקבל הצעה, קראו ל-`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**

```bash
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." }'
```

**TypeScript SDK**

```ts
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**

```bash
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" }'
```

**TypeScript SDK**

```ts
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 [קרדיטים](https://nodaro.ai/docs/developers/api/credits).

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

| כלי | הרשאה | מה הוא עושה |
| --- | --- | --- |
| `start_pipeline` | `pipelines:execute` | התחלת פייפליין. מצב ברירת המחדל שלו הוא `auto`. |
| `get_pipeline_status` | `pipelines:read` | קריאת הסטטוס, השלב והקרדיטים. |
| `pipeline_pending_approvals` | `pipelines:read` | רשימת השלבים שממתינים לאישור. |
| `chat_pipeline_stage`, `apply_chat_proposal` | `pipelines:approve` | צ׳אט עם הבמאי והחלת הצעה. |
| `get_pipeline_stage_chat` | `pipelines:read` | קריאת הצ׳אט של שלב. |
| `branch_pipeline` | `pipelines:execute` | יצירת הסתעפות של פייפליין שהושלם. |

כדי לביים סרט דרך עוזר AI, שלב אחר שלב, ראו את הדף [במאי הקולנוע](https://nodaro.ai/docs/mcp/film-director).

## שגיאות
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| `400` | `validation_error` | גוף הבקשה לא תקין, למשל אורך של פחות מ-5 שניות או של יותר מ-3,600 שניות, או `fromStage` בהסתעפות שהוא לא שם של שלב. |
| `400` | `duration_out_of_bounds` | האורך מחוץ לטווח של הפורמט, או יותר מ-600 שניות. |
| `400` | `pipeline_not_completed` | התבקשה הסתעפות מפייפליין שהסטטוס שלו הוא לא `completed`. |
| `400` | `invalid_stage` | שליחה או קריאה של צ׳אט מציינת שלב שהוא לא `script`, `shot_list` או `post_merge`. |
| `400` | `invalid_stage_name` | אישור מציין שלב שהוא לא אחד משמונת השלבים. בקשה לקרוא שלב כזה נדחית עם `404` ועם הקוד הזה. |
| `400` | `stage_not_implemented` | קריאת דחייה מציינת שלב שהוא לא `script`. |
| `400` | `invalid_change_type_for_stage` | הוצע JSON Patch לשלב `post_merge`, שמקבל רק הסתעפות. |
| `400` | `invalid_sub_gate` | נקודת האישור היא לא אחת מאלה שנתיבי ה-`sub-gates` מטפלים בהן. ב-`match_cut_break_pending`, ההודעה מציינת את הנתיב שמאשר כל שבירה. |
| `400` | `shot_not_found` | השוט לאישור לא נמצא בסצנה הזו. |
| `400` | `not_a_match_cut` | לשוט לאישור אין מאץ׳ קאט מתוכנן. |
| `400` | `invalid_entity_type` | הרשימה של `entities` התבקשה עם `type` שהוא לא `character`, `object`, `location` או `scene`. |
| `401` | `unauthorized` | האסימון חסר, לא תקין או מבוטל. |
| `402` | `insufficient_credits` | אין בחשבון מספיק קרדיטים לשריון. |
| `403` | `edition_required` | המופע הוא לא Nodaro Cloud. |
| `403` | `insufficient_scope` | לאסימון של אפליקציית OAuth חסרה ההרשאה שהנתיב דורש. |
| `404` | `not_found` | אין לכם פייפליין עם המזהה הזה. בקריאה לנתיב `sub-gates`, הקוד הזה אומר גם שהשלב לא ממתין בנקודת האישור הזו. |
| `404` | `pipeline_not_found` | קריאת הסתעפות מציינת פייפליין שלא קיים או לא שייך לכם. |
| `404` | `stage_not_started` | השלב שביקשתם לקרוא עוד לא התחיל. |
| `404` | `stage_not_found` | קריאה לנתיב `sub-gates` הגיעה לפייפליין ששלב האנימציה שלו עוד לא התחיל. קריאה לאישור או לדחייה של שלב נדחית עם `409` ועם הקוד הזה. |
| `404` | `scene_not_found` | אין בפייפליין סצנה עם המזהה הזה. |
| `409` | `patch_invalid` | הצעה מהצ׳אט היא לא שינוי תקין, ואי אפשר היה להחיל אותה. |
| `409` | `stage_not_awaiting` | השלב כבר לא ממתין לאישור, כשמחילים הצעה מהצ׳אט או מאשרים עם עריכות. |
| `409` | `stage_already_advanced` | השלב כבר לא ממתין לאישור, כשמאשרים בלי עריכות או דוחים. |
| `409` | `stage_not_awaiting_approval` | קריאה לנתיב `sub-gates` הגיעה לשלב אנימציה שלא ממתין לאישור. |
| `409` | `already_terminal` | קריאת ביטול הגיעה לפייפליין שכבר הושלם, נכשל או בוטל. |
| `409` | `critic_retry_cap_reached` | כבר תיקנו את התסריט פעמיים: אתם או מבקר התסריט האוטומטי. |
| `409` | `scene_not_planned` | לסצנה עדיין אין תוכנית שוטים, ולכן אי אפשר לאשר בה שבירה. |
| `501` | `chat_not_wired_for_stage` | לשלב אין צ׳אט שעובד. כרגע זה נכון רק ל-`shot_list`. |

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

### מה מפיק פייפליין של סיפור ← וידאו?

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

### האם פייפליין יכול לרוץ בלי שמישהו יאשר אותו?

כן. צרו את הפייפליין כשהשדה mode מוגדר ל-auto, והמנוע מריץ כל שלב בעצמו, בזמן שמבקרים אוטומטיים בודקים את הפלט. בדקו את הסטטוס מדי כמה שניות עם GET /v1/pipelines/:id, עד שהוא completed או failed. ההרצה עוצרת רק כשמאץ׳ קאט מתוכנן בין שני שוטים נשבר. הסטטוס נשאר אז running, והנתיב GET /v1/pipelines/:id/pending-approvals מציג את השלב scene_images עד שכל שבירה מאושרת.

### איך מריצים מחדש סרט גמור משלב מסוים?

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

### מה קורה לקרדיטים שלי כשמבטלים פייפליין?

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

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

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