Hugging Face's logo

Diffusers documentation

Ideogram 4

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

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, é recomendável expandir um prompt curto para esse esquema nativo antes da geração. Existem duas maneiras de produzir a legenda.

Remoto (API da Ideogram)

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

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 (no dispositivo)

Para um pipeline totalmente local, carregue um 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):

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 )

Parâmetros

  • scheduler (FlowMatchEulerDiscreteScheduler) — Agendador de fluxo de correspondência. 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) — transformer de flow-matching condicional.
  • unconditional_transformer (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__

< >

( 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[str] = ['latents'] )

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 constante de orientação sem classificador 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 valor padrão é None.
  • guidance_schedule (list[float] ou torch.Tensor, opcional) — Agenda de 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 agenda recomendada (7.0 para as etapas principais, caindo para 3.0 nas 3 etapas finais de “acabamento”). Para usar uma escala constante em vez disso, 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 prompt na legenda JSON estruturada nativa do Ideogram4 via upsample_prompt() antes da codificação. Exige o componente opcional prompt_enhancer_head; instale outlines para legendas com esquema restrito. generator é reutilizado para tornar o upsampling reproduzível.
  • prompt_upsampling_temperature (float, opcional, padrão 1.0) — Temperatura de amostragem para o upsampling de 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 de "pil", "np", "pt" ou "latent".
  • return_dict (bool, opcional, padrão True) — Se deve retornar um 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.

Execute a geração de texto para imagem.

Exemplos:

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

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 diretamente suas entradas (zeradas) em vez de codificar um prompt negativo.

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 )

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, é executada sem restrições. Passe generator (o mesmo aceito por __call__) para tornar a amostragem reproduzível.

Ideogram4PromptEnhancerHead

classe diffusers.Ideogram4PromptEnhancerHead

< >

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

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

classe diffusers.pipelines.ideogram4.Ideogram4PipelineOutput

< >

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

Parâmetros

  • images (list[PIL.Image.Image] ou np.ndarray) — Lista de imagens PIL desruidas de comprimento batch_size, ou array numpy de forma (batch_size, height, width, num_channels).

Classe de saída para o pipeline Ideogram 4.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→