# Ideogram 4 Local Execution in ComfyUI

Multiple paths exist to generate with Ideogram 4. The simplest is the cloud API node (`IdeogramV4`), but it requires a `comfy.org` API key. For local execution without cloud dependency, use the native `Ideogram4Scheduler` + model files.

## Path A: Cloud API Node (Simplest, but requires key)

**Node:** `IdeogramV4`  
**Location:** `comfy_api_nodes/nodes_ideogram.py`  
**Requires:** `COMFY_CLOUD_API_KEY` env var or login

**Error without auth:**
```
Unauthorized: Please login first to use this node.
```

Works with structured JSON prompt (scene + style + background blocks). The easiest if you have the key.

---

## Path B: Local Native Pipeline (No API key, but 28 GB disk needed)

**Recommended when:** No comfy.org auth available or prefer full local execution.

### Required Model Files

| File | Size | Folder | Source |
|---|---|---|---|
| `ideogram4_fp8_scaled.safetensors` | ~8.6 GB | `models/diffusion_models/` | HuggingFace: `Comfy-Org/Ideogram-4` |
| `ideogram4_unconditional_fp8_scaled.safetensors` | ~8.6 GB | `models/diffusion_models/` | HuggingFace: `Comfy-Org/Ideogram-4` |
| `flux2-vae.safetensors` | ~320 MB | `models/vae/` | HuggingFace: `Comfy-Org/flux2-dev` |
| `qwen3vl_8b_fp8_scaled.safetensors` | ~9.9 GB | `models/text_encoders/` | HuggingFace: `Comfy-Org/Qwen3-VL` |
| `gemma4_e4b_it_fp8_scaled.safetensors` | ~5.4 GB (optional alt) | `models/text_encoders/` | HuggingFace: `Comfy-Org/gemma-4` |

**Total: ~28 GB**

### Model Verification Recipe

A file can have the correct size on disk but still fail to load with `SafetensorError: incomplete metadata`. This happens when a download is interrupted and resumed incorrectly, or when the file was copied incompletely.

Use this Python script to verify any `.safetensors` file before trusting it:

```python
import struct, json, os

def verify_safetensors(path):
    """Check header metadata against actual file size."""
    actual = os.path.getsize(path)
    f = open(path, 'rb')
    header_len = struct.unpack("<Q", f.read(8))[0]
    meta = json.loads(f.read(header_len))
    total = 8 + header_len
    for k, v in meta.items():
        if isinstance(v, dict) and "data_offsets" in v:
            total += v["data_offsets"][1] - v["data_offsets"][0]
    return {
        "actual_bytes": actual,
        "expected_bytes": total,
        "ok": total == actual,
        "header_keys": len(meta),
        "missing": total - actual if total > actual else 0,
    }

# Example
result = verify_safetensors("models/text_encoders/qwen3vl_8b_fp8_scaled.safetensors")
print(result)
# If ok=False, the file is corrupt and MUST be re-downloaded.
```

**Command line shortcut (in Container):**
```bash
python3 -c "
import struct, json, os; p='/opt/ComfyUI/models/text_encoders/qwen3vl_8b_fp8_scaled.safetensors'
f=open(p,'rb'); h=struct.unpack('<Q',f.read(8))[0]; m=json.loads(f.read(h))
t=8+h; [t:=t+v['data_offsets'][1]-v['data_offsets'][0] for k,v in m.items()
 if isinstance(v,dict) and 'data_offsets' in v]
print('ok=',t==os.path.getsize(p))
"
```

### Text Encoder Compatibility Note

Ideogram 4 supports **two** text encoders:
- `qwen3vl_8b_fp8_scaled.safetensors` (Qwen3-VL, ~9.9 GB) — primary, higher quality
- `gemma4_e4b_it_fp8_scaled.safetensors` (Gemma 4, ~5.4 GB) — lighter alternative

If one fails (e.g., corrupt download), try the other.

### ComfyUI BluePrint Workflow (API Format)

The canonical workflow is shipped as a BluePrint JSON in ComfyUI:
```
blueprints/Text to Image (Ideogram v4).json
```

This uses the `Ideogram4Scheduler` + `DualModelGuider` with the two UNet files (conditional + unconditional) for asymmetric classifier-free guidance.

**Key nodes in the BluePrint:**
- `Ideogram4Scheduler` → outputs SIGMAS (replaces BasicScheduler)
- `DualModelGuider` → combines positive + unconditional models
- `CFGOverride` → cfg schedule override (start/end percent)
- `EmptyFlux2LatentImage` → 128-channel latent
- `SamplerCustomAdvanced` → with euler + Ideogram4Scheduler sigmas

### Common Errors — Local Path

**1. `SafetensorError: incomplete metadata, file not fully covered`**
- **Cause:** File is structurally corrupt (wrong tensor offsets in header).
- **Fix:** Run verification recipe above. If `ok=False`, delete and re-download from HuggingFace.
- **Important:** `ls -lh` showing the right size is NOT sufficient. The header values must match the data offsets.

**2. `Unauthorized: Please login first to use this node`**
- **Cause:** Using `IdeogramV1`/`V2`/`V3`/`V4` API node without comfy.org auth.
- **Fix:** Switch to local pipeline (`Ideogram4Scheduler` + model files), or add `COMFY_CLOUD_API_KEY`.

**3. `expected input[1, 128, 32, 32] to have 16 channels`**
- **Cause:** Using FLUX.1 VAE (`ae.safetensors`) instead of `flux2-vae.safetensors`.
- **Fix:** VAE must be `flux2-vae.safetensors` (or `taef2`).

## References

- ComfyUI BluePrints: `blueprints/Text to Image (Ideogram v4).json`
- Model source: https://huggingface.co/Comfy-Org/Ideogram-4
- Text encoder: https://huggingface.co/Comfy-Org/Qwen3-VL
- Alternative encoder: https://huggingface.co/Comfy-Org/gemma-4