# Ideogram 4

Ideogram 4 est un modèle de génération d’images à partir de texte par flow-matching qui utilise un encodeur de texte multimodal et un schéma de guidance sans classifieur asymétrique : un `unconditional_transformer` dédié produit la branche négative avec des caractéristiques de texte nulles, tandis que le `transformer` principal consomme la séquence complète et compactée de texte + image.

Les valeurs par défaut du pipeline sont les paramètres recommandés pour une qualité optimale, de sorte qu'un simple appel `pipe(prompt)` produit des résultats de la meilleure qualité dès l'installation : 48 étapes de flow-matching sur un planning logit-normal (`mu=0.0`, `std=1.5`) avec un classifier-free guidance maintenu à 7,0 pour les étapes principales et réduit à 3,0 pour les 3 dernières étapes de « finition ».

Les principaux paramètres d'inférence sont exposés via l'appel du pipeline :

- `num_inference_steps`, `mu` et `std` contrôlent le plan de flow-matching logit-normal tenant compte de la résolution.
- `guidance_scale` (ou un `guidance_schedule` complet par étape) combine les vitesses conditionnelle et non conditionnelle.

## Texte vers image

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

## Échantillonnage supérieur des prompts

Ideogram 4 est entraîné sur une légende JSON structurée plutôt que sur un prompt libre, il est donc préférable d’étendre un prompt court vers ce schéma natif avant la génération. Il existe deux façons de produire la légende.

### Remote (Ideogram API)

Pour obtenir les meilleurs résultats, étendez le prompt avec l’API magic-prompt hébergée par Ideogram et transmettez la légende renvoyée directement au pipeline (obtenez une clé sur [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 (sur l'appareil)

Pour un pipeline entièrement local, chargez une petite [Ideogram4PromptEnhancerHead](/docs/diffusers/main/fr/api/pipelines/ideogram4#diffusers.Ideogram4PromptEnhancerHead) (la tête LM de Qwen3-VL) en tant que composant optionnel `prompt_enhancer_head` et passez `prompt_upsampling=True`. La tête est greffée sur le `text_encoder` partagé, de sorte qu'aucun second encodeur de texte n'est chargé. Installez `outlines` pour les légendes contraintes par schéma (le point de contrôle nf4 nécessite également `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)
```

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

**Paramètres :**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/fr/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : planificateur de correspondance de flux (flow-matching). Le pipeline remplace le plan de sigmas par défaut par un plan logit-normal prenant en compte la résolution.

vae (`AutoencoderKLFlux2`) : Auto-encodeur variationnel utilisé pour décoder les latents en images.

text_encoder (`PreTrainedModel`) : encodeur de texte multimodal. Le pipeline consomme les états cachés d'un ensemble fixe de couches intermédiaires du décodeur (voir `QWEN3_VL_ACTIVATION_LAYERS`).

tokenizer (`AutoTokenizer`) : Tokenizer associé à `text_encoder`.

transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/fr/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de correspondance de flux conditionnelle.

unconditional_transformer ([Ideogram4Transformer2DModel](/docs/diffusers/main/fr/api/models/ideogram4_transformer2d#diffusers.Ideogram4Transformer2DModel)) : Transformer de correspondance de flux non conditionnel (CFG asymétrique).

Pipeline de texte vers image pour Ideogram4.

Ideogram4 est un modèle de flow-matching entraîné avec un guidage sans classifieur asymétrique : un `transformer` consomme les fonctionnalités conditionnées par le texte aux côtés des latents de l'image, tandis qu'un `unconditional_transformer` distinct effectue le débruitage avec des fonctionnalités de texte nulles. Les deux prédictions de vitesse sont fusionnées linéairement à chaque étape.

#### __appel__[[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'])
```

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

**Paramètres :**

prompt (`str` ou `list[str]`) : Prompt(s) pour guider la génération d'images.

height (`int`, *facultatif*, valeur par défaut 2048) : Hauteur de l'image de sortie en pixels ; doit être un multiple de `vae_scale_factor * patch_size`.

width (`int`, *facultatif*, valeur par défaut 2048) : Largeur de l'image de sortie en pixels ; doit être un multiple de `vae_scale_factor * patch_size`.

num_inference_steps (`int`, *facultatif*, valeur par défaut 48) : Nombre d'étapes de flow-matching. La valeur par défaut est le paramétrage recommandé pour une qualité optimale.

guidance_scale (`float`, *facultatif*) : Échelle de guidage sans classifieur constante appliquée à chaque étape. Les prédictions de vitesse conditionnelle et non conditionnelle sont combinées selon `v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg`. Mutuellement exclusif avec `guidance_schedule` (définir les deux provoque une erreur). Valeur par défaut : `None`.

guidance_schedule (`list[float]` ou `torch.Tensor`, *facultatif*) : Plan d'échelle de guidage par étape ; doit avoir la longueur `num_inference_steps`. La première entrée correspond à la première étape (niveau de bruit le plus élevé). Mutuellement exclusif avec `guidance_scale` ; exactement l'un des deux doit être défini. Par défaut, le plan recommandé est utilisé (7,0 pour les étapes principales, en diminuant à 3,0 pour les 3 dernières étapes de « finition »). Pour utiliser une échelle constante à la place, passez `guidance_scale` et `guidance_schedule=None`.

mu (`float`, *facultatif*, valeur par défaut 0.0) : Moyenne de base du planning de flow-matching logit-normal. La moyenne du planning est décalée de la moitié du logarithme du ratio de résolution par rapport à 512x512.

std (`float`, *facultatif*, valeur par défaut 1.5) : Écart-type de l'ordonnancement de flow-matching logit-normal.

prompt_upsampling (`bool`, *facultatif*, valeur par défaut `False`) : Si `True`, réécrit `prompt` en légende JSON structurée native d'Ideogram4 via [upsample_prompt()](/docs/diffusers/main/fr/api/pipelines/ideogram4#diffusers.Ideogram4Pipeline.upsample_prompt) avant l'encodage. Nécessite le composant facultatif `prompt_enhancer_head` ; installez `outlines` pour des légendes contraintes par schéma. `generator` est réutilisé pour rendre le suréchantillonnage reproductible.

prompt_upsampling_temperature (`float`, *facultatif*, valeur par défaut 1.0) : Température d'échantillonnage pour le suréchantillonnage du prompt lorsque `prompt_upsampling=True`.

max_sequence_length (`int`, *facultatif*, valeur par défaut 2048) : Nombre maximal de jetons de texte par invite.

num_images_per_prompt (`int`, *facultatif*, valeur par défaut 1) : Nombre d'images à générer par invite.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Générateur(s) utilisé(s) pour rendre l'échantillonnage déterministe.

latents (`torch.Tensor`, *facultatif*) : Bruit pré-généré de forme `(batch_size, num_image_tokens, latent_dim)`.

output_type (`str`, *facultatif*, par défaut `"pil"`) : L'un des `"pil"`, `"np"`, `"pt"` ou `"latent"`.

return_dict (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut retourner un [Ideogram4PipelineOutput](/docs/diffusers/main/fr/api/pipelines/ideogram4#diffusers.pipelines.ideogram4.Ideogram4PipelineOutput).

attention_kwargs (`dict`, *facultatif*) : Un dictionnaire kwargs transmis au processeur d'attention de chaque transformer. Une entrée `"scale"` met à l'échelle les poids LoRA chargés (par ex. `{"scale": 0.7}`) lorsque le backend PEFT est actif.

callback_on_step_end (`Callable`, *facultatif*) : Callback appelé à la fin de chaque étape de débruitage.

callback_on_step_end_tensor_inputs (`list[str]`, *facultatif*) : Noms des tenseurs à exposer au rappel via `callback_kwargs`.

**Retourne :**

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

Exécuter la génération d’images à partir de texte.

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

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

Préparez le conditionnement pour la séquence texte+image compactée (une entrée par invite).

Retourne un tuple aplati `(prompt_embeds, position_ids, segment_ids, indicator)`. La branche inconditionnelle ne contient aucun texte, le pipeline construit donc directement ses entrées (remplies de zéros) plutôt que d’encoder un prompt négatif.

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

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

Réécrivez chaque invite sous forme de légende JSON structurée native d’Ideogram4.

Nécessite le composant optionnel `prompt_enhancer_head`, greffé sur le corps partagé `text_encoder` pour le rendre génératif. La génération est contrainte par le schéma si `outlines` est installé, sinon elle s’exécute sans contrainte. Passez `generator` (le même que celui accepté par `__call__`) pour rendre l’échantillonnage reproductible.

## Ideogram4PromptEnhancerHead[[diffusers.Ideogram4PromptEnhancerHead]]

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

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

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

Tête LM qui rend le `text_encoder` sans tête de Qwen3-VL génératif pour l'échantillonnage de prompts.

Un composant de pipeline facultatif (`prompt_enhancer_head`) : ses poids sont chargés via un `from_pretrained` standard (son propre petit dépôt, ou inclus dans le dépôt du modèle) plutôt que par un téléchargement au sein du pipeline. Lors de l'upsampling, le pipeline le combine avec le corps partagé `text_encoder` pour former le modèle génératif.

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

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

**Paramètres :**

images (`list[PIL.Image.Image]` ou `np.ndarray`) : Liste d'images PIL débruitées de longueur `batch_size`, ou tableau numpy de forme `(batch_size, height, width, num_channels)`.

Classe de sortie pour le pipeline Ideogram 4.