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.43.0).
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→