# Z-Image

  

[Z-Image](https://huggingface.co/papers/2511.22699) é um modelo de geração de imagens poderoso e altamente eficiente, com 6B de parâmetros. Atualmente, há apenas um modelo disponível, com mais dois a serem lançados:

|Model|Hugging Face|
|---|---|
|Z-Image-Turbo|https://huggingface.co/Tongyi-MAI/Z-Image-Turbo|

## Z-Image-Turbo

Z-Image-Turbo é uma versão destilada do Z-Image que iguala ou supera os principais concorrentes com apenas 8 NFEs (Number of Function Evaluations). Oferece latência de inferência inferior a um segundo em GPUs H800 de nível empresarial e cabe confortavelmente em dispositivos de consumo com 16G de VRAM. Destaca-se na geração de imagens fotorrealistas, na renderização de texto bilíngue (inglês & chinês) e na robusta aderência a instruções.

## Imagem para imagem

Use [ZImageImg2ImgPipeline](/docs/diffusers/main/pt/api/pipelines/z_image#diffusers.ZImageImg2ImgPipeline) para transformar uma imagem existente com base em um prompt de texto.

```python
import torch
from diffusers import ZImageImg2ImgPipeline
from diffusers.utils import load_image

pipe = ZImageImg2ImgPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
image = pipe(
    prompt,
    image=init_image,
    strength=0.6,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_img2img.png")
```

## Inpainting

Use [ZImageInpaintPipeline](/docs/diffusers/main/pt/api/pipelines/z_image#diffusers.ZImageInpaintPipeline) para preencher regiões específicas de uma imagem com base em um prompt de texto e uma máscara.

```python
import torch
import numpy as np
from PIL import Image
from diffusers import ZImageInpaintPipeline
from diffusers.utils import load_image

pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

# Create a mask (white = inpaint, black = preserve)
mask = np.zeros((1024, 1024), dtype=np.uint8)
mask[256:768, 256:768] = 255  # Inpaint center region
mask_image = Image.fromarray(mask)

prompt = "A beautiful lake with mountains in the background"
image = pipe(
    prompt,
    image=init_image,
    mask_image=mask_image,
    strength=1.0,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_inpaint.png")
```

## ZImagePipeline[[diffusers.ZImagePipeline]]

#### diffusers.ZImagePipeline[[diffusers.ZImagePipeline]]

```python
diffusers.ZImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image.py#L141)

#### __call__[[diffusers.ZImagePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 512)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image.py#L297)

**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.

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

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

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

sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado.

guidance_scale (`float`, *opcional*, padrão 5.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). 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.

cfg_normalization (`bool`, *opcional*, padrão é False) : Se deve aplicar a normalização de configuração.

cfg_truncation (`float`, *opcional*, padrão 1.0) : O valor de truncamento para a configuração.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

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.FloatTensor`, *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 (`list[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 (`list[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, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

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 `~pipelines.stable_diffusion.ZImagePipelineOutput` em vez de uma tupla simples.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `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 variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int`, *opcional*, padrão 512) : Comprimento máximo da sequência a ser usado com o `prompt`.

**Retorna:** `ZImagePipelineOutput` ou `tuple`

`ZImagePipelineOutput` 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 ZImagePipeline

>>> pipe = ZImagePipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> # Optionally, set the attention backend to flash-attn 2 or 3, default is SDPA in PyTorch.
>>> # (1) Use flash attention 2
>>> # pipe.transformer.set_attention_backend("flash")
>>> # (2) Use flash attention 3
>>> # pipe.transformer.set_attention_backend("_flash_3")

>>> prompt = "一幅为名为“造相「Z-IMAGE-TURBO」”的项目设计的创意海报。画面巧妙地将文字概念视觉化：一辆复古蒸汽小火车化身为巨大的拉链头，正拉开厚厚的冬日积雪，展露出一个生机盎然的春天。"
>>> image = pipe(
...     prompt,
...     height=1024,
...     width=1024,
...     num_inference_steps=8,
...     guidance_scale=0.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage.png")
```

## ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

#### diffusers.ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

```python
diffusers.ZImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L154)

**Parâmetros:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`PreTrainedModel`) : Um modelo de codificador de texto para codificar prompts de texto.

tokenizer (`AutoTokenizer`) : Um tokenizador para tokenizar prompts de texto.

transformer ([ZImageTransformer2DModel](/docs/diffusers/main/pt/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : Um modelo transformer ZImage para desruidar os latentes de imagem codificados.

O pipeline ZImage para geração de imagem a partir de imagem.

#### __call__[[diffusers.ZImageImg2ImgPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.6, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 512)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L369)

**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.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` ou `list[np.ndarray]`) : `Image`, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Tanto para arrays numpy quanto para tensors do PyTorch, o intervalo de valores esperado é entre `[0, 1]`. Se for um tensor ou uma lista de tensors, a forma esperada deve ser `(B, C, H, W)` ou `(C, H, W)`. Se for um array numpy ou uma lista de arrays, a forma esperada deve ser `(B, H, W, C)` ou `(H, W, C)`.

strength (`float`, *opcional*, padrão 0.6) : Indica o grau de transformação da `image` de referência. Deve estar entre 0 e 1. `image` é usado como ponto de partida e mais ruído é adicionado quanto maior for o `strength`. O número de etapas de desruidamento depende da quantidade de ruído inicialmente adicionada. Quando `strength` é 1, o ruído adicionado é máximo e o processo de desruidamento executa pelo número total de iterações especificado em `num_inference_steps`. Um valor de 1 essencialmente ignora `image`.

height (`int`, *opcional*, padrão 1024) : A altura em pixels da imagem gerada. Se não for fornecida, usa a altura da imagem de entrada.

width (`int`, *opcional*, padrão 1024) : A largura em pixels da imagem gerada. Se não for fornecida, usa a largura da imagem de entrada.

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

sigmas (`list[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado.

guidance_scale (`float`, *opcional*, padrão 5.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). 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.

cfg_normalization (`bool`, *opcional*, padrão é False) : Se deve aplicar a normalização de configuração.

cfg_truncation (`float`, *opcional*, padrão 1.0) : O valor de truncamento para a configuração.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

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.FloatTensor`, *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 (`list[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 (`list[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, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

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 `~pipelines.stable_diffusion.ZImagePipelineOutput` em vez de uma tupla simples.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `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 variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int`, *opcional*, padrão 512) : Comprimento máximo da sequência a ser usado com o `prompt`.

**Retorna:** `ZImagePipelineOutput` ou `tuple`

`ZImagePipelineOutput` 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 de imagem para imagem.

Exemplos:
```py
>>> import torch
>>> from diffusers import ZImageImg2ImgPipeline
>>> from diffusers.utils import load_image

>>> pipe = ZImageImg2ImgPipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
>>> init_image = load_image(url).resize((1024, 1024))

>>> prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
>>> image = pipe(
...     prompt,
...     image=init_image,
...     strength=0.6,
...     num_inference_steps=8,
...     guidance_scale=0.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage_img2img.png")
```

## ZImageInpaintPipeline[[diffusers.ZImageInpaintPipeline]]

#### diffusers.ZImageInpaintPipeline[[diffusers.ZImageInpaintPipeline]]

```python
diffusers.ZImageInpaintPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L170)

**Parâmetros:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Um scheduler a ser usado em combinação com `transformer` para desruidar os latentes da imagem codificada.

vae ([AutoencoderKL](/docs/diffusers/main/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes.

text_encoder (`PreTrainedModel`) : Um modelo de codificador de texto para codificar prompts de texto.

tokenizer (`AutoTokenizer`) : Um tokenizador para tokenizar prompts de texto.

transformer ([ZImageTransformer2DModel](/docs/diffusers/main/pt/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : Um modelo transformer ZImage para desruidar os latentes de imagem codificados.

O pipeline ZImage para inpainting.

#### __call__[[diffusers.ZImageInpaintPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str]] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, mask_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, masked_image_latents: typing.Optional[torch.FloatTensor] = None, strength: float = 1.0, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_images_per_prompt: typing.Optional[int] = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = None, negative_prompt_embeds: typing.Optional[typing.List[torch.FloatTensor]] = None, output_type: str = 'pil', return_dict: bool = True, joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], max_sequence_length: int = 512)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L535)

**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.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `List[torch.Tensor]`, `List[PIL.Image.Image]` ou `List[np.ndarray]`) : `Image`, array numpy ou tensor representando um lote de imagens a ser usado como ponto de partida. Tanto para arrays numpy quanto para tensors do PyTorch, o intervalo de valores esperado é entre `[0, 1]`. Se for um tensor ou uma lista de tensors, a forma esperada deve ser `(B, C, H, W)` ou `(C, H, W)`. Se for um array numpy ou uma lista de arrays, a forma esperada deve ser `(B, H, W, C)` ou `(H, W, C)`.

mask_image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `List[torch.Tensor]`, `List[PIL.Image.Image]` ou `List[np.ndarray]`) : `Image`, array numpy ou tensor representando uma imagem de máscara para inpainting. Os pixels brancos (valor 1) na máscara serão inpaintados, enquanto os pixels pretos (valor 0) serão preservados da imagem original.

masked_image_latents (`torch.FloatTensor`, *opcional*) : Latentes de imagem mascarada pré-codificados. Se fornecidos, a etapa de codificação da imagem mascarada será ignorada.

strength (`float`, *opcional*, padrão 1.0) : Indica a extensão da transformação da `image` de referência. Deve estar entre 0 e 1. `image` é usado como ponto de partida e mais ruído é adicionado quanto maior for o `strength`. O número de etapas de desruidamento depende da quantidade de ruído inicialmente adicionada. Quando `strength` é 1, o ruído adicionado é máximo e o processo de desruidamento executa pelo número total de iterações especificado em `num_inference_steps`. Um valor de 1 essencialmente ignora `image` na região mascarada.

height (`int`, *opcional*, padrão 1024) : A altura em pixels da imagem gerada. Se não for fornecida, usa a altura da imagem de entrada.

width (`int`, *opcional*, padrão 1024) : A largura em pixels da imagem gerada. Se não for fornecida, usa a largura da imagem de entrada.

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

sigmas (`List[float]`, *opcional*) : Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumento `sigmas` em seu método `set_timesteps`. Se não definido, o comportamento padrão quando `num_inference_steps` é passado será usado.

guidance_scale (`float`, *opcional*, padrão 5.0) : Escala de orientação definida em [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` é definido como `w` da equação 2. do [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). 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.

cfg_normalization (`bool`, *opcional*, padrão é False) : Se deve aplicar a normalização de configuração.

cfg_truncation (`float`, *opcional*, padrão 1.0) : O valor de truncamento para a configuração.

negative_prompt (`str` ou `List[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

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.FloatTensor`, *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 (`List[torch.FloatTensor]`, *opcional*) : Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`List[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, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

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 `~pipelines.stable_diffusion.ZImagePipelineOutput` em vez de uma tupla simples.

joint_attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

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: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `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 variáveis listadas no atributo `._callback_tensor_inputs` da sua classe de pipeline.

max_sequence_length (`int`, *opcional*, padrão 512) : Comprimento máximo da sequência a ser usado com o `prompt`.

**Retorna:** `ZImagePipelineOutput` ou `tuple`

`ZImagePipelineOutput` 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 inpainting.

Exemplos:
```py
>>> import torch
>>> from diffusers import ZImageInpaintPipeline
>>> from diffusers.utils import load_image

>>> pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
>>> init_image = load_image(url).resize((1024, 1024))

>>> # Create a mask (white = inpaint, black = preserve)
>>> import numpy as np
>>> from PIL import Image

>>> mask = np.zeros((1024, 1024), dtype=np.uint8)
>>> mask[256:768, 256:768] = 255  # Inpaint center region
>>> mask_image = Image.fromarray(mask)

>>> prompt = "A beautiful lake with mountains in the background"
>>> image = pipe(
...     prompt,
...     image=init_image,
...     mask_image=mask_image,
...     strength=1.0,
...     num_inference_steps=8,
...     guidance_scale=0.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage_inpaint.png")
```

#### prepare_latents[[diffusers.ZImageInpaintPipeline.prepare_latents]]

```python
prepare_latents(image, timestep, batch_size, num_channels_latents, height, width, dtype, device, generator, latents = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L386)

**Retorna:** `Tuple of (latents, noise, image_latents) where`

- latents: Latentes de imagem com ruído para desruído
- noise: O tensor de ruído usado para a mistura
- image_latents: Latentes de imagem limpos para mesclagem

Prepara os latentes para inpainting, retornando o ruído e os image_latents para a mistura.

#### prepare_mask_latents[[diffusers.ZImageInpaintPipeline.prepare_mask_latents]]

```python
prepare_mask_latents(mask, masked_image, batch_size, height, width, dtype, device, generator)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L318)

**Parâmetros:**

mask : Tensor de máscara binária onde 1 = região de inpainting, 0 = região a ser preservada.

masked_image : Imagem original com as regiões mascaradas zeradas.

batch_size : Número de imagens a serem geradas.

height : Altura da imagem de saída.

width : Largura da imagem de saída.

dtype : Tipo de dados dos tensores.

device : Dispositivo em que os tensores serão colocados.

generator : Gerador aleatório para reprodutibilidade.

**Retorna:**

Tupla de (mask, masked_image_latents) preparada para o loop de desruidamento.

Prepare os latentes da máscara e da imagem mascarada para inpainting.