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 adalah model teks-ke-gambar berbasis flow-matching yang menggunakan encoder teks multimodal dan skema panduan bebas-klasifikasi asimetris: unconditional_transformer khusus menghasilkan cabang negatif dengan fitur teks yang dinolkan, sementara transformer utama mengonsumsi urutan teks + gambar yang dikemas penuh.

Nilai bawaan pipeline adalah pengaturan yang direkomendasikan untuk kualitas terbaik, sehingga pemanggilan pipe(prompt) sederhana menghasilkan hasil berkualitas terbaik langsung dari awal: 48 langkah flow-matching pada jadwal logit-normal (mu=0.0, std=1.5) dengan classifier-free guidance dipertahankan pada 7.0 untuk langkah utama dan diturunkan ke 3.0 untuk 3 langkah “polish” terakhir.

Parameter utama saat inferensi dapat diatur melalui panggilan pipeline:

  • num_inference_steps, mu, dan std mengontrol jadwal flow-matching logit-normal yang sadar resolusi.
  • guidance_scale (atau guidance_schedule lengkap per langkah) mencampurkan kecepatan kondisional dan non-kondisional.

Teks-ke-gambar

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

Upsampling prompt

Ideogram 4 dilatih pada caption JSON terstruktur, bukan prompt bebas, sehingga prompt pendek sebaiknya diperluas ke skema native tersebut sebelum generasi. Ada dua cara untuk menghasilkan caption.

Remote (API Ideogram)

Untuk hasil terbaik, perluas prompt dengan API magic-prompt yang dihosting oleh Ideogram dan lewati caption yang dikembalikan langsung ke pipeline (dapatkan kunci di 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")

Lokal (di perangkat)

Untuk pipeline yang sepenuhnya lokal, muat Ideogram4PromptEnhancerHead kecil (head LM Qwen3-VL) sebagai komponen opsional prompt_enhancer_head dan teruskan prompt_upsampling=True. Head ini disambungkan ke text_encoder yang dibagikan, sehingga tidak ada text encoder kedua yang dimuat. Instal outlines untuk caption dengan kendala skema (checkpoint nf4 juga membutuhkan 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

kelas diffusers.Ideogram4Pipeline

< >

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

Parameter

  • scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler flow-matching. Pipeline ini menimpa jadwal sigma default dengan jadwal logit-normal yang sadar resolusi.
  • vae (AutoencoderKLFlux2) — Variational auto-encoder yang digunakan untuk mendekode latents kembali menjadi gambar.
  • text_encoder (PreTrainedModel) — Encoder teks multimodal. Pipeline mengonsumsi hidden states dari himpunan lapisan decoder antara yang tetap (lihat QWEN3_VL_ACTIVATION_LAYERS).
  • tokenizer (AutoTokenizer) — Tokenizer yang berpasangan dengan text_encoder.
  • transformer (Ideogram4Transformer2DModel) — Transformer flow-matching bersyarat.
  • unconditional_transformer (Ideogram4Transformer2DModel) — Transformer flow-matching tanpa syarat (asymmetric-CFG).

Pipeline teks-ke-gambar untuk Ideogram4.

Ideogram4 adalah model flow-matching yang dilatih dengan panduan classifier-free asimetris: sebuah transformer mengonsumsi fitur yang dikondisikan teks bersama dengan latens gambar, sementara unconditional_transformer yang terpisah melakukan denoising dengan fitur teks yang dinolkan. Kedua prediksi kecepatan tersebut dicampur secara linear pada setiap langkah.

__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'] )

Parameter

  • prompt (str atau list[str]) — Prompt untuk memandu pembuatan gambar.
  • height (int, opsional, default 2048) — Tinggi gambar output dalam piksel; harus merupakan kelipatan dari vae_scale_factor * patch_size.
  • width (int, opsional, default 2048) — Lebar gambar output dalam piksel; harus merupakan kelipatan dari vae_scale_factor * patch_size.
  • num_inference_steps (int, opsional, default 48) — Jumlah langkah flow-matching. Default adalah pengaturan yang direkomendasikan untuk kualitas terbaik.
  • guidance_scale (float, opsional) — Skala panduan klasifikasi bebas (classifier-free guidance) konstan yang diterapkan pada setiap langkah. Prediksi kecepatan kondisional dan tidak kondisional dicampur sebagai v = guidance_scale * v_pos + (1 - guidance_scale) * v_neg. Saling eksklusif dengan guidance_schedule (menetapkan keduanya akan memicu error). Nilai defaultnya adalah None.
  • guidance_schedule (list[float] atau torch.Tensor, opsional) — Jadwal skala panduan per langkah; harus memiliki panjang num_inference_steps. Entri pertama berkorespondensi dengan langkah pertama (tingkat kebisingan terbesar). Saling eksklusif dengan guidance_scale; tepat satu harus disetel. Secara default menggunakan jadwal yang direkomendasikan (7,0 untuk langkah utama, menurun ke 3,0 untuk 3 langkah “polish” terakhir). Untuk menggunakan skala konstan, berikan guidance_scale dan guidance_schedule=None.
  • mu (float, opsional, default 0.0) — Rata-rata dasar dari jadwal flow-matching logit-normal. Rata-rata jadwal digeser sebesar setengah log dari rasio resolusi relatif terhadap 512x512.
  • std (float, opsional, default 1.5) — Standar deviasi dari jadwal flow-matching logit-normal.
  • prompt_upsampling (bool, opsional, default False) — Jika True, tulis ulang prompt menjadi caption JSON terstruktur native Ideogram4 melalui upsample_prompt() sebelum encoding. Memerlukan komponen opsional prompt_enhancer_head; pasang outlines untuk caption dengan kendala skema. generator digunakan kembali agar upsampling dapat direproduksi.
  • prompt_upsampling_temperature (float, opsional, default 1.0) — Suhu sampling untuk prompt upsampling ketika prompt_upsampling=True.
  • max_sequence_length (int, opsional, default 2048) — Jumlah maksimum token teks per prompt.
  • num_images_per_prompt (int, opsional, default 1) — Jumlah gambar yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Generator yang digunakan untuk membuat sampling menjadi deterministik.
  • latents (torch.Tensor, opsional) — Noise yang telah dibuat sebelumnya dengan bentuk (batch_size, num_image_tokens, latent_dim).
  • output_type (str, opsional, defaultnya "pil") — Salah satu dari "pil", "np", "pt", atau "latent".
  • return_dict (bool, opsional, default True) — Apakah akan mengembalikan Ideogram4PipelineOutput.
  • attention_kwargs (dict, opsional) — Kamus kwargs yang diteruskan ke pemroses perhatian (attention processor) dari setiap transformer. Entri "scale" menyesuaikan bobot LoRA yang dimuat (mis. {"scale": 0.7}) saat backend PEFT aktif.
  • callback_on_step_end (Callable, opsional) — Callback yang dipanggil di akhir setiap langkah denoising.
  • callback_on_step_end_tensor_inputs (list[str], opsional) — Nama-nama tensor yang akan diekspos ke callback melalui callback_kwargs.

Jalankan generasi teks-ke-gambar.

Contoh:

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

Siapkan kondisioning untuk urutan teks+gambar yang dikemas (satu entri per prompt).

Mengembalikan tuple datar (prompt_embeds, position_ids, segment_ids, indicator). Cabang tanpa syarat tidak membawa teks, sehingga pipeline membangun inputnya (yang dinolkan) secara langsung alih-alih mengodekan prompt negatif.

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 )

Tulis ulang setiap prompt menjadi caption JSON terstruktur native Ideogram4.

Memerlukan komponen opsional prompt_enhancer_head, yang disambungkan ke tubuh text_encoder bersama untuk membuatnya generatif. Generasi dibatasi oleh skema jika outlines terpasang, jika tidak, ia berjalan tanpa batasan. Sampaikan generator (yang sama yang diterima oleh __call__) untuk membuat sampling dapat direproduksi.

Ideogram4PromptEnhancerHead

kelas diffusers.Ideogram4PromptEnhancerHead

< >

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

LM head yang membuat text_encoder Qwen3-VL tanpa head menjadi generatif untuk upsampling prompt.

Komponen pipeline opsional (prompt_enhancer_head): bobotnya dimuat melalui from_pretrained biasa (repo kecilnya sendiri, atau dibundel di repo model) alih-alih diunduh di dalam pipeline. Saat upsample, pipeline menggabungkannya dengan tubuh text_encoder bersama untuk membentuk model generatif.

Ideogram4PipelineOutput

kelas diffusers.pipelines.ideogram4.Ideogram4PipelineOutput

< >

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

Parameter

  • images (list[PIL.Image.Image] atau np.ndarray) — Daftar gambar PIL yang telah didenoise dengan panjang batch_size, atau array numpy dengan bentuk (batch_size, height, width, num_channels).

Kelas output untuk pipeline Ideogram 4.

Update on GitHub

←HunyuanImage2.1 InstructPix2Pix→