# Ideogram 4

Ideogram 4 es un modelo de texto a imagen basado en flow-matching que utiliza un codificador de texto multimodal y un esquema de guía libre de clasificador asimétrico: un `unconditional_transformer` dedicado produce la rama negativa con características de texto puestas a cero, mientras que el `transformer` principal consume la secuencia completa empaquetada de texto + imagen.

Los valores predeterminados del pipeline son las configuraciones recomendadas para obtener la mejor calidad, por lo que una llamada simple a `pipe(prompt)` produce resultados de la mejor calidad desde el inicio: 48 pasos de flow-matching en una programación logit-normal (`mu=0.0`, `std=1.5`) con classifier-free guidance mantenido en 7.0 para los pasos principales y reducido a 3.0 para los 3 pasos finales de "pulido".

Los parámetros clave de tiempo de inferencia se exponen a través de la llamada de pipeline:

- `num_inference_steps`, `mu` y `std` controlan el flujo de correspondencia logit-normal con resolución consciente.
- `guidance_scale` (o un `guidance_schedule` completo por paso) combina las velocidades condicionales y no condicionales.

## Texto a imagen

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

## Ampliación de prompts

Ideogram 4 se entrena con una descripción en JSON estructurada en lugar de un prompt libre, por lo que es mejor expandir un prompt corto a ese esquema nativo antes de la generación. Hay dos formas de generar la descripción.

### Remote (Ideogram API)

Para obtener los mejores resultados, expanda el prompt con la API magic-prompt alojada de Ideogram y pase la descripción devuelta directamente a la pipeline (obtenga una clave en [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 (en el dispositivo)

Para un pipeline totalmente local, cargue una pequeña [Ideogram4PromptEnhancerHead](/docs/diffusers/main/es/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) (la cabeza LM de Qwen3-VL) como el componente opcional `prompt_enhancer_head` y pase `prompt_upsampling=True`. La cabeza se injerta en el `text_encoder` compartido, por lo que no se carga un segundo codificador de texto. Instale `outlines` para descripciones con restricciones de esquema (el punto de control nf4 también requiere `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)
```

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

**Parámetros:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/es/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : Programador de flow-matching. El pipeline anula el programa de sigma predeterminado con un programa logit-normal consciente de la resolución.

vae (`AutoencoderKLFlux2`) : Autoencoder variacional utilizado para decodificar latentes de vuelta a imágenes.

text_encoder (`PreTrainedModel`) : Codificador de texto multimodal. El pipeline consume estados ocultos de un conjunto fijo de capas intermedias del decodificador (ver `QWEN3_VL_ACTIVATION_LAYERS`).

tokenizer (`AutoTokenizer`) : Tokenizador emparejado con `text_encoder`.

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

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

Pipeline de texto a imagen para Ideogram4.

Ideogram4 es un modelo de flow-matching entrenado con guía libre de clasificador asimétrica: un `transformer` consume características condicionadas por texto junto con los latentes de la imagen, mientras que un `unconditional_transformer` separado realiza el desruido con características de texto puestas a cero. Las dos predicciones de velocidad se combinan linealmente en cada paso.

#### __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 = ['latents'])
```

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

**Parámetros:**

prompt (`str` o `list[str]`) : Prompt(s) para guiar la generación de imágenes.

height (`int`, *opcional*, valor predeterminado 2048) : Altura de la imagen de salida en píxeles; debe ser un múltiplo de `vae_scale_factor * patch_size`.

width (`int`, *opcional*, valor predeterminado 2048) : Ancho de la imagen de salida en píxeles; debe ser un múltiplo de `vae_scale_factor * patch_size`.

num_inference_steps (`int`, *opcional*, valor predeterminado 48) : Número de pasos de flow-matching. El valor predeterminado es la configuración recomendada para la mejor calidad.

guidance_scale (`float`, *opcional*) : Escala de guía libre de clasificador constante aplicada en cada paso. Las predicciones de velocidad condicionales y no condicionales se combinan como `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. Es mutuamente excluyente con `guidance_schedule` (establecer ambos provoca un error). El valor predeterminado es `None`.

guidance_schedule (`list[float]` o `torch.Tensor`, *opcional*) : Programa de escala de guía por paso; debe tener longitud `num_inference_steps`. La primera entrada corresponde al primer paso (nivel de ruido más alto). Es mutuamente excluyente con `guidance_scale`; se debe establecer exactamente uno. Por defecto, se utiliza el programa recomendado (7.0 para los pasos principales, bajando a 3.0 para los 3 pasos finales de "pulido"). Para usar una escala constante en su lugar, pase `guidance_scale` y `guidance_schedule=None`.

mu (`float`, *opcional*, valor predeterminado 0.0) : Media base del programa de flow-matching logit-normal. La media del programa se desplaza la mitad del logaritmo de la relación de resolución respecto a 512x512.

std (`float`, *opcional*, valor predeterminado 1.5) : Desviación estándar del programa de flow-matching logit-normal.

prompt_upsampling (`bool`, *opcional*, valor predeterminado `False`) : Si es `True`, reescribe `prompt` en la descripción JSON estructurada nativa de Ideogram4 mediante [upsample_prompt()](/docs/diffusers/main/es/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) antes de codificarlo. Requiere el componente opcional `prompt_enhancer_head`; instala `outlines` para descripciones con restricciones de esquema. Se reutiliza `generator` para que el muestreo sea reproducible.

prompt_upsampling_temperature (`float`, *opcional*, valor predeterminado 1.0) : Temperatura de muestreo para el aumento de datos de los prompts cuando `prompt_upsampling=True`.

max_sequence_length (`int`, *opcional*, valor predeterminado 2048) : Número máximo de tokens de texto por indicación.

num_images_per_prompt (`int`, *opcional*, valor predeterminado 1) : Número de imágenes a generar por indicación.

generator (`torch.Generator` o `list[torch.Generator]`, *opcional*) : Generador(es) utilizados para hacer la muestreo determinista.

latents (`torch.Tensor`, *opcional*) : Ruido pregenerado de forma `(batch_size, num_image_tokens, latent_dim)`.

output_type (`str`, *opcional*, por defecto `"pil"`) : Uno de `"pil"`, `"np"`, `"pt"` o `"latent"`.

return_dict (`bool`, *opcional*, por defecto `True`) : Si se debe devolver una [Ideogram4PipelineOutput](/docs/diffusers/main/es/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput).

attention_kwargs (`dict`, *opcional*) : Un diccionario de kwargs que se pasa al procesador de atención de cada transformer. Una entrada `"scale"` escala los pesos de LoRA cargados (p. ej. `{"scale": 0.7}`) cuando el backend PEFT está activo.

callback_on_step_end (`Callable`, *opcional*) : Callback que se invoca al final de cada paso de desruido.

callback_on_step_end_tensor_inputs (`list[str]`, *opcional*) : Nombres de los tensores que se expondrán al callback a través de `callback_kwargs`.

**Devuelve:**

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

Ejecuta la generación de texto a imagen.

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

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

Prepara el condicionamiento para la secuencia empaquetada de texto+imagen (una entrada por prompt).

Devuelve una tupla plana `(prompt_embeds, position_ids, segment_ids, indicator)`. La rama incondicional no lleva texto, por lo que el pipeline construye sus entradas (a ceros) directamente en lugar de codificar un 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)
```

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

Reescribe cada indicación en la descripción JSON estructurada nativa de Ideogram4.

Requiere el componente opcional `prompt_enhancer_head`, que se injerta en el cuerpo compartido `text_encoder` para hacerlo generativo. La generación está restringida por el esquema cuando `outlines` está instalado; de lo contrario, se ejecuta sin restricciones. Pasa `generator` (el mismo aceptado por `__call__`) para hacer que el muestreo sea reproducible.

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

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

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

LM head que hace que el `text_encoder` sin cabeza de Qwen3-VL sea generativo para el muestreo de prompts.

Un componente de pipeline opcional (`prompt_enhancer_head`): sus pesos se cargan mediante un `from_pretrained` normal (su propio repositorio pequeño, o incluido en el repositorio del modelo) en lugar de una descarga dentro del pipeline. En el momento del upsample, el pipeline lo combina con el cuerpo compartido `text_encoder` para formar el 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)
```

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

**Parámetros:**

images (`list[PIL.Image.Image]` o `np.ndarray`) : Lista de imágenes PIL desruidas de longitud `batch_size`, o matriz numpy de forma `(batch_size, height, width, num_channels)`.

Clase de salida para el pipeline de Ideogram 4.