Gemini 3 创建缓存

The cost model of an LLM API punishes you for repetition: every call re-bills the same long document sitting in the context. Context caching is the fix - Google keeps the expensive part server-side and charges a fraction to reuse it. Gemini3ContextCache is the "store the document" half of that trick. You feed it the long text, it creates a cached entry, and hands you back the cache's name so a whole family of subsequent calls can reference it cheaply.

The README claims roughly a 10x discount on cached input tokens, and the mechanics back that up: input tokens served from cache are billed at the cache rate instead of the full input rate. If your workflow re-asks questions against the same big context - a character bible, a spec, a style guide, a PDF's worth of instructions - this is the node that stops you paying full price for it on every single run.

How it works

The node POSTs your content_to_cache to Google's /v1beta/cachedContents endpoint with three parameters: the model, the content, and a TTL. The response is a full cache record - name, model, creation/update/expiry times, and usage metadata - which the node returns as cache_info JSON. The critical number is expireTime: when it passes, the cache is gone and you have to re-create it.

Two constraints that matter in practice: the cached content must be substantial (Google's floor for cacheable context is on the order of 2048 tokens - caching a short paragraph is a no-op, and the API says so), and the cache is tied to the model - create it against gemini-3-pro-preview and it only serves that model.

Inputs and outputs that matter

• content_to_cache - the long text you'll keep asking about. This is where the token floor applies.
• ttl_minutes - how long the cache lives, 5 to 1440 minutes, default 60. Each run of this node re-creates (and re-bills) the cache, so set the TTL to outlive your working session.
• cache_name - a label you choose (my_cache by default). Note this is the display name, not the server-generated name.

Outputs: cache_name (the server's full cache reference - this is the one to wire into Gemini3UseCachedContent), cache_info (the JSON record with expireTime), and status (a plain success/failure string).

Install

Standard for the pack. ComfyUI Manager (search "ComfyUI-Gemini-3") or:

cd ComfyUI/custom_nodes
git clone https://github.com/xuchenxu168/ComfyUI-Gemini-3
cd ComfyUI-Gemini-3
pip install -r requirements.txt

No model downloads. Google AI Studio key via api_key field, config.json, or GEMINI_API_KEY.

Common issues

• "缓存创建失败" / cache creation failed - the most likely culprit is content under the minimum token count. Caching exists for long contexts; short text gets rejected.
• Cache not found on the use side - the TTL expired, or you're using the label (cache_name input) where the server reference belongs. The output named cache_name carries the real cachedContents/... reference; use that.
• Re-created every run - ComfyUI re-executes this node each time it's in the active path, and each creation bills a fresh cache write. If you're iterating on prompts, bypass the cache node after the first good run so you stop paying for it.
• It's write-once, use-many - pair it with Gemini3UseCachedContent; on its own this node only stores, it never generates.