comfyui_o1key/docs/decisions/0002-save-node-image-format-ownership.md

0002: Save-node ownership of generated image formats

• Status: Superseded by 0003
• Date: 2026-08-30
• Owners: Maintainers

Context

The unified background generator previously decoded provider results and permanently re-encoded Nano Banana output as PNG. This obscured whether output_format was a provider capability or a local save choice, and discarded the original PNG/JPEG container returned by Nano Banana. The released O1keyImageSave node also delegated to ComfyUI's PNG-only helper.

Decision

Generation paths retain provider bytes and detected format. Panel-triggered jobs place those bytes in ComfyUI temp storage and return type=temp descriptors. O1keyImageSave is the only component that promotes them into output storage, through its append-only 格式 widget and the batch-bound /o1key/image/save route.

格式=原始 preserves PNG/JPEG/WebP compressed image data; workflow metadata may be inserted into the container without recompressing pixels. Explicit PNG and WebP use lossless encoding. Explicit JPEG uses quality 100 with 4:4:4 subsampling. If pixels were modified after generation or original bytes are unavailable, 原始 falls back to PNG.

Nano Banana payloads never contain output_format. GPT Image keeps its API-level output_format, which determines provider output but does not bypass the save node.

Consequences

• Nano Banana PNG and JPEG responses remain distinguishable and recoverable.
• API output options and local save options have separate owners and labels.
• Background generation must retain temp results until the save route succeeds.
• Original-format preservation requires private in-memory tensor metadata on the direct execution path; ordinary downstream tensor operations may invalidate it and trigger the PNG fallback.
• Existing workflows gain only one appended save-node widget and migrate to 原始 idempotently.

Alternatives considered

• Continue saving every background result as PNG. Rejected because it destroys the provider container and implies a Nano Banana capability that does not exist.
• Let the generator select the permanent local format. Rejected because it duplicates the output responsibility and leaves the save node semantically misleading.
• Store original bytes inside workflow JSON. Rejected because large binary payloads do not belong in workflows and would make saved graphs unsafe and impractical.

Validation

• tests/test_o1key_image_save.py verifies original JPEG/PNG preservation, metadata injection, explicit conversions, and PNG fallback.
• tests/test_o1key_image_jobs.py verifies Nano Banana ignores GPT-only fields, jobs produce temp descriptors, and save-route path binding.
• tests/test_o1key_image_generator_frontend.mjs verifies temp promotion, workflow metadata submission, result restoration, and idempotent widget migration.