Hugging Face's logo

Diffusers documentation

Ideogram 4

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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 guidage 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 de texte et d’image empaquetée.

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

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’élargir un prompt court vers ce schéma natif avant la génération. Il existe deux façons de produire la légende.

Distant (API Ideogram)

Pour de 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) :

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 (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) :

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

classe diffusers.Ideogram4Pipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: PreTrainedModeltokenizer: AutoTokenizertransformer: Ideogram4Transformer2DModelunconditional_transformer: Ideogram4Transformer2DModelprompt_enhancer_head: diffusers.pipelines.ideogram4.prompt_enhancer.Ideogram4PromptEnhancerHead | None = None )

Paramètres

  • scheduler (FlowMatchEulerDiscreteScheduler) — Planificateur de flow-matching. Le pipeline remplace le plan de sigma 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) — Transformateur de correspondance de flux conditionnelle.
  • unconditional_transformer (Ideogram4Transformer2DModel) — Transformeur de flow-matching non conditionnel (asymétrique-CFG).

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 textuelles nulles. Les deux prédictions de vitesse sont fusionnées linéairement à chaque étape.

__call__

< >

( prompt: str | list[str] | None = Noneheight: int = 2048width: int = 2048num_inference_steps: int = 48guidance_scale: float | None = Noneguidance_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.0std: float = 1.5prompt_upsampling: bool = Falseprompt_upsampling_temperature: float = 1.0max_sequence_length: int = 2048num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[ForwardRef('Ideogram4Pipeline'), int, int, dict[str, typing.Any]], dict[str, typing.Any]]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents'] )

Paramètres

  • prompt (str ou list[str]) — Prompt(s) pour guider la génération d’images.
  • height (int, facultatif, 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, 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 de l’horaire de flow-matching logit-normal. La moyenne de l’horaire 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, par défaut False) — Si True, réécrit prompt en légende JSON structurée native d’Ideogram4 via 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 l’upsampling reproductible.
  • prompt_upsampling_temperature (float, facultatif, valeur par défaut 1.0) — Température d'échantillonnage pour l'augmentation de 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, valeur par défaut True) — Indique s'il faut retourner un Ideogram4PipelineOutput.
  • attention_kwargs (dict, facultatif) — Dictionnaire de 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 callback via callback_kwargs.

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

Exemples :

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

< >

( prompt: str | list[str]grid_h: intgrid_w: intmax_sequence_length: intdevice: device )

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

< >

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

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

classe diffusers.Ideogram4PromptEnhancerHead

< >

( hidden_size: int = 4096vocab_size: int = 151936 )

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

classe diffusers.pipelines.ideogram4.Ideogram4PipelineOutput

< >

( images: list[PIL.Image.Image] | numpy.ndarray )

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.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→