https://github.com/yamasoo/z_image_json_prompt

V2

Z-Image-JSON-Prompt: Structured Prompt Generator for ComfyUI

Project Introduction

The Z-Image-JSON-Prompt custom node for ComfyUI and other node-based WebUIs provides a robust and structured workflow for managing and generating complex image prompts. It addresses the limitations of monolithic text prompts by breaking down creative elements into distinct, manageable categories, allowing users to build highly specific and reproducible image generation settings.

Key Features

• Structured Prompting: Organizes prompts into five main categories (Scene, Subject, Photography, Lighting, Style) and fifteen sub-options for clear, hierarchical composition.

• Customizable Options: Automatically generates an z_image_options directory, enabling users to easily modify and expand the prompt choices via simple .txt files.

• Style Templates: Includes built-in style templates (e.g., Cyberpunk, Fantasy Magic, Cinematic Portrait) that can be applied with a single click to accelerate creation.

• Multi-Language Support: Supports output in English, Chinese, or Bilingual format, accommodating various models and user preferences.

• Dual Output Formats:

  • json_prompt: Outputs a full structured JSON object containing all settings for archival and programmatic use.

  • positive_text: Outputs a clean, four-part text prompt ready to be connected to Samplers or other text-input nodes.

• Detail Level Control: Offers control over prompt verbosity with options ranging from "Brief" to "Extremely Detailed."

Installation

1. Place z_image_json_prompt.py into your ComfyUI custom nodes directory (e.g., custom_nodes/z_image_json_prompt/).

2. Ensure you have a correct __init__.py file in the directory if it is a folder (see previous advice).

3. Restart ComfyUI. The node will be available under the Z-Image category as Z-Image JSON Prompt Generator.

# Z-Image-JSON-Prompt 🏷️

一個強大且結構化的 ComfyUI / 節點式 WebUI 提示詞生成器。

Z-Image-JSON-Prompt 節點旨在解決傳統文字提示詞缺乏組織和難以管理的問題。它將圖像生成的關鍵元素（場景、主體、攝影、燈光、風格）結構化，允許使用者通過清晰的選項列表和預設模板快速生成複雜、高品質的提示詞。

### ✨ 核心功能

* 結構化輸入：將提示詞分解為五大類 (場景、主體、攝影、燈光、風格) 和十五個子選項，使提示詞的構建邏輯清晰。

* 選項自定義：節點會自動生成一個名為 z_image_options 的目錄，使用者可以輕鬆修改內部的 .txt 檔案來**增加或修改提示詞選項**。

* 內建風格模板：提供十多種預設風格（如賽博朋克、奇幻魔法、電影人像等），可一鍵應用，加速創作流程。

* 多語言輸出：支援 中文、英文、雙語 三種模式輸出，滿足不同模型或使用者需求。

* 多格式輸出：

* *json_prompt**：輸出包含所有設定的結構化 JSON 資料，方便追溯、存檔或程式化使用。

* *positive_text**：輸出四段式（核心、環境、技術、風格）的純文字提示詞，可直接饋入圖像生成模型。

* 細節等級控制：可選擇「簡略」、「標準」、「詳細」、「極度詳細」來控制輸出提示詞的豐富度。

### 🚀 安裝與使用

#### 1. 安裝

1. 將 z_image_json_prompt.py 檔案放置到您的 ComfyUI 自定義節點目錄下（通常是 custom_nodes/）。或在custom_nodes新建一個資料夾(例custom_nodes/z_image_json_prompt/)將z_image_json_prompt.py和__init__.py放入資料夾

2. 重新啟動 ComfyUI。

3. 在節點選單中，您可以在 *Z-Image** 類別下找到 *Z-Image JSON Prompt Generator** 節點。

#### 2. 第一次運行

當您第一次運行此節點時，它會自動在您的腳本目錄下創建一個名為 *z_image_options** 的資料夾，其中包含：

* 五個分類資料夾 scene, subject, photography, lighting, style)，每個資料夾內有數個 .txt 檔案，用於儲存選項。

* *templates 資料夾**，內含預設的 .json 模板檔案。

您可以編輯這些 .txt 或 .json 檔案來擴展您的提示詞庫。

#### 3. 節點輸入參數說明

| 參數名稱 | 類型 | 說明 | 預設值 |

| :--- | :--- | :--- | :--- |

| *style_template** | 選擇列表 | 一鍵選擇預設風格模板，將覆蓋對應的選項。 | 無模板 | No Template |

| *language_choice** | 選擇列表 | 決定輸出提示詞的語言（中文/English/雙語）。 | 雙語 | Bilingual |

| *detail_level** | 選擇列表 | 控制輸出提示詞的複雜度及描述詞的豐富度。 | 標準 | Standard |

| *negative_prompt** | 文本輸入 | 負面提示詞，將原樣輸出。 | 預設低品質相關的提示詞。 |

| *【...】_...** | 選擇列表 | 各類型的提示詞選項。選擇 *隨機 | Random** 將從對應檔案中隨機抽取。 | 隨機 | Random |

#### 4. 節點輸出

| 輸出名稱 | 類型 | 說明 |

| :--- | :--- | :--- |

| *json_prompt** | STRING | 完整的結構化 JSON 輸出，包含所有設定和元數據。 |

| *positive_text** | STRING | 四段式的純文字提示詞，可直接連線到 KSampler 或其他提示詞輸入節點。 |

| *negative_prompt** | STRING | 負面提示詞文本。 |

只是一個簡單的COMFYUI節點,靈感來自於社群討論https://www.reddit.com/r/StableDiffusion/comments/1p809wt/

雖然我的結論是直接輸入json內容不行會在圖片中產生大量的錯誤資訊

但這個想法可以產生結構化的prompts

直接把z_image_json_prompt.py放到IComfyUI\custom_nodes底下就行

他會自動產生一個目錄產生所需的檔案

z_image_json_prompt.json則是示範工作流

Z-image JSON Prompting for ComfyUI

A ComfyUI custom node for generating structured, detailed prompts in JSON format, inspired by the community discussion on Reddit.

画像を表示 画像を表示 画像を表示

💡 Concept

While directly feeding JSON to image models produces artifacts and errors (as tested), this node takes a different approach:

✅ Generate structured JSON prompts for organization and reusability
✅ Convert to optimized text prompts for actual image generation
✅ Maintain detailed prompt components in a readable format

Think of it as a prompt construction framework rather than direct JSON-to-image generation.

✨ Features

📋 Triple Output Format

• JSON Output - Complete structured prompt with all components

• Text Output - Optimized positive prompt for image generation

• Negative Prompt - Separate negative guidance

🎨 Detailed Component Categories

Inspired by professional photography and filmmaking workflows:

CategoryComponentsSceneOverall scene descriptionSubjectType, skin detail, attire, hair, position, expressionActionPrimary action, visual effectsEnvironmentSetting, background elements, atmosphereCameraLens specs, angle, film simulationLightingStyle, key light, fill light, contrastStyleMedium, aesthetic, quality, color palette, special layers

🎲 Smart Randomization

• Each parameter supports random, none, or manual selection

• Auto-generates from curated option files

• Easily customizable via text files

🔄 Automatic Setup

• Creates z_image_options folder on first run

• Auto-generates all option files with defaults

• No manual configuration needed

📦 Installation

Method 1: Direct Download (Recommended)

1. Download z_image_json_prompt.py

2. Place it in: ComfyUI/custom_nodes/

3. Restart ComfyUI

4. The node will automatically create the z_image_options folder with all necessary files

Method 2: Git Clone

bash

cd ComfyUI/custom_nodes/
git clone https://github.com/yourusername/z-image-json-prompting
# Restart ComfyUI

Folder Structure (Auto-generated)

ComfyUI/
└── custom_nodes/
    ├── z_image_json_prompt.py
    └── z_image_options/          # Auto-created on first run
        ├── scene_description.txt
        ├── subject_type.txt
        ├── skin_detail.txt
        ├── attire_detail.txt
        └── ... (22 more option files)

🚀 Usage

Basic Workflow

1. Add the node: Search for Z-image JSON Prompting in ComfyUI

2. Configure parameters: Choose from dropdowns or use "random"

3. Connect outputs:

   • json_prompt → Text display or save node (for documentation)

   • positive_text → Your image model's positive prompt

   • negative_prompt → Your image model's negative prompt

Example Workflow

A demo workflow is included: z_image_json_prompt.json

To use:

1. Drag z_image_json_prompt.json into ComfyUI

2. The workflow demonstrates all three outputs

3. Customize parameters as needed

Output Examples

JSON Output:

json

{
  "scene_description": "Hyper-realistic street photography merged with explosive 2D old-school hip-hop graffiti doodles",
  "subject": {
    "type": "Cool Black/Latino young man, early 20s, street-dancer build",
    "skin": "Natural skin texture, subtle pores, light sweat sheen",
    "attire": "Oversized white graphic tee, olive cargo pants with fabric folds",
    "hair": "Fresh medium-length twist sponge curls",
    "position": "Dynamic low crouch, one knee down",
    "expression": "Eyes half-closed, subtle smirk, zoned into the beat"
  },
  "camera_settings": {
    "lens": "35mm f/1.4 prime, shot at f/2.0",
    "angle": "Low-angle street photography perspective"
  },
  ...
}

Text Output (for image generation):

Hyper-realistic street photography merged with explosive 2D old-school hip-hop graffiti doodles, 8K resolution insanely sharp, Ultra-detailed photorealistic photography, Subject: Cool Black/Latino young man early 20s street-dancer build, wearing oversized white graphic tee olive cargo pants, dynamic low crouch one knee down, eyes half-closed subtle smirk, deep in the music feeling the bass drop, Setting: Grimy NYC-style subway platform at night, low-angle street photography perspective, harsh overhead fluorescent lighting, raw urban energy rhythmic loud youthful rebellion

🎨 Customization

Editing Options

All options are stored in plain text files under z_image_options/:

bash

# Example: Edit subject types
nano z_image_options/subject_type.txt

Format: One option per line

Cool Black/Latino young man, early 20s, street-dancer build
Elegant Asian woman, late 20s, professional model physique
Mysterious hooded figure, ageless, lean athletic build
# Add your own here

Adding New Options

Simply add new lines to any .txt file - they'll appear in the dropdown on next restart.

🔧 Parameters Reference

<details> <summary><b>Scene Level (1 parameter)</b></summary>

• scene_description - Overall scene overview and style description

</details> <details> <summary><b>Subject (6 parameters)</b></summary>

• subject_type - Character type, age, build

• skin_detail - Skin texture, pores, complexion details

• attire_detail - Clothing description with fabric and wear details

• hair_style - Hair length, style, condition

• position - Body pose and positioning

• expression - Facial expression and mood

</details> <details> <summary><b>Action (2 parameters)</b></summary>

• primary_action - Main action or activity

• visual_effect - Special visual effects accompanying the action

</details> <details> <summary><b>Environment (3 parameters)</b></summary>

• setting - Location and environment description

• background_elements - Specific background details

• atmosphere - Overall mood and atmospheric conditions

</details> <details> <summary><b>Camera Settings (3 parameters)</b></summary>

• lens_spec - Lens type, focal length, aperture

• camera_angle - Camera positioning and perspective

• film_simulation - Film stock emulation settings

</details> <details> <summary><b>Lighting (4 parameters)</b></summary>

• lighting_style - Overall lighting approach

• key_light - Primary light source description

• fill_light - Secondary/fill lighting details

• contrast_level - Shadow and highlight contrast

</details> <details> <summary><b>Style (5 parameters)</b></summary>

• render_medium - Rendering style and medium

• aesthetic - Overall artistic direction

• quality_setting - Resolution and quality descriptors

• color_palette - Color scheme and tone

• special_layer - Special effects or overlay styles

</details>

🤔 Why Not Direct JSON Input?

After testing (as discussed in the Reddit thread), feeding raw JSON directly to Stable Diffusion models produces:

❌ Text artifacts in the image
❌ JSON syntax appearing as visual elements
❌ Poor understanding of the actual intended content

This node solves that by:

✅ Storing prompt structure as JSON (for organization)
✅ Converting to optimized text (for generation)
✅ Preserving both formats (for flexibility)

📊 Use Cases

1. Professional Workflows

• Maintain detailed prompt documentation

• Version control for complex prompts

• Team collaboration with structured formats

2. Prompt Libraries

• Save JSON prompts as reusable templates

• Mix and match components

• Build prompt collections systematically

🐛 Troubleshooting

Node doesn't appear after installation

• Ensure the file is in ComfyUI/custom_nodes/

• Restart ComfyUI completely

• Check console for Python errors

Options not loading

• The z_image_options folder will auto-create on first run

• If missing, delete and let it regenerate