#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença. -->

# PRX Pixel

PRXPixel é um modelo de geração de texto para imagem no espaço de pixels da Photoroom. Um `PRXTransformer2DModel` de ~7B remove o ruído de imagens RGB brutas diretamente — não é necessário um VAE. O modelo é condicionado por um codificador de texto Qwen3-VL e usa flow matching, no qual o transformer prevê a imagem limpa em cada etapa (x-prediction). A resolução de geração é inserida na modulação do timestep, para que o modelo esteja ciente do tamanho alvo.

## Modelos disponíveis

| Model | Resolução | Descrição | Parâmetros sugeridos | dtype recomendado |
|:-----:|:---------:|:----------:|:----------:|:----------:|
| [`Photoroom/prxpixel-t2i`](https://huggingface.co/Photoroom/prxpixel-t2i) | 1024 | Modelo de espaço de pixels ~7B com codificador de texto Qwen3-VL | 28 etapas, cfg=5.0 | `torch.bfloat16` |

## Carregando o pipeline

[PRXPixelPipeline](/docs/diffusers/main/pt/api/pipelines/prx_pixel#diffusers.PRXPixelPipeline) requer `transformers >= 4.57` (a versão que introduziu `Qwen3VLTextModel`). Carregue-o com [from_pretrained()](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained):

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
image.save("prxpixel_output.png")
```

## Otimização de Memória

Para ambientes com restrições de memória:

```py
import torch
from diffusers import PRXPixelPipeline

pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

# Or use sequential CPU offload for even lower memory
pipe.enable_sequential_cpu_offload()
```

## PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

#### diffusers.PRXPixelPipeline[[diffusers.PRXPixelPipeline]]

```python
diffusers.PRXPixelPipeline(transformer: PRXTransformer2DModel, scheduler: FlowMatchEulerDiscreteScheduler, text_encoder: PreTrainedModel, tokenizer: transformers.models.auto.tokenization_auto.AutoTokenizer | transformers.tokenization_utils_base.PreTrainedTokenizerBase, default_sample_size: int | None = 1024, prompt_max_tokens: int = 256, noise_scale: float = 2.0)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L98)

**Parâmetros:**

transformer (`PRXTransformer2DModel`) : O denoiser PRX com ~7B parâmetros. Para o PRXPixel, ele é construído com `in_channels=3`, um gargalo `img_in` e `resolution_embeds=True`, e é treinado para prever a imagem limpa `x0`.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Agendador de correspondência de fluxo (flow-matching) usado para desruidar os latentes (no espaço de pixels).

text_encoder (`PreTrainedModel`) : O backbone de texto do Qwen3-VL usado para codificar prompts (a torre de visão é descartada). Deve retornar um `last_hidden_state`.

tokenizer (`PreTrainedTokenizerBase`) : Tokenizador para `text_encoder` (geralmente carregado via `AutoTokenizer`).

default_sample_size (`int`, *opcional*, padrão 1024) : Altura/largura padrão usada quando nenhuma é fornecida para `__call__`.

prompt_max_tokens (`int`, *opcional*, padrão 256) : Número de tokens de texto para os quais o prompt é preenchido/truncado antes da codificação.

noise_scale (`float`, *opcional*, padrão 2.0) : Escala aplicada ao ruído gaussiano inicial. O PRXPixel é treinado com uma escala de ruído inicial não unitária, portanto a amostragem deve começar em `randn * noise_scale`.

Pipeline para geração de texto para imagem com o modelo PRXPixel.

PRXPixel é um pipeline independente de texto para imagem no espaço de pixels. Ele remove o ruído do RGB bruto diretamente com um `PRXTransformer2DModel` de ~7B parâmetros e não possui VAE (a geração ocorre inteiramente no espaço de pixels, portanto a saída desruidizada *é* a imagem). Os prompts são codificados com um codificador de texto Qwen3-VL (a torre de visão é descartada). Diferentemente do [PRXPipeline](/docs/diffusers/main/pt/api/pipelines/prx#diffusers.PRXPipeline), o transformer é treinado com x-prediction: em cada etapa, ele prevê a imagem limpa `x0`, que é convertida em uma velocidade de flow-matching antes da etapa do agendador. A amostragem começa em `randn * noise_scale` (`noise_scale=2.0` por padrão) e a resolução padrão é de 1024px.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

Exemplos:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### __call__[[diffusers.PRXPixelPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str = '', height: int | None = None, width: int | None = None, num_inference_steps: int = 28, timesteps: list[int] = None, guidance_scale: float = 4.0, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, output_type: str | None = 'pil', return_dict: bool = True, use_resolution_binning: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L406)

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração da imagem. Se não definido, é necessário passar `prompt_embeds` em vez disso.

negative_prompt (`str`, *opcional*, padrão `""`) : O prompt ou os prompts que não devem orientar a geração da imagem. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

height (`int`, *opcional*, padrão `default_sample_size`) : A altura em pixels da imagem gerada.

width (`int`, *opcional*, padrão `default_sample_size`) : A largura em pixels da imagem gerada.

num_inference_steps (`int`, *opcional*, padrão 28) : O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, às custas de uma inferência mais lenta.

timesteps (`list[int]`, *opcional*) : Passos de tempo personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumento `timesteps` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado. Deve estar em ordem decrescente.

guidance_scale (`float`, *opcional*, padrão 4.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://huggingface.co/papers/2205.11487). A escala de orientação é ativada ao definir `guidance_scale > 1`. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas ao `prompt` de texto, geralmente em detrimento de uma menor qualidade de imagem.

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um ou uma lista de [geradores do torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.FloatTensor`, *opcional*) : Emojis de texto pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido, os emojis de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.FloatTensor`, *opcional*) : Embeddings de texto negativos pré-gerados. Pode ser usado para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não for fornecido e `guidance_scale > 1`, os embeddings negativos serão gerados a partir de uma string vazia.

prompt_attention_mask (`torch.BoolTensor`, *opcional*) : Máscara de atenção pré-gerada para `prompt_embeds`. Se não for fornecida, a máscara de atenção será gerada a partir do argumento de entrada `prompt`.

negative_prompt_attention_mask (`torch.BoolTensor`, *opcional*) : Máscara de atenção pré-gerada para `negative_prompt_embeds`. Se não for fornecida e `guidance_scale > 1`, a máscara de atenção será gerada a partir de uma string vazia.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` ou `np.array`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [PRXPipelineOutput](/docs/diffusers/main/pt/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) em vez de uma tupla simples.

use_resolution_binning (`bool`, *opcional*, padrão `True`) : Se definido como `True`, a altura e a largura solicitadas são primeiro mapeadas para as resoluções mais próximas usando bins de proporção de aspecto predefinidos. Após os latentes produzidos serem decodificados em imagens, eles são redimensionados de volta para a resolução solicitada. Útil para gerar imagens não quadradas em resoluções ótimas.

callback_on_step_end (`Callable`, *opcional*) : Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos: `callback_on_step_end(self, step, timestep, callback_kwargs)`. `callback_kwargs` incluirá uma lista de todos os tensores, conforme especificado por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, *opcional*) : A lista de entradas de tensor para a função `callback_on_step_end`. Os tensores especificados na lista serão passados como argumento `callback_kwargs`. Você só poderá incluir tensores que estão listados no atributo `._callback_tensor_inputs`.

**Retorna:** [PRXPipelineOutput](/docs/diffusers/main/pt/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) ou `tuple`

[PRXPipelineOutput](/docs/diffusers/main/pt/api/pipelines/prx#diffusers.pipelines.prx.PRXPipelineOutput) se `return_dict` for True, caso contrário, uma `tuple. Ao retornar uma tupla, o primeiro elemento é uma lista com as imagens geradas.

Função invocada ao chamar o pipeline para geração.

Exemplos:
```py
>>> import torch
>>> from diffusers import PRXPixelPipeline

>>> pipe = PRXPixelPipeline.from_pretrained("Photoroom/prxpixel-t2i", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A front-facing portrait of a lion in the golden savanna at sunset."
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=5.0).images[0]
>>> image.save("prxpixel_output.png")
```

#### check_inputs[[diffusers.PRXPixelPipeline.check_inputs]]

```python
check_inputs(prompt: str | list[str], height: int, width: int, guidance_scale: float, callback_on_step_end_tensor_inputs: list[str] | None = None, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L324)

Verifique se todas as entradas estão no formato correto.

#### encode_prompt[[diffusers.PRXPixelPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], device: typing.Optional[torch.device] = None, do_classifier_free_guidance: bool = True, negative_prompt: str = '', num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.FloatTensor] = None, negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None, prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, negative_prompt_attention_mask: typing.Optional[torch.BoolTensor] = None, tokenizer_max_length: int | None = None, skip_text_cleaning: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L263)

Codifique o prompt de texto usando um codificador e um tokenizador de texto padrão, ou use embeddings pré-computados.

#### prepare_latents[[diffusers.PRXPixelPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, dtype: dtype, device: device, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_prx_pixel.py#L378)

Prepare os latentes iniciais para o processo de difusão.

PRXPixel treina com uma escala de ruído inicial não unitária, portanto o ruído amostrado é multiplicado por `self.config.noise_scale`.

## PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

#### diffusers.pipelines.prx.PRXPipelineOutput[[diffusers.pipelines.prx.PRXPipelineOutput]]

```python
diffusers.pipelines.prx.PRXPipelineOutput(images: list[PIL.Image.Image] | numpy.ndarray)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/prx/pipeline_output.py#L24)

**Parâmetros:**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : lista de imagens PIL desruidas de comprimento `batch_size` ou array numpy de forma `(batch_size, height, width, num_channels)`. As imagens PIL ou o array numpy apresentam as imagens desruidas do pipeline de difusão.

Classe de saída para pipelines PRX.