Nodaro 문서파이프라인
TypeScript로 스토리 → 동영상 파이프라인을 시작하고 단계별로 추적합니다. 단계를 승인하고, 감독과 채팅하고, 완성된 타임라인을 읽습니다.
client.pipelines는 스토리 → 동영상 파이프라인을 실행합니다. 스토리 프롬프트를 영화로 만드는, 여러 단계로 이루어진 프로덕션입니다. 파이프라인은 script, characters, objects, locations, shot_list, scene_images, animate_audio_edit, post_merge의 8개 단계를 거치며, 각 단계에서 멈춰 내 승인을 기다릴 수 있습니다. 스튜디오의 영화 만들기를 코드에서 사용하는 버전입니다. 이 메서드들은 파이프라인 REST API를 호출합니다.
모드
| 모드 | 각 단계에서 일어나는 일 |
|---|---|
manual(기본값) | 모든 단계가 내 승인을 기다립니다. 각 단계를 승인하세요. 스크립트는 거부할 수도 있습니다. |
auto | 엔진이 모든 단계를 스스로 승인하고 끝까지 실행합니다. 매치 컷 불일치에서만 멈추며, 모든 불일치가 수락될 때까지 기다립니다. 그동안 상태는 running으로 유지되고, pendingApprovals(id)에 scene_images 단계가 나타납니다. |
guided | manual과 같지만, 단계에 대해 감독과 채팅하고 감독이 제안한 변경을 적용할 수도 있습니다. |
파이프라인의 상태는 queued, running, awaiting_approval, completed, failed, cancelled, forked 중 하나입니다.
메서드
| 메서드 | 스코프 | 하는 일 |
|---|---|---|
create(input) | pipelines:execute | 파이프라인을 시작합니다 |
get(id) | pipelines:read | 파이프라인의 상태와 크레딧을 읽습니다 |
list() | pipelines:read | 내 파이프라인을 나열합니다 |
cancel(id) | pipelines:execute | 파이프라인을 중지합니다 |
pendingApprovals(id) | pipelines:read | 승인을 기다리는 단계를 나열합니다 |
approveStage(id, stage, edits?) | pipelines:approve | 단계를 승인하며, 선택적으로 수정을 적용합니다 |
rejectStage(id, stage, feedback) | pipelines:approve | 스크립트를 거부하고 다시 쓰게 합니다 |
approveSubGate(id, gate) | pipelines:approve | 애니메이션 단계 안의 체크포인트를 승인합니다 |
getStage(id, stage) | pipelines:read | 단계 하나의 출력을 읽습니다 |
getTimeline(id) | pipelines:read | 조립된 영화를 읽습니다 |
branch(id, input) | pipelines:execute | 완료된 파이프라인을 한 단계부터 다시 실행합니다 |
chatStage(pipelineId, stage, message) | pipelines:approve | 감독에게 단계 변경을 요청합니다 |
applyChatProposal(pipelineId, stage, turnId) | pipelines:approve | 감독이 제안한 변경을 수락합니다 |
getStageChat(pipelineId, stage) | pipelines:read | 단계의 채팅을 읽습니다 |
스코프는 OAuth 토큰에 적용됩니다. API 토큰과 세션은 스코프의 제한을 받지 않습니다.
client.pipelines
create(input)
파이프라인을 시작합니다. auto 모드에서는 매치 컷 불일치로 멈추지 않는 한 스스로 끝까지 실행됩니다. 상태는 get()을, 결과는 getTimeline()을 폴링하세요. manual 또는 guided 모드에서는 pendingApprovals(), approveStage(), approveSubGate()로 진행하세요.
create(input: PipelineInput): Promise<{ id: string }>속성
타입
const { id } = await client.pipelines.create({
story_prompt: "A lighthouse keeper finds a message in a bottle that predicts tomorrow's storm.",
target_duration_seconds: 60,
format: "short_film",
root_node_id: "pipeline-root",
mode: "auto",
})get(id)
파이프라인의 현재 상태를 읽습니다. auto 실행을 끝까지 추적하려면 이 메서드를 폴링하세요. 매치 컷 불일치에서 멈춘 실행은 running으로 유지되므로 pendingApprovals(id)도 확인하세요.
get(id: string): Promise<PipelineRecord>속성
타입
const pipeline = await client.pipelines.get(id)
console.log(pipeline.status, pipeline.current_stage, pipeline.current_progress_message)PipelineRecord에는 id, status, current_stage, mode, spent_credits, reserved_credits, upfront_credit_estimate, failure_reason(상태가 failed일 때 설정됨), current_progress_message가 있고, 브랜치에는 branched_from_pipeline_id와 branched_from_stage도 있습니다.
list()
내 파이프라인을 최신 항목부터 나열합니다.
list(): Promise<PipelineRecord[]>const pipelines = await client.pipelines.list()cancel(id)
실행 중인 파이프라인을 중지합니다. 사용하지 않은 예약 크레딧은 환불됩니다. 이미 끝난 파이프라인을 취소해도 아무것도 바뀌지 않습니다.
cancel(id: string): Promise<{ ok: true }>속성
타입
await client.pipelines.cancel(id)pendingApprovals(id)
승인을 기다리는 단계를 각 단계의 출력과 함께 나열합니다. auto 실행 중에는 엔진이 단계를 스스로 승인하므로, 매치 컷 불일치로 멈추지 않는 한 목록이 비어 있습니다.
pendingApprovals(id: string): Promise<Array<{ stage_name: PipelineStageName; output: unknown }>>속성
타입
const approvals = await client.pipelines.pendingApprovals(id)
for (const { stage_name, output } of approvals) console.log(stage_name, output)approveStage(id, stage, edits?)
단계를 승인해 파이프라인이 다음으로 넘어가게 합니다. 승인하기 전에 단계의 출력을 변경하려면 JSON Patch인 edits를 전달하세요.
approveStage(id: string, stage: PipelineStageName, edits?: unknown): Promise<{ ok: true }>속성
타입
await client.pipelines.approveStage(id, "script")
await client.pipelines.approveStage(id, "script", [
{ op: "replace", path: "/title", value: "The Keeper's Warning" },
])rejectStage(id, stage, feedback)
메모와 함께 스크립트를 거부하면, 엔진이 그 메모를 반영해 스크립트를 다시 씁니다. 거부할 수 있는 단계는 script뿐이며, 다른 단계는 stage_not_implemented로 실패합니다. 스크립트는 최대 2번 거부할 수 있으며, 자동 스크립트 검토기가 이미 스크립트를 수정했다면 그보다 적게 거부할 수 있습니다.
rejectStage(id: string, stage: PipelineStageName, feedback: string): Promise<{ ok: true }>속성
타입
await client.pipelines.rejectStage(id, "script", "Make the story darker and more suspenseful")approveSubGate(id, gate)
animate_audio_edit 단계 안의 dialogue_recheck 같은 체크포인트를 승인해, 파이프라인이 다음 과정으로 이어지게 합니다.
scene_images 단계에는 자체 체크포인트인 match_cut_break_pending이 있으며, approveSubGate로는 이를 해제할 수 없습니다. 대신 각 불일치를 REST API로 수락하세요. 장면 이미지 단계의 매치 컷 불일치를 참조하세요.
approveSubGate(id: string, gate: SubGateName): Promise<{ ok: true; gate: SubGateName; resumed_at: string }>속성
타입
await client.pipelines.approveSubGate(id, "dialogue_recheck")getStage(id, stage)
단계 하나의 status, output, critic_feedback을 읽습니다. 스크립트나 계획을 승인하기 전에 살펴볼 때 사용하세요.
getStage(id: string, stage: PipelineStageName): Promise<{ status: string; output: unknown; critic_feedback: unknown }>속성
타입
const { status, output } = await client.pipelines.getStage(id, "script")getTimeline(id)
조립된 영화를 읽습니다. 순서대로 놓인 장면과 그 길이, 오디오 URL, 애니메이션 진행 상황이 담깁니다. 직접 렌더링하거나 편집기에 넘기세요.
getTimeline(id: string): Promise<PipelineTimeline>속성
타입
const timeline = await client.pipelines.getTimeline(id)
for (const scene of timeline.scenes) console.log(scene.compositeUrl, scene.durationSeconds)PipelineTimeline에는 fps, width, height, scenes(각각 { compositeUrl, durationSeconds }), musicUrl, narrationUrl, 그리고 totalShots, shotsDone, percent가 담긴 animateProgress가 있습니다.
branch(id, input)
완료된 파이프라인을 한 단계부터 새 파이프라인으로 다시 실행합니다. 그 앞의 단계는 승인된 상태로 복사됩니다. 원래 파이프라인은 completed로 유지됩니다.
branch(id: string, input: { fromStage: PipelineStageName }): Promise<{ pipelineId: string; clonedStages: string[]; clonedEntities: number }>속성
타입
const { pipelineId } = await client.pipelines.branch(id, { fromStage: "scene_images" })chatStage(pipelineId, stage, message)
guided 모드에서 감독에게 메시지를 보냅니다. 파이프라인의 모드가 guided이고, 단계가 awaiting_approval 상태여야 합니다. 답변에는 applyChatProposal()로 수락할 수 있는 proposed_change가 들어 있을 수 있습니다. 채팅은 script처럼 채팅을 지원하는 단계에서 사용할 수 있습니다.
chatStage(pipelineId: string, stage: ChatEnabledStage, message: string): Promise<{
turnId: string
role: "assistant"
content: string
proposed_change: ProposedChange | null
}>속성
타입
const { content, proposed_change, turnId } = await client.pipelines.chatStage(
id,
"script",
"Can you make the protagonist's motivation clearer in scene 2?",
)applyChatProposal(pipelineId, stage, turnId)
감독이 이전 턴에서 제안한 변경을 수락합니다. 변경이 검사되고, 단계의 새 버전으로 저장된 다음, 단계가 승인됩니다.
applyChatProposal(pipelineId: string, stage: ChatEnabledStage, turnId: string): Promise<
| { applied: true; attemptId: string; newOutput: unknown }
| { applied: false; error: { code: string; detail?: unknown } }
>속성
타입
const result = await client.pipelines.applyChatProposal(id, "script", turnId)
if (result.applied) console.log("Approved:", result.newOutput)
else console.log("Not applied:", result.error.code)변경을 적용할 수 없지만 복구할 수 있으면 결과는 applied: false이며, 감독이 이미 힌트를 담은 답변을 추가해 둔 상태입니다. 복구할 수 없는 실패는 409 오류를 발생시킵니다.
getStageChat(pipelineId, stage)
단계의 채팅 기록을 읽습니다. 첫 메시지를 보내기 전에는 비어 있습니다.
getStageChat(pipelineId: string, stage: ChatEnabledStage): Promise<{ turns: ChatTurn[] }>속성
타입
const { turns } = await client.pipelines.getStageChat(id, "script")각 ChatTurn에는 id, turn_n, role, content, proposed_change, applied_to_attempt_id, created_at이 있습니다.
자주 묻는 질문
Nodaro 파이프라인은 무엇인가요?
파이프라인은 스토리 프롬프트로 영화를 여러 단계에 걸쳐 만듭니다. 스크립트, 캐릭터, 오브젝트, 장소, 샷 목록, 장면 이미지, 오디오와 편집이 포함된 애니메이션, 최종 병합 단계입니다. 스튜디오의 영화 만들기를 화면 없이 실행하는 버전입니다.
단계마다 승인하지 않고 파이프라인을 실행하려면 어떻게 하나요?
mode를 auto로 설정해 만드세요. 엔진이 각 단계를 스스로 승인하고 끝까지 실행합니다. 상태는 client.pipelines.get(id)를 폴링해 확인하고, 결과는 getTimeline(id)로 읽으세요. 실행은 계획한 매치 컷이 맞지 않을 때만 멈춥니다. 그러면 상태는 running으로 유지되고, 모든 불일치가 수락될 때까지 pendingApprovals(id)에 scene_images 단계가 나타납니다.
승인하기 전에 단계의 출력을 변경하려면 어떻게 하나요?
approveStage의 세 번째 인수로 JSON Patch를 전달하세요. 단계가 승인되기 전에 그 단계의 출력에 적용됩니다.
파이프라인에는 어떤 OAuth 스코프가 필요한가요?
파이프라인과 단계를 읽으려면 pipelines:read, 파이프라인을 만들고 취소하고 브랜치하려면 pipelines:execute, 단계를 승인하고 스크립트를 거부하고 단계에 대해 채팅하려면 pipelines:approve가 필요합니다.
관련 문서
파이프라인
영화 디렉터
작업과 실행
스튜디오 프로덕션
최종 업데이트