Grok Image to T2I Prompt

ComfyUI-GrokImagePrompt

Custom ComfyUI node that sends a reference image to Grok and returns:

1. A detailed description of the image
2. A T2I prompt optimized so you can recreate similar images

The node appears under Grok/Image as Grok Image to T2I Prompt.

Installation

From ComfyUI-Manager or the Comfy CLI, after the package is on the registry:

comfy node install grok-image-prompt

From a git checkout:

1. Clone this repository into ComfyUI/custom_nodes/ComfyUI-GrokImagePrompt
2. Install requirements.txt into the same Python environment ComfyUI uses (requests; Pillow and NumPy normally ship with ComfyUI)
3. Restart ComfyUI
4. Find the node in Grok/Image

This is a server-side node. It has no JavaScript UI. ComfyUI loads it because __init__.py exports NODE_CLASS_MAPPINGS. The workflow identity is the class key GrokImagePrompt. That key stays stable across releases so saved workflows keep working.

Authentication

The node uses the first key it finds:

1. The api_key widget, when it is not empty
2. The XAI_API_KEY environment variable
3. The token in ~/.grok/auth.json (after grok login)

Get an API key from console.x.ai.

Usage

1. Connect an image to image
2. Set t2i_model to the generator you will use (Flux, SDXL, Pony, Illustrious, …)
3. Optionally add extra instructions in user_request and extra_config
4. Queue the prompt

example_workflows/ComfyUI-GrokImagePrompt Example Workflow.json is a ready graph: Load Image, this node, and a preview for each string output. Load Image starts on empty.png. Choose your own reference image before you queue it. ComfyUI lists this file under workflow templates because it sits in example_workflows.

This node is an output node, so the workflow can end on it. ComfyUI only runs a prompt that contains at least one output (Save Image, Preview Image, or a node marked as an output). The description and T2I prompt are printed in the ComfyUI console. You can still connect the string outputs to another node.

Inputs

| Input | Type | Description | |-------|------|-------------| | image | IMAGE | Reference image. The first frame of the batch is JPEG-encoded and resized so the longest side is at most 512px. Aspect ratio is kept. Images already smaller than that are left unchanged. | | t2i_model | STRING | Target text-to-image model the prompt should be written for. Examples: Flux, SDXL, Pony, Illustrious, SD3. Grok follows that model's prompt style (natural language for Flux, tags for Pony/SDXL when appropriate). | | user_request | STRING (multiline) | Extra instructions on top of the default task. Examples: focus on the pose, ignore the background, restyle as anime, describe clothing only. | | api_key | STRING (optional) | xAI API key. Leave empty to fall back to XAI_API_KEY, then ~/.grok/auth.json. | | model_name | dropdown (optional) | Grok model used for vision + prompt writing. Default: grok-4.7. | | temperature | FLOAT (optional) | Sampling temperature (0.0–2.0, default 0.5). Lower is more consistent; higher is more varied wording. | | max_tokens | INT (optional) | Maximum tokens in Grok's reply (256–8192, default 2048). Raise this if the JSON is truncated on very detailed images. | | extra_config | STRING (optional, multiline) | Extra generation notes (seed, steps, cfg, sampler, …). They are given to Grok and also appended to t2i_prompt. |

Image size

Every image is sent with a longest side of 512px. Testing showed that 768px and 1024px made Grok merge two overlapping people into one body. 512px kept them separate. The prompt also tells Grok to count people first and to leave each body part with the person it belongs to.

Outputs

| Output | Content | |--------|---------| | description | Factual, detailed description of the reference image | | t2i_prompt | Positive prompt written for t2i_model, with extra_config appended when set | | full_json | Full JSON from Grok (description, t2i_prompt, notes) for debugging |

Publishing

Registry package id: grok-image-prompt. Publisher id: brunopreima. Version: the version field in pyproject.toml. A published version cannot be edited.

1. Create the publisher brunopreima at registry.comfy.org if it does not exist yet.
2. Create a registry API key for that publisher. This key is only for publishing nodes.
3. In this GitHub repository, add the key as an Actions secret named REGISTRY_ACCESS_TOKEN.
4. Push a pyproject.toml change to main, or run the Publish to Comfy registry workflow by hand. .github/workflows/publish.yml publishes the version in pyproject.toml. Bump that version before every release.