Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /pt /api /pipelines /ideogram4.md

mishig

3 days ago

preview code

download

raw

14.9 kB

# Ideogram 4

O Ideogram 4 é um modelo de texto para imagem baseado em flow-matching que utiliza um codificador de texto multimodal e um esquema de orientação livre de classificador assimétrico: um `unconditional_transformer` dedicado produz o ramo negativo com recursos de texto zerados, enquanto o `transformer` principal consome a sequência completa empacotada de texto + imagem.

Os padrões do pipeline são as configurações recomendadas para a melhor qualidade, portanto, uma chamada simples de `pipe(prompt)` produz resultados de melhor qualidade imediatamente: 48 etapas de flow-matching em um agendamento logit-normal (`mu=0.0`, `std=1.5`) com classifier-free guidance mantido em 7.0 para as etapas principais e reduzido para 3.0 nas 3 etapas finais de "acabamento".

Os principais parâmetros de inferência são expostos por meio da chamada do pipeline:

- `num_inference_steps`, `mu` e `std` controlam o agendamento de flow-matching logit-normal sensível à resolução.
- `guidance_scale` (ou um `guidance_schedule` completo por etapa) combina as velocidades condicionais e incondicionais.

## Texto para imagem

```python
import torch
from diffusers import Ideogram4Pipeline
pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"
prompt = "A photo of a cat holding a sign that says hello world"
# The defaults are the recommended settings for best quality.
image = pipe(prompt, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
image.save("ideogram4.png")
```

## Ampliação de prompt

O Ideogram 4 é treinado com base em uma legenda JSON estruturada, em vez de um prompt em formato livre, portanto, um prompt curto é melhor expandido para esse esquema nativo antes da geração. Existem duas maneiras de produzir a legenda.

### Remote (Ideogram API)

Para obter os melhores resultados, expanda o prompt com a API magic-prompt hospedada pela Ideogram e passe a legenda retornada diretamente para o pipeline (obtenha uma chave em [developer.ideogram.ai](https://developer.ideogram.ai/)):

```python
import json
import requests
import torch
from diffusers import Ideogram4Pipeline
pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-4-nf4", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"
# Expand the prompt into a structured JSON caption with Ideogram's hosted magic-prompt API.
response = requests.post(
    "https://api.ideogram.ai/v1/ideogram-v4/magic-prompt",
    headers={"Api-Key": "your_ideogram_api_key"},
    json={"text_prompt": "A photo of a cat holding a sign that says hello world", "aspect_ratio": "1x1"},
).json()
caption = json.dumps(response["json_prompt"])
# The caption is already upsampled, so pass it directly (no prompt_upsampling).
image = pipe(caption, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
image.save("ideogram4_upsampled.png")
```

### Local (em dispositivo)

Para um pipeline totalmente local, carregue um [Ideogram4PromptEnhancerHead](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) pequeno (o head do LM Qwen3-VL) como o componente opcional `prompt_enhancer_head` e passe `prompt_upsampling=True`. O head é acoplado ao `text_encoder` compartilhado, portanto, nenhum segundo codificador de texto é carregado. Instale `outlines` para legendas com esquema restrito (o checkpoint nf4 também requer `bitsandbytes`):

```python
import torch
from diffusers import Ideogram4Pipeline, Ideogram4PromptEnhancerHead
prompt_enhancer_head = Ideogram4PromptEnhancerHead.from_pretrained(
    "diffusers/qwen3-vl-8b-instruct-lm-head", dtype=torch.bfloat16
)
pipe = Ideogram4Pipeline.from_pretrained(
    "ideogram-ai/ideogram-4-nf4", prompt_enhancer_head=prompt_enhancer_head, dtype=torch.bfloat16
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"
prompt = "A photo of a cat holding a sign that says hello world"
image = pipe(
    prompt,
    height=1024,
    width=1024,
    prompt_upsampling=True,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("ideogram4_upsampled.png")
```

## Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

#### diffusers.Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

```python
diffusers.Ideogram4Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: Ideogram4Transformer2DModel, unconditional_transformer: Ideogram4Transformer2DModel, prompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None)
```

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

**Parâmetros:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Agendador de fluxo correspondente (flow-matching). O pipeline substitui o agendamento de sigma padrão por um agendamento logit-normal sensível à resolução.

vae (`AutoencoderKLFlux2`) : Autoencoder variacional usado para decodificar latentes de volta em imagens.

text_encoder (`PreTrainedModel`) : Codificador de texto multimodal. O pipeline consome estados ocultos de um conjunto fixo de camadas intermediárias do decodificador (veja `QWEN3_VL_ACTIVATION_LAYERS`).

tokenizer (`AutoTokenizer`) : Tokenizer associado ao `text_encoder`.

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/pt/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de fluxo condicional.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/pt/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de flow-matching incondicional (asymmetric-CFG).
Pipeline de texto para imagem para Ideogram4.
Ideogram4 é um modelo de flow-matching treinado com orientação livre de classificador assimétrica: um `transformer` consome recursos condicionados por texto junto com os latentes da imagem, enquanto um `unconditional_transformer` separado remove o ruído com recursos de texto zerados. As duas previsões de velocidade são mescladas linearmente a cada etapa.

#### __call__[[diffusers.Ideogram4Pipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, height: int = 2048, width: int = 2048, num_inference_steps: int = 48, guidance_scale: float | None = None, guidance_schedule: typing.Union[list[float], torch.Tensor, NoneType] = (7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 3.0, 3.0, 3.0), mu: float = 0.0, std: float = 1.5, prompt_upsampling: bool = False, prompt_upsampling_temperature: float = 1.0, max_sequence_length: int = 2048, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[ForwardRef('Ideogram4Pipeline'), int, int, dict[str, typing.Any]], dict[str, typing.Any]]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

**Parâmetros:**

prompt (`str` ou `list[str]`) : Prompt(s) para orientar a geração de imagens.

height (`int`, *opcional*, padrão 2048) : Altura da imagem de saída em pixels; deve ser um múltiplo de `vae_scale_factor * patch_size`.

width (`int`, *opcional*, padrão 2048) : Largura da imagem de saída em pixels; deve ser um múltiplo de `vae_scale_factor * patch_size`.

num_inference_steps (`int`, *opcional*, padrão 48) : Número de etapas de flow-matching. O padrão é a configuração recomendada para a melhor qualidade.

guidance_scale (`float`, *opcional*) : Escala de orientação sem classificador constante aplicada em cada etapa. As previsões de velocidade condicionais e incondicionais são combinadas como `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. Mutuamente exclusivo com `guidance_schedule` (definir ambos gera um erro). O padrão é `None`.

guidance_schedule (`list[float]` ou `torch.Tensor`, *opcional*) : Escala de orientação por etapa; deve ter comprimento `num_inference_steps`. A primeira entrada corresponde à primeira etapa (maior nível de ruído). Mutuamente exclusivo com `guidance_scale`; exatamente um deve ser definido. O padrão é a escala recomendada (7.0 para as etapas principais, caindo para 3.0 nas 3 etapas finais de "acabamento"). Para usar uma escala constante, passe `guidance_scale` e `guidance_schedule=None`.

mu (`float`, *opcional*, padrão 0.0) : Média base do agendamento de flow-matching logit-normal. A média do agendamento é deslocada pela metade do log da razão de resolução em relação a 512x512.

std (`float`, *opcional*, padrão 1.5) : Desvio padrão do agendamento de flow-matching logit-normal.

prompt_upsampling (`bool`, *opcional*, padrão `False`) : Se `True`, reescreve o `prompt` para a legenda estruturada em JSON nativa do Ideogram4 via [upsample_prompt()](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) antes da codificação. Exige o componente opcional `prompt_enhancer_head`; instale `outlines` para legendas com esquema restrito. O `generator` é reutilizado para tornar o upsampling reproduzível.
prompt_upsampling_temperature (`float`, *opcional*, padrão 1.0) : Temperatura de amostragem para o upsampling do prompt quando `prompt_upsampling=True`.

max_sequence_length (`int`, *opcional*, padrão 2048) : Número máximo de tokens de texto por prompt.

num_images_per_prompt (`int`, *opcional*, padrão 1) : Número de imagens a serem geradas por prompt.
generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Gerador(es) usados para tornar a amostragem determinística.
latents (`torch.Tensor`, *opcional*) : Ruído pré-gerado com forma `(batch_size, num_image_tokens, latent_dim)`.
output_type (`str`, *opcional*, padrão `"pil"`) : Um dos valores `"pil"`, `"np"`, `"pt"` ou `"latent"`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve retornar um [Ideogram4PipelineOutput](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput).
attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs passado ao processador de atenção de cada transformer. Uma entrada `"scale"` escala os pesos LoRA carregados (por exemplo, `{"scale": 0.7}`) quando o backend PEFT está ativo.

callback_on_step_end (`Callable`, *opcional*) : Callback chamado no final de cada etapa de desruidamento.
callback_on_step_end_tensor_inputs (`list[str]`, *opcional*) : Nomes dos tensores a serem expostos ao callback via `callback_kwargs`.

**Retorna:**

[Ideogram4PipelineOutput](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) ou `tuple`.

Execute a geração de texto para imagem.

Exemplos:
```py
>>> import torch
>>> from diffusers import Ideogram4Pipeline
>>> pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A photo of a cat holding a sign that says hello world"
>>> # The defaults are the recommended settings for best quality.
>>> image = pipe(prompt, height=2048, width=2048, generator=torch.Generator("cuda").manual_seed(0)).images[0]
>>> image.save("ideogram4.png")
```

#### encode_prompt[[diffusers.Ideogram4Pipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

Prepare o condicionamento para a sequência empacotada de texto+imagem (uma entrada por prompt).

Retorna uma tupla plana `(prompt_embeds, position_ids, segment_ids, indicator)`. O ramo incondicional não carrega texto, portanto o pipeline constrói seus (zerados) inputs diretamente, em vez de codificar um prompt negativo.

#### upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

```python
upsample_prompt(prompt: str | list[str], height: int = 2048, width: int = 2048, temperature: float = 1.0, max_new_tokens: int = 1024, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, device: typing.Optional[torch.device] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

Reescreva cada prompt na legenda JSON estruturada nativa do Ideogram4.

Exige o componente opcional `prompt_enhancer_head`, que é acoplado ao corpo compartilhado do `text_encoder` para torná-lo generativo. A geração é restrita por esquema quando o `outlines` está instalado; caso contrário, ela é executada sem restrições. Passe `generator` (o mesmo aceito por `__call__`) para tornar a amostragem reproduzível.

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

```python
diffusers.Ideogram4PromptEnhancerHead(hidden_size: int = 4096, vocab_size: int = 151936)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

LM head que torna o `text_encoder` sem cabeça do Qwen3-VL generativo para o upsampling de prompts.

Um componente de pipeline opcional (`prompt_enhancer_head`): seus pesos são carregados via um `from_pretrained` normal (seu próprio repositório pequeno, ou incluído no repositório do modelo), em vez de um download dentro do pipeline. No momento do upsample, o pipeline o combina com o corpo compartilhado do `text_encoder` para formar o modelo generativo.

## Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

#### diffusers.pipelines.ideogram4.Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

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

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

**Parâmetros:**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : Lista de imagens PIL desruídas com comprimento `batch_size`, ou array numpy de forma `(batch_size, height, width, num_channels)`.

Classe de saída para o pipeline Ideogram 4.

Xet Storage Details

Size:: 14.9 kB
Xet hash:: 52915b8489af7124e2fb01282b6f9a3bc267766312528744b765eacc3ee44096

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Ideogram 4

	O Ideogram 4 é um modelo de texto para imagem baseado em flow-matching que utiliza um codificador de texto multimodal e um esquema de orientação livre de classificador assimétrico: um `unconditional_transformer` dedicado produz o ramo negativo com recursos de texto zerados, enquanto o `transformer` principal consome a sequência completa empacotada de texto + imagem.

	Os padrões do pipeline são as configurações recomendadas para a melhor qualidade, portanto, uma chamada simples de `pipe(prompt)` produz resultados de melhor qualidade imediatamente: 48 etapas de flow-matching em um agendamento logit-normal (`mu=0.0`, `std=1.5`) com classifier-free guidance mantido em 7.0 para as etapas principais e reduzido para 3.0 nas 3 etapas finais de "acabamento".

	Os principais parâmetros de inferência são expostos por meio da chamada do pipeline:

	- `num_inference_steps`, `mu` e `std` controlam o agendamento de flow-matching logit-normal sensível à resolução.
	- `guidance_scale` (ou um `guidance_schedule` completo por etapa) combina as velocidades condicionais e incondicionais.

	## Texto para imagem

	```python
	import torch
	from diffusers import Ideogram4Pipeline

	pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", dtype=torch.bfloat16)
	pipe.to("cuda") # or "mps", "xpu", "cpu"

	prompt = "A photo of a cat holding a sign that says hello world"
	# The defaults are the recommended settings for best quality.
	image = pipe(prompt, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
	image.save("ideogram4.png")
	```

	## Ampliação de prompt

	O Ideogram 4 é treinado com base em uma legenda JSON estruturada, em vez de um prompt em formato livre, portanto, um prompt curto é melhor expandido para esse esquema nativo antes da geração. Existem duas maneiras de produzir a legenda.

	### Remote (Ideogram API)

	Para obter os melhores resultados, expanda o prompt com a API magic-prompt hospedada pela Ideogram e passe a legenda retornada diretamente para o pipeline (obtenha uma chave em [developer.ideogram.ai](https://developer.ideogram.ai/)):

	```python
	import json
	import requests
	import torch
	from diffusers import Ideogram4Pipeline

	pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-4-nf4", dtype=torch.bfloat16)
	pipe.to("cuda") # or "mps", "xpu", "cpu"

	# Expand the prompt into a structured JSON caption with Ideogram's hosted magic-prompt API.
	response = requests.post(
	"https://api.ideogram.ai/v1/ideogram-v4/magic-prompt",
	headers={"Api-Key": "your_ideogram_api_key"},
	json={"text_prompt": "A photo of a cat holding a sign that says hello world", "aspect_ratio": "1x1"},
	).json()
	caption = json.dumps(response["json_prompt"])

	# The caption is already upsampled, so pass it directly (no prompt_upsampling).
	image = pipe(caption, height=1024, width=1024, generator=torch.Generator("cuda").manual_seed(0)).images[0]
	image.save("ideogram4_upsampled.png")
	```

	### Local (em dispositivo)

	Para um pipeline totalmente local, carregue um [Ideogram4PromptEnhancerHead](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) pequeno (o head do LM Qwen3-VL) como o componente opcional `prompt_enhancer_head` e passe `prompt_upsampling=True`. O head é acoplado ao `text_encoder` compartilhado, portanto, nenhum segundo codificador de texto é carregado. Instale `outlines` para legendas com esquema restrito (o checkpoint nf4 também requer `bitsandbytes`):

	```python
	import torch
	from diffusers import Ideogram4Pipeline, Ideogram4PromptEnhancerHead

	prompt_enhancer_head = Ideogram4PromptEnhancerHead.from_pretrained(
	"diffusers/qwen3-vl-8b-instruct-lm-head", dtype=torch.bfloat16
	)
	pipe = Ideogram4Pipeline.from_pretrained(
	"ideogram-ai/ideogram-4-nf4", prompt_enhancer_head=prompt_enhancer_head, dtype=torch.bfloat16
	)
	pipe.to("cuda") # or "mps", "xpu", "cpu"

	prompt = "A photo of a cat holding a sign that says hello world"
	image = pipe(
	prompt,
	height=1024,
	width=1024,
	prompt_upsampling=True,
	generator=torch.Generator("cuda").manual_seed(0),
	).images[0]
	image.save("ideogram4_upsampled.png")
	```

	## Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

	#### diffusers.Ideogram4Pipeline[[diffusers.Ideogram4Pipeline]]

	```python
	diffusers.Ideogram4Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLFlux2, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: Ideogram4Transformer2DModel, unconditional_transformer: Ideogram4Transformer2DModel, prompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead \| None = None)
	```

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

	Parâmetros:

	scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Agendador de fluxo correspondente (flow-matching). O pipeline substitui o agendamento de sigma padrão por um agendamento logit-normal sensível à resolução.

	vae (`AutoencoderKLFlux2`) : Autoencoder variacional usado para decodificar latentes de volta em imagens.

	text_encoder (`PreTrainedModel`) : Codificador de texto multimodal. O pipeline consome estados ocultos de um conjunto fixo de camadas intermediárias do decodificador (veja `QWEN3_VL_ACTIVATION_LAYERS`).

	tokenizer (`AutoTokenizer`) : Tokenizer associado ao `text_encoder`.

	transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/pt/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de fluxo condicional.

	unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/pt/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de flow-matching incondicional (asymmetric-CFG).

	Pipeline de texto para imagem para Ideogram4.

	Ideogram4 é um modelo de flow-matching treinado com orientação livre de classificador assimétrica: um `transformer` consome recursos condicionados por texto junto com os latentes da imagem, enquanto um `unconditional_transformer` separado remove o ruído com recursos de texto zerados. As duas previsões de velocidade são mescladas linearmente a cada etapa.

	#### __call__[[diffusers.Ideogram4Pipeline.__call__]]

	```python
	__call__(prompt: str \| list[str] \| None = None, height: int = 2048, width: int = 2048, num_inference_steps: int = 48, guidance_scale: float \| None = None, guidance_schedule: typing.Union[list[float], torch.Tensor, NoneType] = (7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0, 3.0, 3.0, 3.0), mu: float = 0.0, std: float = 1.5, prompt_upsampling: bool = False, prompt_upsampling_temperature: float = 1.0, max_sequence_length: int = 2048, num_images_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] \| None = None, callback_on_step_end: typing.Optional[typing.Callable[[ForwardRef('Ideogram4Pipeline'), int, int, dict[str, typing.Any]], dict[str, typing.Any]]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L481)

	Parâmetros:

	prompt (`str` ou `list[str]`) : Prompt(s) para orientar a geração de imagens.

	height (`int`, opcional, padrão 2048) : Altura da imagem de saída em pixels; deve ser um múltiplo de `vae_scale_factor * patch_size`.

	width (`int`, opcional, padrão 2048) : Largura da imagem de saída em pixels; deve ser um múltiplo de `vae_scale_factor * patch_size`.

	num_inference_steps (`int`, opcional, padrão 48) : Número de etapas de flow-matching. O padrão é a configuração recomendada para a melhor qualidade.

	guidance_scale (`float`, opcional) : Escala de orientação sem classificador constante aplicada em cada etapa. As previsões de velocidade condicionais e incondicionais são combinadas como `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. Mutuamente exclusivo com `guidance_schedule` (definir ambos gera um erro). O padrão é `None`.

	guidance_schedule (`list[float]` ou `torch.Tensor`, opcional) : Escala de orientação por etapa; deve ter comprimento `num_inference_steps`. A primeira entrada corresponde à primeira etapa (maior nível de ruído). Mutuamente exclusivo com `guidance_scale`; exatamente um deve ser definido. O padrão é a escala recomendada (7.0 para as etapas principais, caindo para 3.0 nas 3 etapas finais de "acabamento"). Para usar uma escala constante, passe `guidance_scale` e `guidance_schedule=None`.

	mu (`float`, opcional, padrão 0.0) : Média base do agendamento de flow-matching logit-normal. A média do agendamento é deslocada pela metade do log da razão de resolução em relação a 512x512.

	std (`float`, opcional, padrão 1.5) : Desvio padrão do agendamento de flow-matching logit-normal.

	prompt_upsampling (`bool`, opcional, padrão `False`) : Se `True`, reescreve o `prompt` para a legenda estruturada em JSON nativa do Ideogram4 via [upsample_prompt()](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) antes da codificação. Exige o componente opcional `prompt_enhancer_head`; instale `outlines` para legendas com esquema restrito. O `generator` é reutilizado para tornar o upsampling reproduzível.

	prompt_upsampling_temperature (`float`, opcional, padrão 1.0) : Temperatura de amostragem para o upsampling do prompt quando `prompt_upsampling=True`.

	max_sequence_length (`int`, opcional, padrão 2048) : Número máximo de tokens de texto por prompt.

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

	generator (`torch.Generator` ou `list[torch.Generator]`, opcional) : Gerador(es) usados para tornar a amostragem determinística.

	latents (`torch.Tensor`, opcional) : Ruído pré-gerado com forma `(batch_size, num_image_tokens, latent_dim)`.

	output_type (`str`, opcional, padrão `"pil"`) : Um dos valores `"pil"`, `"np"`, `"pt"` ou `"latent"`.

	return_dict (`bool`, opcional, padrão `True`) : Se deve retornar um [Ideogram4PipelineOutput](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput).

	attention_kwargs (`dict`, opcional) : Um dicionário de kwargs passado ao processador de atenção de cada transformer. Uma entrada `"scale"` escala os pesos LoRA carregados (por exemplo, `{"scale": 0.7}`) quando o backend PEFT está ativo.

	callback_on_step_end (`Callable`, opcional) : Callback chamado no final de cada etapa de desruidamento.

	callback_on_step_end_tensor_inputs (`list[str]`, opcional) : Nomes dos tensores a serem expostos ao callback via `callback_kwargs`.

	Retorna:

	[Ideogram4PipelineOutput](/docs/diffusers/main/pt/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput) ou `tuple`.

	Execute a geração de texto para imagem.

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

	>>> pipe = Ideogram4Pipeline.from_pretrained("ideogram-ai/ideogram-v4", torch_dtype=torch.bfloat16)
	>>> pipe.to("cuda")

	>>> prompt = "A photo of a cat holding a sign that says hello world"
	>>> # The defaults are the recommended settings for best quality.
	>>> image = pipe(prompt, height=2048, width=2048, generator=torch.Generator("cuda").manual_seed(0)).images[0]
	>>> image.save("ideogram4.png")
	```

	#### encode_prompt[[diffusers.Ideogram4Pipeline.encode_prompt]]

	```python
	encode_prompt(prompt: str \| list[str], grid_h: int, grid_w: int, max_sequence_length: int, device: device)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L335)

	Prepare o condicionamento para a sequência empacotada de texto+imagem (uma entrada por prompt).

	Retorna uma tupla plana `(prompt_embeds, position_ids, segment_ids, indicator)`. O ramo incondicional não carrega texto, portanto o pipeline constrói seus (zerados) inputs diretamente, em vez de codificar um prompt negativo.

	#### upsample_prompt[[diffusers.Ideogram4Pipeline.upsample_prompt]]

	```python
	upsample_prompt(prompt: str \| list[str], height: int = 2048, width: int = 2048, temperature: float = 1.0, max_new_tokens: int = 1024, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, device: typing.Optional[torch.device] = None)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/pipeline_ideogram4.py#L204)

	Reescreva cada prompt na legenda JSON estruturada nativa do Ideogram4.

	Exige o componente opcional `prompt_enhancer_head`, que é acoplado ao corpo compartilhado do `text_encoder` para torná-lo generativo. A geração é restrita por esquema quando o `outlines` está instalado; caso contrário, ela é executada sem restrições. Passe `generator` (o mesmo aceito por `__call__`) para tornar a amostragem reproduzível.

	## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

	#### diffusers.Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

	```python
	diffusers.Ideogram4PromptEnhancerHead(hidden_size: int = 4096, vocab_size: int = 151936)
	```

	[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ideogram4/prompt_enhancer.py#L42)

	LM head que torna o `text_encoder` sem cabeça do Qwen3-VL generativo para o upsampling de prompts.

	Um componente de pipeline opcional (`prompt_enhancer_head`): seus pesos são carregados via um `from_pretrained` normal (seu próprio repositório pequeno, ou incluído no repositório do modelo), em vez de um download dentro do pipeline. No momento do upsample, o pipeline o combina com o corpo compartilhado do `text_encoder` para formar o modelo generativo.

	## Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

	#### diffusers.pipelines.ideogram4.Ideogram4PipelineOutput[[diffusers.pipelines.ideogram4.Ideogram4PipelineOutput]]

	```python
	diffusers.pipelines.ideogram4.Ideogram4PipelineOutput(images: list[PIL.Image.Image] \| numpy.ndarray)
	```

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

	Parâmetros:

	images (`list[PIL.Image.Image]` ou `np.ndarray`) : Lista de imagens PIL desruídas com comprimento `batch_size`, ou array numpy de forma `(batch_size, height, width, num_channels)`.

	Classe de saída para o pipeline Ideogram 4.