# Z-Image

  

[Z-Image](https://huggingface.co/papers/2511.22699) — мощная и высокоэффективная модель генерации изображений с 6 млрд параметров. На данный момент доступна только одна модель, две другие будут выпущены позже:

|Модель|Hugging Face|
|---|---|
|Z-Image-Turbo|https://huggingface.co/Tongyi-MAI/Z-Image-Turbo|

## Z-Image-Turbo

Z-Image-Turbo — это дистиллированная версия Z-Image, которая при всего 8 NFE (Number of Function Evaluations) соответствует или превосходит ведущих конкурентов. Она обеспечивает задержку вывода менее секунды на корпоративных GPU H800 и комфортно помещается в 16 ГБ видеопамяти потребительских устройств. Модель демонстрирует превосходные результаты в генерации фотореалистичных изображений, двуязычном рендеринге текста (английский и китайский) и точном следовании инструкциям.

## Изображение в изображение

Используйте [ZImageImg2ImgPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/z_image#diffusers.ZImageImg2ImgPipeline) для преобразования существующего изображения на основе текстового запроса.

```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")
```

## Инпейнтинг

Используйте [ZImageInpaintPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/z_image#diffusers.ZImageInpaintPipeline) для восстановления конкретных областей изображения на основе текстового запроса и маски.

```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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[str] = ['latents'], max_sequence_length: int = 512)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image.py#L297)

**Параметры:**

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него.

height (`int`, *необязательный*, по умолчанию 1024) : Высота генерируемого изображения в пикселях.

width (`int`, *необязательный*, по умолчанию 1024) : Ширина генерируемого изображения в пикселях.

num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

sigmas (`list[float]`, *optional*) : Пользовательские сигмы для процесса денойзинга в планировщиках, поддерживающих аргумент `sigmas` в методе `set_timesteps`. Если не задано, будет использовано поведение по умолчанию при передаче `num_inference_steps`.

guidance_scale (`float`, *optional*, по умолчанию 5.0) : Масштаб руководства, определённый в [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

cfg_normalization (`bool`, *необязательный*, по умолчанию False) : Нужно ли применять нормализацию конфигурации.

cfg_truncation (`float`, *необязательный*, по умолчанию 1.0) : Значение усечения для конфигурации.

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющее влияние (то есть игнорируется, если `guidance_scale` меньше `1`).

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`list[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`list[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные эмбеддинги отрицательного текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерируемого изображения. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~pipelines.stable_diffusion.ZImagePipelineOutput` вместо обычного кортежа.

joint_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`List`, *необязательный*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса конвейера.

max_sequence_length (`int`, *необязательный*, по умолчанию 512) : Максимальная длина последовательности, используемая с `prompt`.

**Возвращает:** `ZImagePipelineOutput` или `tuple`

`ZImagePipelineOutput`, если `return_dict` равно True, иначе `tuple`. При возврате кортежа первым элементом является список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L154)

**Параметры:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик, используемый в связке с `transformer` для удаления шума из закодированных латентов изображения.

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder (`PreTrainedModel`) : модель текстового кодировщика для кодирования текстовых промптов.

tokenizer (`AutoTokenizer`) : токенизатор для токенизации текстовых промптов.

transformer ([ZImageTransformer2DModel](/docs/diffusers/v0.43.0/ru/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : трансформерная модель ZImage для удаления шума из закодированных латентов изображения.

Пайплайн ZImage для генерации изображений по изображению.

#### __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[str] = ['latents'], max_sequence_length: int = 512)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py#L369)

**Параметры:**

prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]` или `list[np.ndarray]`) : `Image`, массив numpy или тензор, представляющие пакет изображений, который будет использоваться в качестве начальной точки. Для массивов numpy и тензоров pytorch ожидаемый диапазон значений составляет `[0, 1]`. Если это тензор или список тензоров, ожидаемая форма должна быть `(B, C, H, W)` или `(C, H, W)`. Если это массив numpy или список массивов, ожидаемая форма должна быть `(B, H, W, C)` или `(H, W, C)`.

strength (`float`, *optional*, по умолчанию 0.6) : Определяет степень трансформации исходного `image`. Значение должно быть в диапазоне от 0 до 1. `image` используется как отправная точка, и чем выше `strength`, тем больше шума добавляется. Количество шагов денойзинга зависит от количества шума, добавленного изначально. Когда `strength` равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в `num_inference_steps`. Значение 1 фактически игнорирует `image`.

height (`int`, *optional*, по умолчанию 1024) : Высота генерируемого изображения в пикселях. Если не указано, используется высота входного изображения.

width (`int`, *optional*, по умолчанию 1024) : Ширина генерируемого изображения в пикселях. Если не указано, используется ширина входного изображения.

num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

sigmas (`list[float]`, *optional*) : Пользовательские сигмы для процесса денойзинга в планировщиках, поддерживающих аргумент `sigmas` в методе `set_timesteps`. Если не задано, будет использовано поведение по умолчанию при передаче `num_inference_steps`.

guidance_scale (`float`, *optional*, по умолчанию 5.0) : Масштаб руководства, определённый в [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

cfg_normalization (`bool`, *необязательный*, по умолчанию False) : Нужно ли применять нормализацию конфигурации.

cfg_truncation (`float`, *необязательный*, по умолчанию 1.0) : Значение усечения для конфигурации.

negative_prompt (`str` или `list[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющее влияние (то есть игнорируется, если `guidance_scale` меньше `1`).

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

generator (`torch.Generator` или `list[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`list[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`list[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные эмбеддинги отрицательного текста. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерируемого изображения. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~pipelines.stable_diffusion.ZImagePipelineOutput` вместо обычного кортежа.

joint_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`List`, *необязательный*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса конвейера.

max_sequence_length (`int`, *необязательный*, по умолчанию 512) : Максимальная длина последовательности, используемая с `prompt`.

**Возвращает:** `ZImagePipelineOutput` или `tuple`

`ZImagePipelineOutput`, если `return_dict` равно True, иначе `tuple`. При возврате кортежа первым элементом является список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для генерации изображений по изображению.

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L170)

**Параметры:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : планировщик, используемый в связке с `transformer` для удаления шума из закодированных латентов изображения.

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/ru/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.

text_encoder (`PreTrainedModel`) : модель текстового кодировщика для кодирования текстовых промптов.

tokenizer (`AutoTokenizer`) : токенизатор для токенизации текстовых промптов.

transformer ([ZImageTransformer2DModel](/docs/diffusers/v0.43.0/ru/api/models/z_image_transformer2d#diffusers.ZImageTransformer2DModel)) : трансформерная модель ZImage для удаления шума из закодированных латентов изображения.

Пайплайн ZImage для инпейнтинга.

#### __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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L535)

**Параметры:**

prompt (`str` или `List[str]`, *необязательный*) : Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передать `prompt_embeds` вместо него.

image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `List[torch.Tensor]`, `List[PIL.Image.Image]` или `List[np.ndarray]`) : `Image`, массив numpy или тензор, представляющие пакет изображений, который будет использоваться в качестве начальной точки. Для массивов numpy и тензоров pytorch ожидаемый диапазон значений составляет `[0, 1]`. Если это тензор или список тензоров, ожидаемая форма должна быть `(B, C, H, W)` или `(C, H, W)`. Если это массив numpy или список массивов, ожидаемая форма должна быть `(B, H, W, C)` или `(H, W, C)`.

mask_image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `List[torch.Tensor]`, `List[PIL.Image.Image]` или `List[np.ndarray]`) : `Image`, массив numpy или тензор, представляющий маску для инпейнтинга. Белые пиксели (значение 1) в маске будут инпейнтингованы, черные пиксели (значение 0) сохранятся из исходного изображения.

masked_image_latents (`torch.FloatTensor`, *необязательный*) : Предварительно закодированные латенты замаскированного изображения. Если указаны, шаг кодирования замаскированного изображения будет пропущен.

strength (`float`, *optional*, по умолчанию 1.0) : Определяет степень трансформации исходного изображения `image`. Значение должно находиться в диапазоне от 0 до 1. Изображение `image` используется как отправная точка, и чем выше значение `strength`, тем больше шума добавляется. Количество шагов денойзинга зависит от количества шума, добавленного на начальном этапе. Если `strength` равно 1, добавляется максимальное количество шума, и процесс денойзинга выполняется в течение полного числа итераций, указанного в `num_inference_steps`. Значение 1 фактически игнорирует `image` в замаскированной области.

height (`int`, *optional*, по умолчанию 1024) : Высота генерируемого изображения в пикселях. Если не указано, используется высота входного изображения.

width (`int`, *optional*, по умолчанию 1024) : Ширина генерируемого изображения в пикселях. Если не указано, используется ширина входного изображения.

num_inference_steps (`int`, *optional*, по умолчанию 50) : Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода.

sigmas (`List[float]`, *необязательный*) : Пользовательские сигмы для процесса денуазинга в планировщиках, поддерживающих аргумент `sigmas` в методе `set_timesteps`. Если не задано, будет использоваться поведение по умолчанию при передаче `num_inference_steps`.

guidance_scale (`float`, *optional*, по умолчанию 5.0) : Масштаб руководства, определённый в [Classifier-Free Diffusion Guidance](https://arxiv.org/abs/2207.12598). `guidance_scale` определяется как `w` из уравнения 2 в [Imagen Paper](https://arxiv.org/pdf/2205.11487.pdf). Масштаб руководства активируется при установке `guidance_scale > 1`. Более высокий масштаб руководства способствует генерации изображений, тесно связанных с текстовым `prompt`, обычно за счёт снижения качества изображения.

cfg_normalization (`bool`, *необязательный*, по умолчанию False) : Нужно ли применять нормализацию конфигурации.

cfg_truncation (`float`, *необязательный*, по умолчанию 1.0) : Значение усечения для конфигурации.

negative_prompt (`str` или `List[str]`, *необязательный*) : Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передать `negative_prompt_embeds`. Игнорируется, если не используется направляющее влияние (то есть игнорируется, если `guidance_scale` меньше `1`).

num_images_per_prompt (`int`, *необязательный*, по умолчанию 1) : Количество изображений, генерируемых на один запрос.

generator (`torch.Generator` или `List[torch.Generator]`, *необязательный*) : Один или список [генераторов torch](https://pytorch.org/docs/stable/generated/torch.Generator.html) для обеспечения детерминированности генерации.

latents (`torch.FloatTensor`, *необязательный*) : Предварительно сгенерированные шумовые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации изображений. Позволяет корректировать одну и ту же генерацию с помощью разных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайного `generator`.

prompt_embeds (`List[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, текстовые эмбеддинги будут сгенерированы из входного аргумента `prompt`.

negative_prompt_embeds (`List[torch.FloatTensor]`, *необязательный*) : Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, *например* для взвешивания промпта. Если не предоставлены, negative_prompt_embeds будут сгенерированы из входного аргумента `negative_prompt`.

output_type (`str`, *необязательный*, по умолчанию `"pil"`) : Формат вывода для генерируемого изображения. Выберите между [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` или `np.array`.

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~pipelines.stable_diffusion.ZImagePipelineOutput` вместо обычного кортежа.

joint_attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который при указании передается в `AttentionProcessor`, определенный в `self.processor` в [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: `callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)`. `callback_kwargs` будет содержать список всех тензоров, как указано в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`List`, *необязательный*) : Список тензорных входных данных для функции `callback_on_step_end`. Тензоры, указанные в списке, будут переданы в качестве аргумента `callback_kwargs`. Вы сможете включать только переменные, перечисленные в атрибуте `._callback_tensor_inputs` вашего класса конвейера.

max_sequence_length (`int`, *необязательный*, по умолчанию 512) : Максимальная длина последовательности, используемая с `prompt`.

**Возвращает:** `ZImagePipelineOutput` или `tuple`

`ZImagePipelineOutput`, если `return_dict` равно True, иначе `tuple`. При возврате кортежа первым элементом является список с сгенерированными изображениями.

Функция, вызываемая при обращении к конвейеру для инпейнтинга.

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L386)

**Возвращает:** `Tuple of (latents, noise, image_latents) where`

- latents: Зашумлённые латенты изображения для денойзинга
- noise: тензор шума, используемый для смешивания
- image_latents: Чистые латенты изображения для смешивания

Подготовьте латенты для инпейнтинга, вернув шум и image_latents для смешивания.

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/z_image/pipeline_z_image_inpaint.py#L318)

**Параметры:**

mask : тензор двоковой маски, где 1 = область для инпейнта, 0 = область для сохранения.

masked_image : Исходное изображение с обнулёнными замаскированными областями.

batch_size : Количество изображений для генерации.

height : Высота выходного изображения.

width : Ширина выходного изображения.

dtype : Тип данных для тензоров.

device : Устройство, на котором размещаются тензоры.

generator : Генератор случайных чисел для воспроизводимости.

**Возвращает:**

Кортеж (mask, masked_image_latents), подготовленный для цикла денойзинга.

Подготовьте маску и латенты замаскированного изображения для инпейнтинга.