# Dividir em camadas

> Divida uma imagem em uma imagem base e camadas separadas, cada elemento em um PNG transparente, com nome, caixa de posição e ordem de empilhamento.

Source: https://nodaro.ai/pt-BR/docs/nodes/image/split-into-layers

O nó **Dividir em camadas** separa uma imagem em uma imagem base e camadas separadas. Cada elemento, como uma pessoa, um animal, um produto, uma linha de texto ou um logo, volta como um PNG transparente próprio. O nó também retorna os dados das camadas, que dizem o que é cada camada, onde ela fica e como as camadas se empilham.

Edite, anime ou substitua as camadas uma a uma e depois junte-as de novo. Deixe **O que separar** vazio, e o nó encontra os elementos principais sozinho, ou descreva os elementos que você quer.

- Found in: Image › Edit & Retouch
- API type: `split-into-layers`

## Quando usar
- Edite um elemento de uma imagem, como um produto ou um título, sem mexer no resto.
- Anime cada elemento separadamente: conecte as camadas ao [**Gerar vídeo**](https://nodaro.ai/docs/nodes/video/generate-video).
- Aumente a resolução de cada elemento separadamente com o [**Upscale de imagem**](https://nodaro.ai/docs/nodes/image/upscale-image).
- Recomponha uma imagem: mova, redimensione ou troque elementos e depois coloque-os de volta sobre a imagem base.
- Obtenha cada elemento como um PNG transparente, pronto para uma ferramenta de design.

## Início rápido
### Adicionar o nó
Pressione Tab no canvas e escolha **Imagem › Edição e retoque › Dividir em camadas**.

### Conectar a imagem
Conecte um nó de imagem, como o [**Enviar imagem**](https://nodaro.ai/docs/nodes/image/upload-image) ou o [**Gerar imagem**](https://nodaro.ai/docs/nodes/image/generate-image), à entrada **Imagem**. Você também pode enviar uma imagem no próprio nó.

### Escolher as configurações
Abra o painel de configurações. Defina **Máximo de camadas** e **Tamanho**. Para escolher os elementos você mesmo, descreva-os em **O que separar**.

### Executar
Clique em **Executar** no nó. Uma execução costuma levar menos de um minuto. O nó mostra a imagem base e uma faixa com as camadas, cada uma com o nome dela.

Workflow: Um pôster é dividido em camadas, e uma conexão Cada item aumenta a resolução de cada camada separadamente.

- Enviar imagem → Dividir em camadas (imagem)
- Dividir em camadas → Upscale de imagem (camadas)

## Entradas
| Entrada | Aceita | O que faz |
| --- | --- | --- |
| **Imagem** | Nós de imagem, como Enviar imagem, Gerar imagem e Modificar imagem, ou um Personagem, um Objeto ou um Local | A imagem a dividir: JPEG, PNG ou WebP. Um arquivo maior, ou outro formato, como HEIC ou AVIF, é convertido antes. Um Personagem, um Objeto ou um Local conectado é usado como a imagem. Obrigatória. |

## Saídas
| Saída | O que leva |
| --- | --- |
| **Base** | A imagem base, um PNG opaco. |
| **Camadas** | Uma lista com todas as camadas, de baixo para cima: PNGs transparentes, cada um recortado no próprio elemento. |
| **Dados das camadas** | Uma entrada por camada, na mesma ordem de **Camadas**. |

**Camadas** é uma lista. Uma conexão a partir dela no modo **Cada item**, o padrão, executa o próximo nó uma vez por camada. Por exemplo, conecte-a ao Upscale de imagem para aumentar a resolução de cada camada, ou ao Gerar vídeo para animar cada uma. Defina a conexão como **Conjunto** para entregar todas as camadas de uma vez a um nó que recebe várias imagens, como o nó [**Colagem de imagens**](https://nodaro.ai/docs/nodes/image/image-collage) ou as referências do Gerar imagem. Veja [Listas e lotes](https://nodaro.ai/docs/concepts/lists-and-batching).

A imagem base e todas as camadas também são guardadas na sua Biblioteca. Cada camada é guardada com o nome dela.

### Dados das camadas
A saída **Dados das camadas** fica assim:

```json
[
{
"name": "Arctic fox",
"description": "The full body of the standing white arctic fox, with no background.",
"zIndex": 1,
"width": 1108,
"height": 946,
"box": { "x1": 228, "y1": 482, "x2": 897, "y2": 1070 },
"boxNormalized": { "x1": 223, "y1": 314, "x2": 875, "y2": 696 },
"url": "https://…/layer.png",
"baseUrl": "https://…/base.png"
}
]
```

| Campo | O que significa |
| --- | --- |
| `zIndex` | A ordem de empilhamento. `1` fica sobre a imagem base, e um número maior é desenhado acima dele. |
| `box` | Onde a camada fica na imagem base, em pixels da imagem base. `x1` e `y1` são o canto superior esquerdo, e `x2` e `y2`, o canto inferior direito. |
| `boxNormalized` | A mesma caixa, em uma escala de 0 a 1000 da largura e da altura da imagem base. |
| `width`, `height` | Os pixels do próprio arquivo da camada. Uma camada não é recortada na escala da imagem base. Ela é recortada no próprio elemento e salva com mais ou menos o orçamento de pixels da configuração **Tamanho** (cerca de um megapixel em 1K), no formato do próprio elemento. Para colocar uma camada de volta no lugar, ajuste a escala dela à `box`. |
| `name`, `description` | O que é o elemento. Uma camada pode vir sem eles. |
| `url` | O arquivo da camada, o mesmo da entrada dela em **Camadas**. |
| `baseUrl` | A imagem base da qual a camada foi recortada, a mesma de **Base**. |

### Várias imagens em uma execução
Conecte uma lista de imagens a **Imagem**, como uma [**Lista**](https://nodaro.ai/docs/nodes/automate/list) de links de imagens ou um nó que gera várias imagens em uma conexão **Cada item**. O nó é então executado uma vez por imagem. O resultado de cada execução é uma versão própria, com a imagem base, as camadas e os dados das camadas daquela imagem.

- **Base** lista uma imagem base para cada imagem que produziu um resultado, na ordem em que as imagens chegaram. Uma imagem cuja execução falhou não tem imagem base, então fica fora da lista.
- **Camadas** passa adiante as camadas de cada imagem, uma imagem depois da outra. Uma conexão **Cada item** executa o próximo nó uma vez por camada de cada imagem: as camadas da primeira imagem, depois as da segunda, e assim por diante. Uma conexão **Conjunto** entrega todas de uma vez, uma conexão **Selecionado** lê a primeira, e uma conexão **Item** escolhe uma da lista inteira.
- **Dados das camadas** se alinha com essas camadas, uma a uma. Cada entrada também traz `row`, o número da imagem de entrada da qual ela veio, contando a partir de 0. Uma imagem sem camadas não acrescenta nada a **Camadas** nem a **Dados das camadas**, e o mesmo vale para uma imagem cuja execução falhou. Cada imagem mantém o próprio número, então `row` pode pular um número.

Para associar uma camada à imagem base dela, use o `baseUrl`, não o `row`. **Base** lista só as imagens que produziram um resultado. Depois que uma imagem falha, o `row` de uma imagem posterior deixa de corresponder à posição dela em **Base**. No exemplo abaixo, a segunda imagem falhou. A imagem base da coruja é o segundo item de **Base**, enquanto o `row` dela é 2.

```json
[
{ "name": "Fox", "zIndex": 1, "url": "https://…/fox.png", "baseUrl": "https://…/base-1.png", "row": 0 },
{ "name": "Owl", "zIndex": 1, "url": "https://…/owl.png", "baseUrl": "https://…/base-3.png", "row": 2 }
]
```

Uma execução com uma única imagem gera dados das camadas sem `row`, como no primeiro exemplo. O nó mostra as camadas da versão que você está vendo. Escolha outra versão para ver as camadas daquela imagem. As conexões a partir de **Camadas** e de **Dados das camadas** continuam passando adiante as camadas de todas as imagens, qualquer que seja a versão escolhida. Da mesma forma, uma conexão **Cada item** a partir de **Base** continua listando a imagem base de cada imagem. Antes da primeira execução, a estimativa da execução conta uma conexão **Cada item** a partir de **Camadas** pelo valor de **Máximo de camadas** para cada imagem.

## Configurações
| Configuração | O que faz |
| --- | --- |
| **Máximo de camadas** | O máximo de camadas que uma execução gera, de 1 a 99. O padrão é 9. A imagem base vem além delas. Uma imagem com mais elementos do que isso recebe menos camadas, e maiores, porque os elementos são agrupados, nunca descartados. |
| **Tamanho** | O orçamento de pixels de cada imagem: `1K`, o padrão, `1.5K` ou `2K`. **Automático** usa o tamanho da própria imagem, entre 1K e 2K. |
| **O que separar** | Opcional, até 2.000 caracteres. Descreva em palavras simples quais elementos separar. Deixe vazio, e o nó encontra os elementos principais sozinho. |

Em **O que separar**, você pode marcar onde fica um elemento com `<bbox>x1 y1 x2 y2</bbox>`. Os números são os cantos, em uma escala de 0 a 1000 da imagem. Por exemplo:

```text
Separate the title <bbox>179 58 809 197</bbox> and the parrot <bbox>330 274 641 991</bbox>
```

### Em um app publicado
Um [app](https://nodaro.ai/docs/concepts/apps) criado a partir de um workflow com este nó pode deixar os usuários dele definirem **Máximo de camadas**, com um controle deslizante de 1 a 20, e **Tamanho**, entre **Automático**, `1K`, `1.5K` ou `2K`. O controle deslizante do app e qualquer substituição em uma execução de workflow ficam limitados a esses valores. Qualquer outro valor é recusado antes de a execução começar.

Um app envia só os valores que o usuário dele mudou. Uma execução que não mexe em **Máximo de camadas** mantém o valor que o criador salvou no nó, até 99 camadas, e reserva créditos para esse valor. Por exemplo, 50 camadas salvas no nó reservam créditos para 51 imagens. Com o controle deslizante no máximo, 20 camadas em `2K` reservam 369 créditos.

## Créditos
Uma execução **reserva** créditos para o máximo de imagens que pode retornar: o **Máximo de camadas** dela mais a imagem base. Ela é **cobrada** só pelas imagens que realmente retorna: a imagem base e cada camada. Os tamanhos `1K` e `1.5K` custam o mesmo, e `2K` e **Automático** custam mais. O botão **Executar** mostra a reserva para as configurações que você escolheu.

| Exemplo | Reservado | Cobrado |
| --- | --- | --- |
| O padrão: 9 camadas em 1K | 104 | — |
| 3 camadas retornadas em 1K (4 imagens) | | 44 |
| 3 camadas retornadas em 2K ou **Automático** (4 imagens) | | 74 |
| **Máximo de camadas** em 5, em 1K | 64 | — |
| Nenhum elemento encontrado: só a imagem base, em 1K | | 15 |

- **Nenhum elemento encontrado.** A execução termina só com a imagem base e é cobrada por essa única imagem.
- **Uma camada que não pode ser salva.** Se uma camada ainda não puder ser salva depois de algumas tentativas, a execução termina sem ela e é cobrada só pelas imagens que salvou. O nó informa quantas camadas não puderam ser salvas, por exemplo “2 de 9 camadas não puderam ser salvas”.
- **Uma execução que falha é reembolsada.** Isso inclui uma execução cuja imagem base não pode ser salva.

As edições auto-hospedadas Community Edition e Business edition não usam créditos.

## Dicas
- **Recomponha em ordem.** Para reconstruir uma imagem, coloque cada camada sobre a imagem base, na `box` dela, na ordem de `zIndex`.
- **Escolha quanto agrupar.** Um **Máximo de camadas** menor agrupa elementos, como um título inteiro em uma camada. Um valor maior os mantém separados.
- **Nomeie os elementos de que você precisa.** Quando os elementos principais não forem os que você quer, descreva-os em **O que separar**, por exemplo “o logo e a etiqueta de preço”.

## Solução de problemas
| Problema | O que fazer |
| --- | --- |
| A execução retornou só a imagem base | O nó não encontrou nenhum elemento. Descreva os elementos que você quer em **O que separar**, ou marque-os com um `<bbox>`. |
| Dois elementos saíram em uma camada | A imagem tem mais elementos que o **Máximo de camadas**. Aumente o **Máximo de camadas**. |
| Uma camada não se alinha com a imagem base | O arquivo de uma camada não está na escala da imagem base. Ajuste a escala dele à `box` indicada nos dados das camadas antes de posicioná-lo. |
| O nó diz que algumas camadas não puderam ser salvas | A execução terminou sem essas camadas e cobrou só pelas imagens que salvou. Execute o nó de novo para obtê-las. |

## Pela API
O `POST /v1/split-into-layers` com `{ imageUrl, maxLayers?, size?, prompt?, sessionId?, origin? }` coloca uma tarefa na fila e responde com o `jobId` dela. Uma requisição malformada responde `400 validation_error` antes de qualquer crédito ser reservado. O `sessionId` arquiva a tarefa em uma das suas sessões, e o `origin` a marca com o slug do seu app. Um cabeçalho `Idempotency-Key` faz uma nova tentativa responder com a tarefa que a primeira requisição iniciou (`{ jobId, deduped: true }`), em vez de iniciar uma segunda.

O `output_data.imageUrl` da tarefa concluída é a imagem base, e `output_data.layers` lista os arquivos das camadas em ordem. O `output_data.layerData` são os dados das camadas descritos acima. O `output_data.layerCount` é o número de camadas salvas, e o `output_data.layersNotSaved`, o número das que não puderam ser salvas (`0` quando todas as camadas foram salvas).

Para saber a reserva antes de uma execução, envie `{ "type": "split-into-layers", "params": { … } }` para `POST /v1/quote`, com o mesmo corpo. Nada é iniciado. O `identifier` da resposta é o preço reservado (`split-into-layers:<1k|2k>:<images>`), e `reserve` são os créditos reservados: 64 com **Máximo de camadas** em 5, em 1K, e 104 com o padrão. No SDK, chame `client.nodes.quote("split-into-layers", body)`. Quando você não pode executar o nó, a cotação é recusada como a execução, com `403 node_not_available`.

O método do SDK é `client.media.splitIntoLayers`, a ferramenta MCP é `split_into_layers`, e o comando da CLI é `nodaro media split-layers`. Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes), [Tarefas](https://nodaro.ai/docs/developers/api/jobs), [Mídia e uploads no SDK](https://nodaro.ai/docs/developers/sdk/media-and-uploads) e as [ferramentas MCP](https://nodaro.ai/docs/mcp/tools).

## Perguntas frequentes

### O que o Dividir em camadas retorna?

Uma imagem base, que é a cena atrás dos elementos, e uma camada PNG transparente para cada elemento, como uma pessoa, um produto, uma linha de texto ou um logo. Ele também retorna os dados das camadas, com o nome, a caixa de posição e a ordem de empilhamento de cada camada.

### Preciso escrever um prompt?

Não. Deixe O que separar vazio, e o nó encontra os elementos principais sozinho. Descreva os elementos que você quer só quando os principais não forem os de que você precisa.

### Quantas camadas uma execução pode gerar?

Até o valor de Máximo de camadas, de 1 a 99, com 9 como padrão. Uma imagem com mais elementos recebe menos camadas, e maiores, porque os elementos são agrupados, nunca descartados.

### Quanto custa o Dividir em camadas?

Uma execução reserva créditos para o Máximo de camadas dela mais a imagem base, e é cobrada só pelas imagens que retorna. O padrão, 9 camadas em 1K, reserva 104 créditos. Por uma execução que retorna 3 camadas em 1K, são cobrados 44 créditos.

### Como junto as camadas de novo?

Coloque cada camada sobre a imagem base, na caixa dela, na ordem de empilhamento, do menor zIndex ao maior. O arquivo de uma camada é recortado no próprio elemento, então ajuste a escala dele à caixa antes.