comfyui_o1key/docs/decisions/0003-generator-owned-image-save-configuration.md

0003: Generator-owned image save configuration

• Status: Accepted
• Date: 2026-09-02
• Owners: Maintainers
• Supersedes: 0002

Context

The unified image workflow exposed naming, local format conversion, and output location on every O1keyImageSave result node. A single generator may create several result nodes, so this duplicated settings and made model-level behavior hard to understand. GPT Image's API output_format is also semantically different from Nano Banana's optional local save conversion.

Moving released positional widgets between nodes risks silently changing saved workflows. Multiple old save nodes may also carry different settings even though the new design has one shared generator configuration.

Decision

O1keyImageGenerator owns four append-only save inputs at indexes 19–22: 命名规则, filename_prefix, 格式, and 保存位置. 命名规则 keeps the serialized value 自定义前缀 for compatibility but displays 自定义. O1keyImageSave removes all configuration widgets and remains the sole permanent file writer and result renderer.

Direct execution attaches validated save settings to the output tensor. Panel jobs snapshot them in the server-side job record at submission, and the save route prefers that immutable snapshot. The frontend migration finds the generator connected to each legacy save node, moves the first connected save node's positional settings into the generator, clears migrated save-node values, and is safe to repeat.

Local 格式 is visible and effective only for Banana models. GPT Image always uses local 原始; its independent API 输出格式 displays JPEG / PNG / WebP, stores lowercase values, and defaults new nodes to jpeg. Legacy generators retain saved API-format values and use the historical png default only when migrating workflows that predate that field.

Consequences

• One generator controls naming and destination for all of its current and future result nodes.
• Multiple legacy save nodes with different settings cannot all be represented; migration deterministically uses the first connected save node.
• Existing node IDs, image ports, and the first nineteen generator widget positions remain unchanged.
• Save-node preview and retry behavior remains independent from save configuration.
• GPT provider format and Banana local conversion have separate controls and cannot accidentally override one another.

Alternatives considered

• Keep configuration duplicated on every save node. Rejected because it conflicts with generator-wide settings and obscures provider capabilities.
• Keep only filename_prefix on the save node. Rejected because the default custom naming rule would then be split across two nodes.
• Rename the serialized 自定义前缀 value to 自定义. Rejected because the visible label can change without breaking saved workflows or backend validation.

Validation

• tests/test_o1key_image_generator.py verifies schema positions, defaults, tensor-carried settings, GPT lowercase jpeg, and the parameter-free save node.
• tests/test_o1key_image_jobs.py verifies immutable job save settings and GPT's forced local 原始 behavior.
• tests/test_o1key_image_generator_frontend.mjs verifies model-dependent visibility, temp promotion settings, zero-widget result nodes, and idempotent cross-node migration.