Qwen-Imagem-Em camadas: Um guia prático para decomposição de imagens

Os usuários do Photoshop passam horas mascarando objetos manualmente e pintando fundos. O Qwen-Image-Layered, um novo modelo da equipe Qwen da Alibaba, faz isso automaticamente: basta inserir uma única imagem e ele retorna várias camadas RGBA com fundos transparentes.

Este tutorial fala sobre o que é o Qwen-Image-Layered, como ele é diferente de ferramentas de segmentação como o SAM e como usá-lo no Python. Você vai dividir uma imagem em camadas, depois editar e juntar essas camadas de novo numa nova composição. No final, você vai ter um fluxo de trabalho funcional para edição programática de imagens que dispensa totalmente o uso de máscaras manuais.

Se você é novo no manuseio de dados de imagem e transparência em código, confira nosso Processamento de Imagens em Python para construir uma base sólida antes de mergulhar de cabeça.

O que é Qwen-Image-Layered?

O Qwen-Image-Layered é baseado no Qwen2.5-VL, um modelo de linguagem visual da Alibaba. A estrutura VL faz com que o modelo entenda o que está em uma imagem de forma semântica: ele consegue diferenciar um produto da sua sombra e da superfície em que está, não só detectar bordas. Como Vision Transformers, ele processa imagens por meio de mecanismos de atenção, em vez das abordagens convolucionais tradicionais.

Quando você faz uma inferência, você escolhe quantas camadas quer. Peça 4, e o modelo vai distribuir o conteúdo da imagem por 4 saídas RGBA. Peça 8 e você vai ter uma separação melhor. O modelo decide o que vai onde com base na estrutura da cena.

Exemplo visual

Aqui tá como a decomposição aparece no anúncio de Qwen:

O modelo pega uma imagem composta e separa em camadas RGBA editáveis individualmente com transparência.

A imagem promocional do doce se divide em quatro camadas distintas: o fundo com estrelas, a pessoa vestida de laranja, o texto e a marca “Sour Candy” e os doces individuais. Cada camada aparece com um fundo transparente (mostrado com o padrão xadrez), pronta para ser editada ou reorganizada.

O modelo distribui elementos visuais pelas camadas com base na profundidade e na compreensão semântica. Os gráficos de fundo vão para a camada 0, o tema principal (pessoa) vai para a camada 1, as sobreposições de texto vão para a camada 2 e os pequenos objetos em primeiro plano (pedaços de doces) vão para a camada 3. Cada elemento é separado de forma clara com a transparência adequada.

Qwen-Image-Layered vs Modelo Segment Anything

Se você já trabalhou com segmentação de imagens antes, pode estar se perguntando como o Qwen-Image-Layered se compara às ferramentas existentes, especialmente o Segment Anything Model (SAM).

SAM e modelos de segmentação parecidos geram máscaras: mapas binários que mostram quais pixels pertencem a qual objeto. É útil, mas uma máscara só mostra onde algo está. Extrair o objeto ainda deixa um buraco na imagem original.

Já o Qwen-Image-Layered gera camadas completas. O objeto em primeiro plano aparece com transparência, e a camada de fundo atrás dele já está preenchida. Quando você excluir ou mover uma camada mais tarde, não vai ter nada para corrigir.

O SAM usa uma abordagem discriminativa, analisando os pixels existentes para definir com precisão os limites dos objetos. Já o Qwen-Image-Layered usa uma arquitetura baseada em difusão generativa que reconstrói áreas ocultas ou escondidas por meio da geração de imagens aprendidas. 

Enquanto o SAM gera máscaras que definem o que deve ser removido, o Qwen-Image-Layered gera conteúdo de fundo plausível para completar a decomposição em camadas. É legal que o SAM consegue preencher o fundo de um jeito parecido quando junto com modelos de preenchimento dedicados, mas o Qwen-Image-Layered junta essa função do começo ao fim no seu processo de decomposição.

O mecanismo de controle de entrada também é diferente: O SAM usa instruções interativas precisas, pedindo pra você clicar em pontos ou desenhar caixas delimitadoras pra escolher um alvo específico. O Qwen-Image-Layered funciona de forma mais holística, permitindo que você simplesmente especifique o número desejado de camadas (por exemplo, “dividir isso em 4 camadas”) para organizar automaticamente toda a estrutura da imagem.

É importante notar que o SAM 2 foi feito especialmente para vídeo, capaz de rastrear objetos em sequências usando uma arquitetura de streaming com memória aumentada (mantém cerca de 6 quadros recentes) com alta consistência temporal. O Qwen-Image-Layered é especializado em composição de imagens estáticas dece, no momento, não oferece rastreamento nativo de objetos para edição de vídeo.

Decompondo uma imagem com o Qwen-Image-Layered

Agora vamos à parte prática. Antes de escrever qualquer código, tem uma questão prática: onde rodar o modelo.

Por que usar uma API?

O Qwen-Image-Layered precisa de mais de 57 GB de pesos de modelo e uma GPU top de linha com bastante VRAM. 

Testei rodar localmente no Google Colab com uma GPU T4, e a sessão ficou sem RAM antes que o modelo eterminasse de baixar. O uso do disco subiu para 90 GB dos 112 GB disponíveis no tempo de execução da GPU. O modelo é simplesmente grande demais para ambientes de nuvem gratuitos. 

Modelos generativos grandes como o Stable Diffusion enfrentam desafios de hospedagem parecidos, e é por isso que APIs hospedadas se tornaram comuns.

Neste tutorial, vamos usar a API hospedada do Replicate. Cada decomposição custa cerca de US$ 0,03, o que te dá uma execução estável e reproduzível sem se preocupar com limites de memória ou conflitos de dependência. Se você só quer experimentar o modelo sem escrever código, o Hugging Face Space tem uma interface web de graça onde você pode mandar imagens e baixar camadas manualmente.

O Hugging Face Space permite que você teste o modelo sem código, mas a API oferece controle programático.

Configurando o ambiente

Crie um novo diretório de projeto e instale os pacotes necessários:

pip install replicate python-dotenv

Pega o teu token API nas configurações da conta Replicate e guarda-o num arquivo .env:

REPLICATE_API_TOKEN=your_token_here

A imagem original

Os anúncios oficiais dos modelos geralmente mostram exemplos cuidadosamente selecionados em que o modelo tem o melhor desempenho. Vamos testar com uma imagem do mundo real pra ver o desempenho de verdade.

Essa é a imagem que vamos dividir em camadas:

Foto de Karola G no Pexels

A foto mostra três produtos para a pele em uma superfície menta contra um fundo lavanda: uma caixa de presente branca com fita preta, um frasco de sérum rosa e um pequeno pote de creme. Composição limpa, objetos distintos, sombras sutis. Um bom teste para a separação de camadas.

Executando inferência

import replicate
from dotenv import load_dotenv

load_dotenv()

with open("data/healthcare_products.jpg", "rb") as f:
	output = replicate.run(
         "qwen/qwen-image-layered",
     	    input={
         	"image": f,
         	"num_layers": 4,
         	"go_fast": True,
         	"output_format": "png",
         	"seed": 42,
     	    }
	)

O parâmetro “ num_layers ” controla o nível de detalhe com que o modelo divide a imagem. Os valores podem variar de 2 a 8. Com 4 camadas, você consegue um equilíbrio legal entre granularidade e facilidade de gerenciamento. Definir seed como um valor fixo torna a saída reproduzível.

A API também aceita URLs diretamente, então você pode pular o manuseio de arquivos se sua imagem estiver hospedada em algum lugar:

output = replicate.run(
	"qwen/qwen-image-layered",
	input={
     	  "image": "https://example.com/photo.jpg",
     	  "num_layers": 4,
     	  "go_fast": True,
     	  "output_format": "png",
	}
)

Salvar as camadas

A API retorna uma lista de objetos FileOutput. Cada um tem um método ` .read() ` que te dá os bytes da imagem:

for i, layer in enumerate(output):
	with open(f"layer_{i}.png", "wb") as f:
     	  f.write(layer.read())

As camadas são organizadas de baixo para cima: o índice 0 é o fundo, e os índices mais altos ficam em cima dele. Cada PNG é uma imagem RGBA com transparência, onde outras camadas ficam visíveis.

E aí está o resultado:

O modelo colocou o fundo (parede lavanda e superfície menta) na camada 0, o pote de creme na camada 1, a caixa de presente na camada 2 e o frasco de sérum na camada 3. Cada produto saiu com bordas limpas e transparência precisa.

Olha só a camada de fundo e você vai ver uns traços de sombra onde os produtos estavam antes. Isso apareceu sempre nos meus testes: o modelo lida bem com o isolamento de objetos, mas tem dificuldade com a reconstrução do fundo quando há sombras. 

Quanto mais visíveis forem as sombras na sua imagem original, mais visíveis esses artefatos vão ficar. É o primeiro modelo desse tipo, então a galera da Qwen deve dar um jeito nisso nas próximas atualizações.

Recombinando camadas com o Qwen-Image-Layered

A decomposição é só metade do fluxo de trabalho. As camadas ficam úteis quando você as edita e junta de novo pra criar algo novo.

Trocar o fundo

Os fotógrafos de produtos muitas vezes precisam da mesma foto com fundos diferentes para testes A/B, campanhas sazonais ou requisitos específicos de cada plataforma. Com camadas separadas, isso leva apenas algumas linhas de código.

from PIL import Image

# Load the decomposed layers
layers = [Image.open(f"layer_{i}.png") for i in range(4)]

# Create a new background (solid coral)
new_bg = Image.new("RGBA", layers[0].size, (255, 180, 162, 255))

# Replace the original background layer
layers[0] = new_bg

# Composite from bottom to top
result = layers[0]
for layer in layers[1:]:
	result = Image.alpha_composite(result, layer)

result.save("coral_background.png")

A função ` alpha_composite() ` cuida automaticamente da mistura RGBA. Ele respeita a transparência em cada camada, então os objetos em primeiro plano ficam naturalmente em cima de qualquer fundo que você escolher. 

O PIL facilita a manipulação de imagens e, se você precisar fazer transformações mais complexas, os recursos de processamento de imagens do PyTorch se integram bem aos fluxos de trabalho do PIL.

E aí está o resultado:

Os mesmos produtos, ambiente diferente, sem mascaramento manual. Você pode trocar por um gradiente, uma textura ou outra foto totalmente diferente. O processo continua o mesmo: troca a camada 0 e junta o resto.

Tirando ou mudando objetos de lugar

O mesmo padrão vale para outras edições. Remova um objeto pulando sua camada:

# Composite without the cream jar (layer 1)
layers_without_jar = [layers[0], layers[2], layers[3]]

result = layers_without_jar[0]
for layer in layers_without_jar[1:]:
	result = Image.alpha_composite(result, layer)

Para reposicionar um objeto colando-o em coordenadas diferentes, use o método paste() método com o deslocamento x/y que você escolher:

# Move the serum bottle 50 pixels left
 canvas = Image.new("RGBA", layers[0].size, (0, 0, 0, 0))
 canvas.paste(layers[3], (-50, 0), layers[3])
 layers[3] = canvas

 # Then composite as usual

O fluxo de trabalho é sempre o mesmo: 

1. Mude as camadas que você quiser: Mude o tamanho, troque a cor, apague, reorganize.
2. Depois, junta tudo de novo. 

Cada operação rola numa camada isolada, então as edições ficam contidas.

Criando um editor com camadas de imagens Qwen usando o Streamlit

Fazer essas operações em um caderno funciona para edições pontuais, mas o feedback é lento. Você escreve o código, executa uma célula, verifica o resultado, ajusta e repete. Para trabalhos repetitivos em que você quer ativar e desativar camadas, comparar composições e baixar resultados sem precisar refazer as células, uma interface gráfica leve faz mais sentido.

Vamos criar um aplicativo Streamlit com cerca de 160 linhas que permite carregar uma imagem, decompor, alternar camadas e ver uma pré-visualização ao vivo. Crie um arquivo chamado streamlit_app.py no diretório do seu projeto.

Configurando o Streamlit

Comece com as importações e a configuração básica:

import os
import io
import time
from typing import List
import streamlit as st
from PIL import Image, ImageDraw
from dotenv import load_dotenv
import replicate

load_dotenv()

# Constants
MAX_LAYERS, MIN_LAYERS, DEFAULT_LAYERS = 8, 2, 4
THUMBNAIL_SIZE = (150, 150)

# Initialize session state
if "layers" not in st.session_state:
	st.session_state.layers = []
	st.session_state.layer_visibility = []
	st.session_state.original_image = None

st.set_page_config(page_title="Qwen-Image-Layered", page_icon="🎨", layout="wide")
st.title("🎨 Qwen-Image-Layered")
st.markdown("Decompose images into editable RGBA layers")

O estado da sessão continua mesmo quando o Streamlit é executado de novo. Sem isso, suas camadas sumiriam toda vez que alguém clicasse em um botão.

Verificação do token da API

Antes de chamar o Replicate, certifique-se de que o token existe:

token = os.environ.get("REPLICATE_API_TOKEN")
if not token:
	st.error("REPLICATE_API_TOKEN not found. Set it in your .env file.")
	st.code("export REPLICATE_API_TOKEN=your_token_here", language="bash")
	st.stop()

st.stop() interrompe a execução se o token estiver faltando. Não faz sentido renderizar o resto da interface do usuário.

Função de decomposição de imagens em cache

A API de decomposição custa US$ 0,03 por chamada e leva de 30 a 60 segundos. O cache evita chamadas desnecessárias:

@st.cache_data(show_spinner=False)
def decompose_image(_image_bytes: bytes, num_layers: int, seed: int) -> List[bytes]:
    """Call Replicate API with retry logic for 502 errors."""
    for attempt in range(3):
        try:
            output = replicate.run(
                "qwen/qwen-image-layered",
                input={
                    "image": io.BytesIO(_image_bytes),
                    "num_layers": num_layers,
                    "go_fast": True,
                    "output_format": "png",
                    "seed": seed,
                },
            )
            return [layer.read() for layer in output]
        except Exception as e:
            if attempt < 2 and ("502" in str(e) or "Replicate" in str(type(e).__name__)):
                time.sleep(5)
                continue
            raise

O prefixo sublinhado em _image_bytes diz ao Streamlit para não fazer o hash desse parâmetro (os bytes são caros para fazer o hash). O loop de repetição lida com os erros 502 ocasionais do Replicate, esperando 5 segundos e tentando até 3 vezes.

Visualização e composição de imagens

Depois, vamos definir pequenos utilitários para visualização e composição:

def create_checkerboard(size: tuple) -> Image.Image:
    """Create a checkerboard pattern to show transparency."""
    img = Image.new("RGBA", size, (220, 220, 220, 255))
    draw = ImageDraw.Draw(img)

    square = 10
    for y in range(0, size[1], square):
        for x in range(0, size[0], square):
            if (x // square + y // square) % 2:
                draw.rectangle(
                    [x, y, x + square, y + square],
                    fill=(255, 255, 255, 255),
                )

    return img


def composite_layers(
    layers: List[Image.Image],
    visibility: List[bool],
) -> Image.Image:
    """Composite visible layers from bottom to top."""
    if not layers or not any(visibility):
        return Image.new(
            "RGBA",
            layers[0].size if layers else (400, 400),
            (0, 0, 0, 0),
        )

    result = None
    for layer, visible in zip(layers, visibility):
        if visible:
            result = layer.copy() if result is None else Image.alpha_composite(result, layer)

    return result or Image.new("RGBA", layers[0].size, (0, 0, 0, 0))

O tabuleiro de xadrez deixa a transparência visível (convenção padrão dos editores de imagem). A função composta reflete o que fizemos no caderno, agora controlada pelo estado da caixa de seleção.

Configurações de upload e decomposição de imagens

A barra lateral cuida das configurações de upload e decomposição de imagens:

with st.sidebar:
    st.header("🖼️ Image Upload")
    uploaded_file = st.file_uploader(
        "Choose an image",
        type=["png", "jpg", "jpeg"],
        help="Upload an image to decompose",
    )

    if uploaded_file is not None:
        st.session_state.original_image = uploaded_file
        st.image(uploaded_file, caption="Uploaded", use_container_width=True)

    st.divider()

    st.header("⚙️ Settings")
    num_layers = st.slider(
        "Number of layers",
        MIN_LAYERS,
        MAX_LAYERS,
        DEFAULT_LAYERS,
    )
    seed = st.number_input(
        "Random seed",
        0,
        999999,
        42,
        help="For reproducibility",
    )

    # Decompose button
    if st.button(
        "🔄 Decompose Image",
        disabled=uploaded_file is None,
        use_container_width=True,
        type="primary",
    ):
        if st.session_state.original_image is not None:
            image_bytes = st.session_state.original_image.getvalue()

            with st.spinner(f"Decomposing into {num_layers} layers... (30-60s)"):
                try:
                    layer_bytes = decompose_image(image_bytes, num_layers, seed)
                    st.session_state.layers = [
                        Image.open(io.BytesIO(lb)).convert("RGBA") for lb in layer_bytes
                    ]
                    st.session_state.layer_visibility = [True] * len(
                        st.session_state.layers
                    )
                    st.success(
                        f"Decomposed into {len(st.session_state.layers)} layers!"
                    )
                except Exception as e:
                    if "502" in str(e):
                        st.error(
                            "Replicate API error (502). Try again or use fewer layers."
                        )
                    else:
                        st.error(f"Error: {e}")

    # Reset button
    if st.session_state.layers and st.button("🗑️ Reset", use_container_width=True):
        st.session_state.layers = []
        st.session_state.layer_visibility = []
        st.session_state.original_image = None
        st.rerun()

O botão decompor fica desativado até que uma imagem seja carregada. Quando tudo dá certo, as camadas ficam guardadas no estado da sessão e todas as opções de visibilidade ficam em True por padrão.

Adicionando controles de camada de imagem

Duas colunas mostram os controles da camada e a pré-visualização ao vivo:

col1, col2 = st.columns([1, 1])  # two equal-width columns [web:61]

with col1:
    st.subheader("📑 Layers")

    if not st.session_state.layers:
        st.info("Upload an image and decompose to see layers here.")
    else:
        st.caption("Toggle layers on/off. Layer 0 is the background.")

        cols = st.columns(min(len(st.session_state.layers), 4))
        for i, layer in enumerate(st.session_state.layers):
            with cols[i % 4]:
                thumb = layer.copy()
                thumb.thumbnail(THUMBNAIL_SIZE)

                checkerboard = create_checkerboard(thumb.size)
                display = Image.alpha_composite(checkerboard, thumb)

                st.image(display, caption=f"Layer {i}", use_container_width=True)

                st.session_state.layer_visibility[i] = st.checkbox(
                    f"Show Layer {i}",
                    value=st.session_state.layer_visibility[i],
                    key=f"layer_{i}",
                )

with col2:
    st.subheader("👁️ Preview")

    if not st.session_state.layers:
        st.info("Composite preview will appear here.")
    else:
        composite = composite_layers(
            st.session_state.layers,
            st.session_state.layer_visibility,
        )
        visible = sum(st.session_state.layer_visibility)

        st.caption(f"Showing {visible} of {len(st.session_state.layers)} layers")
        st.image(composite, caption="Composite result", use_container_width=True)

        if visible > 0:
            buf = io.BytesIO()
            composite.save(buf, format="PNG")

            st.download_button(
                "⬇️ Download Result",
                data=buf.getvalue(),
                file_name="composite.png",
                mime="image/png",
                use_container_width=True,
            )

Quando você desmarca uma camada, o Streamlit executa o script de novo. A caixa de seleção atualiza layer_visibility, a função composta recalcula a visualização e a interface do usuário é atualizada automaticamente.

Executando o aplicativo

Salve o arquivo e execute:

streamlit run streamlit_app.py

O aplicativo tem uma imagem descomposto. Desative as camadas para tirar objetos da pré-visualização.

Carregue uma imagem, clique em decompor e, em seguida, ative e desative as camadas. A pré-visualização atualiza na hora. Baixe o resultado quando encontrar uma composição que você curtir. Todo o fluxo de trabalho rola no navegador, sem precisar executar novamente as células do caderno.

Conclusão

O Qwen-Image-Layered tem uma abordagem diferente para a edição de imagens: em vez de mascarar pixels, ele separa o conteúdo em camadas RGBA completas com fundos preenchidos. Você consegue isolar objetos sem precisar fazer a limpeza. O modelo tem dificuldade com artefatos de sombra em cenas complexas, mas a extração de objetos em si funciona bem.

O fluxo de trabalho do Python é bem simples. Chame a API do Replicate, pegue uma lista de camadas e junte tudo com o PIL. A troca de planos de fundo e a remoção de objetos agora são só algumas linhas de código. O aplicativo Streamlit coloca essa lógica numa interface gráfica pra iteração mais rápida.

Esse é o primeiro modelo desse tipo. A equipe da Qwen lança atualizações rapidinho, então espere melhorias na reconstrução do fundo e um melhor tratamento de imagens com muitas sombras. O artigo de pesquisa fala sobre a arquitetura, caso você queira entender como a decomposição da camada variável funciona nos bastidores.

Pronto para conhecer mais modelos de IA de código aberto? Domine o ecossistema por trás do Qwen fazendo o Hugging Face Fundamentals no programa de DataCamp.