Better-Gemini

ComfyUI Better Gemini

ComfyUI V3 nodes for generating images and text with Google Gemini and xAI Grok, plus image generation and editing through OpenRouter.

This repo provides three nodes:

• Better Gemini for Gemini image and text generation
• Better Grok for Grok image generation, image editing, and text chat
• Better OpenRouter for OpenRouter image generation and reference-guided editing

Install

1. Clone into your ComfyUI custom_nodes directory:
   • cd /path/to/ComfyUI/custom_nodes
   • git clone https://github.com/<you>/ComfyUI-Better-Gemini.git
2. Install Python deps with uv:
   • uv sync
   • uv pip install --python /path/to/ComfyUI/python/bin/python -e ./ComfyUI-Better-Gemini
3. Set API keys as needed:
   • export GOOGLE_API_KEY="..." or export GEMINI_API_KEY="..."
   • export XAI_API_KEY="..." (optional for Grok Imagine after OAuth login)
   • export OPENROUTER_API_KEY="..."
4. Restart ComfyUI.

Nodes

Better Gemini

• Inputs: prompt, model, response_modalities (IMAGE, IMAGE+TEXT, TEXT), optional prompt images, aspect ratio, resolution or width+height, temperature, top_p, top_k, max tokens, thinking controls, seed, optional output caching
• Outputs: IMAGE, STRING
• Use it when you want one node that can handle both Gemini image models and Gemini text-only models

Better Grok

• Inputs: prompt, model, authentication mode (auto, oauth, api_key), response_modalities (IMAGE, IMAGE+TEXT, TEXT), reasoning effort (none, low, medium, high), optional prompt images, aspect ratio, resolution, n, optional output caching
• Outputs: IMAGE, STRING
• Use it when you want Grok image generation, image editing, or a text-only Grok call from the same node

xAI OAuth Login

Better Grok can use xAI device authorization for Imagine image generation and editing without storing an API key in the workflow:

1. Add or open a Better Grok node with ComfyUI's V3 node renderer.
2. Click Login in the node header.
3. Open the xAI verification page, sign in, enter the displayed code if requested, and approve access.
4. Leave ComfyUI running while the node polls for approval. The button changes to Logout when authorization completes, and the initiating node switches to auth_mode=oauth.

Authentication modes:

• auto preserves existing workflows: an inline API key wins, then a saved OAuth login is used for Imagine requests, then XAI_API_KEY remains the fallback.
• oauth requires a completed node-header login and never uses the API-key field.
• api_key uses the inline key or XAI_API_KEY and ignores saved OAuth credentials.

OAuth credentials are stored server-side under ComfyUI's protected system-user directory (user/__better_gemini/xai_oauth.json), not in workflows or browser storage. The directory and token file use private permissions where the platform supports them. Each workflow run checks token expiry asynchronously; near-expiry credentials refresh in the background, while an already expired token is refreshed before the xAI request is sent. Logout cancels pending login/refresh work and deletes the stored credentials.

The OAuth client follows xAI's Grok-compatible device endpoints at auth.x.ai and sends the resulting bearer only to xAI's public Imagine image endpoints. Better Grok TEXT mode continues to require an API key because xAI OAuth chat traffic uses a separate CLI-proxy wire contract. This OAuth surface is not documented as a stable public xAI integration API and may require maintenance if xAI changes it.

xAI Rate Limiting

All Better Grok calls in one ComfyUI process share a thread-safe, per-model request coordinator. By default it starts no more than 5 requests per second and allows no more than 5 logical requests for the same model in flight. Starts are evenly spaced instead of released in one burst. The coordinator retains one minute of attempt timestamps for accounting and removes active entries in a finally block af