Pipelines

client.pipelines executa pipelines de história para vídeo: produções em várias etapas que transformam um prompt de história em um filme. Um pipeline passa por oito etapas, script, characters, objects, locations, shot_list, scene_images, animate_audio_edit e post_merge, e pode parar em cada uma delas para a sua aprovação. É a versão programática do Criar filme no estúdio. Os métodos chamam a API REST de pipelines.

Modos

O status de um pipeline é queued, running, awaiting_approval, completed, failed, cancelled ou forked.

Métodos

Os escopos valem para tokens OAuth. Tokens de API e sessões não são limitados por escopos.

client.pipelines

create(input)

Inicia um pipeline. No modo auto, ele vai até o fim sozinho, a menos que uma quebra de match cut o pare; consulte get() periodicamente para ver o status e getTimeline() para ver o resultado. No modo manual ou guided, conduza o pipeline com pendingApprovals(), approveStage() e 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)

Lê o estado atual de um pipeline. Consulte-o periodicamente para acompanhar uma execução auto até o fim. Uma execução parada em uma quebra de match cut continua running, então verifique também 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)

Um PipelineRecord tem id, status, current_stage, mode, spent_credits, reserved_credits, upfront_credit_estimate, failure_reason (definido quando o status é failed), current_progress_message e, em uma derivação, branched_from_pipeline_id e branched_from_stage.

list()

Lista os seus pipelines, dos mais recentes para os mais antigos.

list(): Promise<PipelineRecord[]>

const pipelines = await client.pipelines.list()

cancel(id)

Para um pipeline em execução. Os créditos reservados e não gastos são reembolsados. Cancelar um pipeline que já terminou não muda nada.

cancel(id: string): Promise<{ ok: true }>

await client.pipelines.cancel(id)

pendingApprovals(id)

Lista as etapas que aguardam aprovação, cada uma com a sua saída. A lista fica vazia durante uma execução auto, porque o mecanismo aprova as etapas sozinho, a menos que uma quebra de match cut o pare.

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?)

Aprova uma etapa para que o pipeline siga em frente. Passe edits, um JSON Patch, para alterar a saída da etapa antes de ela ser aprovada.

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)

Rejeita o roteiro com uma observação, e o mecanismo o escreve de novo levando a observação em conta. Só a etapa script pode ser rejeitada; outra etapa falha com stage_not_implemented. Você pode rejeitar o roteiro no máximo duas vezes, e menos vezes se o revisor automático de roteiros já o tiver revisado.

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)

Aprova uma verificação dentro da etapa animate_audio_edit, como dialogue_recheck, para que o pipeline continue com o próximo passo.

A etapa scene_images tem o próprio ponto de controle, match_cut_break_pending, que approveSubGate não libera. Em vez disso, aceite cada quebra pela API REST. Veja Quebras de match cut na etapa de imagens das cenas.

approveSubGate(id: string, gate: SubGateName): Promise<{ ok: true; gate: SubGateName; resumed_at: string }>

await client.pipelines.approveSubGate(id, "dialogue_recheck")

getStage(id, stage)

Lê o status, a output e o critic_feedback de uma etapa. Use-o para examinar o roteiro ou o plano antes de aprová-lo.

getStage(id: string, stage: PipelineStageName): Promise<{ status: string; output: unknown; critic_feedback: unknown }>

const { status, output } = await client.pipelines.getStage(id, "script")

getTimeline(id)

Lê o filme montado: as cenas em ordem com as durações delas, as URLs de áudio e o progresso da animação. Renderize-o você mesmo ou entregue-o a um editor.

getTimeline(id: string): Promise<PipelineTimeline>

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

Um PipelineTimeline tem fps, width, height, scenes (cada uma { compositeUrl, durationSeconds }), musicUrl, narrationUrl e animateProgress com totalShots, shotsDone e percent.

branch(id, input)

Executa de novo um pipeline concluído a partir de uma etapa, como um novo pipeline. As etapas anteriores a ela são copiadas como aprovadas. O pipeline original continua 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)

Envia uma mensagem ao diretor no modo guided. O modo do pipeline precisa ser guided, e a etapa precisa estar em awaiting_approval. A resposta pode trazer uma proposed_change que você pode aceitar com applyChatProposal(). A conversa funciona nas etapas que a aceitam, como 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)

Aceita a alteração que o diretor propôs em uma rodada anterior. A alteração é verificada e salva como uma nova versão da etapa, e a etapa é aprovada.

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)

Quando a alteração não pode ser aplicada, mas é possível se recuperar, o resultado é applied: false, e o diretor já adicionou uma resposta com uma dica. Uma falha definitiva lança um erro 409.

getStageChat(pipelineId, stage)

Lê o histórico da conversa de uma etapa. Ele fica vazio antes da primeira mensagem.

getStageChat(pipelineId: string, stage: ChatEnabledStage): Promise<{ turns: ChatTurn[] }>

const { turns } = await client.pipelines.getStageChat(id, "script")

Cada ChatTurn tem id, turn_n, role, content, proposed_change, applied_to_attempt_id e created_at.