파이프라인

파이프라인 API는 코드에서 스토리 → 동영상을 실행합니다. 한 줄짜리 스토리를 보내면, 파이프라인 엔진이 스크립트를 쓰고, 출연진, 소품, 장소를 만들고, 샷을 계획합니다. 그런 다음 키프레임을 렌더링하고, 사운드와 함께 애니메이션을 만들고, 영화를 합칩니다. 각 단계는 내 승인을 기다리거나, 스스로 실행되거나, 감독과의 채팅을 열 수 있습니다.

파이프라인은 Nodaro Cloud에서만 실행됩니다. Community Edition과 Business 에디션은 403 edition_required로 응답합니다. 셀프 호스팅 설치에서는 대본 생성, 이미지 생성, 동영상 생성 같은 노드로 같은 단계를 워크플로로 구성하세요. 라우트는 Bearer 토큰을 받으며, OAuth 앱 토큰에는 아래에 나열된 스코프가 필요합니다. 인증을 참조하세요.

엔드포인트

단계와 모드

파이프라인은 8개 단계를 순서대로 거칩니다. 경로의 :stage는 다음 이름 중 하나입니다.

생성할 때 고른 mode가 누가 파이프라인을 진행시킬지 정합니다.

파이프라인 시작

POST /v1/pipelines는 파이프라인을 만들고, 크레딧을 예약하고, 시작합니다. { id }와 함께 201로 응답합니다.

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를 열어 변경 사항을 서버 전송 이벤트로 받으세요.

{
  "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 }도 들어 있습니다. 외부 편집기에서 컷을 마무리하려면 타임라인 내보내기를 참조하세요.

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입니다.
• 거부. 스크립트만 거부할 수 있습니다. { feedback }과 함께 POST /v1/pipelines/:id/stages/script/reject를 보내면 { ok: true }를 반환하고, 엔진이 내 메모를 반영해 스크립트를 다시 씁니다. 다른 단계는 400 stage_not_implemented로 응답합니다. 스크립트는 최대 두 번 거부할 수 있으며, 자동 스크립트 평가 AI가 이미 수정했다면 그보다 적게 거부할 수 있습니다.

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에 해당 샷이 나열됩니다.

위의 하위 게이트 라우트로는 이를 해제할 수 없습니다. 이 라우트는 400 invalid_sub_gate로 응답하며, 오류 메시지에 해제할 수 있는 라우트가 나옵니다. 각 불일치는 { "shotId": "<shot id>" }와 함께 POST /v1/pipelines/:id/entities/:sceneId/helpers/accept_match_cut_break로 수락하세요. sceneId는 샷이 속한 장면의 id이며, metadata.scene_id가 아닙니다. GET /v1/pipelines/:id/entities?type=scene은 장면을 나열하며, 각 장면의 샷은 metadata.scene_node_data.shots에 있습니다.

불일치를 수락하려면 pipelines:approve 스코프가 필요하며, 크레딧은 들지 않습니다. 호출은 아직 기다리는 불일치 수를 담은 { ok: true, pendingRemaining }을 반환합니다. 마지막 불일치가 수락되면 단계가 계속됩니다. 수락한 불일치는 scene_images 단계를 다시 실행해도 수락된 상태로 남습니다. shot_list 단계를 다시 실행하면 장면이 새로 계획되고 모든 수락이 지워지므로, 다시 나타난 불일치는 다시 수락해야 합니다.

감독과 채팅

guided 모드에서는 승인을 기다리는 단계에 채팅이 있습니다. { message }와 함께 POST /v1/pipelines/:id/stages/:stage/chat으로 최대 8,000자의 메시지를 보내세요. 감독은 한 문장으로 답하며 변경을 제안할 수 있습니다.

{
  "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이거나, json_patch가 있는 edit_artifact이거나, from_stage와 reason이 있는 suggest_branch입니다.

제안을 수락하려면 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)

이 라우트는 { pipelineId, clonedStages, clonedEntities }와 함께 201로 응답합니다. 새 파이프라인의 ID, 승인된 상태로 복사된 단계, 복사된 캐릭터, 오브젝트, 장소의 수입니다. 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로 총액의 상한을 정합니다. 크레딧을 참조하세요.

MCP와 SDK에서 사용

SDK는 모든 라우트를 client.pipelines.*로 감쌉니다. CLI에는 파이프라인 명령이 없습니다. AI 어시스턴트는 다음 MCP 도구를 사용합니다.

어시스턴트에서 가이드 방식으로 영화를 연출하는 방법은 Film Director를 참조하세요.

오류