# Pipelines

> Inicie um pipeline História → vídeo com um prompt, acompanhe as etapas, aprove-as ou refine-as no chat e derive um pipeline pronto em qualquer etapa.

Source: https://nodaro.ai/pt-BR/docs/mcp/tools/pipelines

As **ferramentas de pipeline** controlam o pipeline **História → vídeo** (Story to Video) a partir de um assistente de IA. Um único prompt inicia um pipeline que escreve um roteiro, cria o elenco e os lugares, planeja e renderiza as tomadas e junta um filme pronto. O assistente pode acompanhar as etapas, aprová-las, refiná-las num chat e derivar um pipeline concluído a partir de qualquer etapa. A versão desse mesmo mecanismo no canvas é o nó [História → vídeo](https://nodaro.ai/docs/nodes/video/story-to-video).

As ferramentas de pipeline só existem no Nodaro Cloud. Elas só aparecem se você tiver concedido as permissões `pipelines:read`, `pipelines:execute` e `pipelines:approve`.

## As etapas
Um pipeline executa estas etapas em ordem: `script`, `characters`, `objects`, `locations`, `shot_list`, `scene_images`, `animate_audio_edit` e `post_merge`. No modo `auto`, ele executa todas sozinho e só para quando um match cut planejado entre duas tomadas se quebra. A execução então aguarda até que cada quebra seja aceita pela [API REST](https://nodaro.ai/docs/developers/api/pipelines#match-cut-breaks-in-the-scene-images-stage). Nenhuma ferramenta MCP aceita uma quebra. Nos modos `manual` e `guided`, ele para em pontos de aprovação, e a etapa aguarda com o status `awaiting_approval`.

## `start_pipeline`
Inicia um novo pipeline História → vídeo a partir de um prompt de história.

**Permissão:** `pipelines:execute`. **Créditos:** os créditos de cada geração que o pipeline executa. `get_pipeline_status` mostra os créditos à medida que ele avança.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `story_prompt` | string | **Obrigatório.** Sobre o que é o filme, com até 4.000 caracteres. |
| `format` | string | `trailer`, `short_film`, `music_video`, `reel` ou `commercial`. Padrão: `reel`. |
| `target_duration_seconds` | integer | A duração do filme, de 5 a 600 segundos. Padrão: `15`. |
| `mode` | string | `auto` (padrão) vai até o fim sem supervisão, exceto numa quebra de match cut. `manual` e `guided` param em pontos de aprovação. |
| `output_resolution` | string | `480p`, `720p`, `1080p` ou `4K`. Padrão: `720p`. |
| `music_enabled` | boolean | Adiciona música. Padrão: `true`. |
| `narration_enabled` | boolean | Adiciona narração. Padrão: `false`. |
| `lipsync_enabled` | boolean | Sincroniza os lábios dos personagens com as falas deles. Padrão: `false`. |

**Retorna:** o ID do novo pipeline. Consulte `get_pipeline_status` periodicamente e, enquanto uma etapa aguarda, `pipeline_pending_approvals`.

A narração e a sincronização labial vêm desativadas por padrão quando um assistente inicia um pipeline, para que uma execução sem supervisão não gaste créditos com elas, a menos que você as peça.

## `get_pipeline_status`
Retorna o estado de um pipeline: o status (`pending`, `running`, `awaiting_approval`, `completed` ou `failed`), a etapa atual, os contadores de créditos, o modo e `failure_reason`, quando ele falhou.

**Permissão:** `pipelines:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** O ID do pipeline. |

## `pipeline_pending_approvals`
Lista as etapas que aguardam aprovação, cada uma com um instantâneo da saída dela. Uma lista vazia significa que nada está aguardando: a execução está no modo `auto` sem quebra de match cut, ou ainda está gerando.

**Permissão:** `pipelines:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** O ID do pipeline. |

## `chat_pipeline_stage`
Envia uma mensagem ao diretor de refinamento sobre uma etapa que aguarda aprovação, por exemplo “deixe o final mais sombrio”. O pipeline precisa estar no modo `guided`.

**Permissão:** `pipelines:approve`.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** O ID do pipeline. |
| `stage` | string | **Obrigatório.** A etapa que aguarda: `script` ou `post_merge`. |
| `message` | string | **Obrigatório.** A sua mensagem, com até 8.000 caracteres. |

**Retorna:** a resposta do diretor e, quando ele propõe uma edição, um `proposed_change`. Aplique a alteração com `apply_chat_proposal`.

## `apply_chat_proposal`
Aceita a alteração proposta numa resposta do diretor e aprova a etapa com essa alteração.

**Permissão:** `pipelines:approve`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** O ID do pipeline. |
| `stage` | string | **Obrigatório.** A etapa do chat. |
| `turn_id` | string | **Obrigatório.** O ID da resposta do diretor cuja alteração você aceita. |

## `get_pipeline_stage_chat`
Lista as mensagens do chat de uma etapa, das mais antigas para as mais recentes. A lista fica vazia quando ninguém escreveu ainda.

**Permissão:** `pipelines:read`. **Créditos:** grátis.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** O ID do pipeline. |
| `stage` | string | **Obrigatório.** A etapa do chat. |

## `branch_pipeline`
Cria um novo pipeline que executa de novo um pipeline concluído a partir de uma etapa. As etapas anteriores, com os personagens, objetos e locais delas, são copiadas como aprovadas. A etapa escolhida e todas as seguintes são executadas de novo.

**Permissão:** `pipelines:execute`. **Créditos:** os créditos das etapas executadas de novo.

| Parâmetro | Tipo | Observações |
| --- | --- | --- |
| `pipeline_id` | string | **Obrigatório.** Um pipeline com o status `completed`. |
| `from_stage` | string | **Obrigatório.** `script`, `characters`, `objects`, `locations`, `shot_list`, `scene_images`, `animate_audio_edit` ou `post_merge`. |

**Retorna:** o ID do novo pipeline.

## Frequently asked questions

### O que um pipeline História → vídeo produz?

Um filme pronto a partir de um único prompt de história. O pipeline escreve o roteiro, cria os personagens, objetos e locais, planeja as tomadas, gera as imagens das cenas, anima-as com áudio e junta a montagem final.

### Qual é a diferença entre os modos auto, manual e guided?

O modo auto vai do prompt ao filme pronto sozinho. Ele só para quando um match cut planejado entre duas tomadas se quebra, até que cada quebra seja aceita pela API REST. Nenhuma ferramenta MCP aceita uma quebra. Os modos manual e guided param em pontos de aprovação. O guided também permite refinar o roteiro e a montagem final num chat antes de aprovar.

### Posso executar um pipeline de novo a partir do meio?

Sim, depois que ele for concluído. branch_pipeline copia como aprovadas as etapas anteriores à que você escolher e executa de novo essa etapa e todas as seguintes, como um novo pipeline.

### Por que as ferramentas de pipeline não aparecem no meu assistente?

Elas precisam das permissões de pipelines e só existem no Nodaro Cloud. Conecte-se de novo e conceda as permissões de pipeline na tela de consentimento.