pixbridge

Multi-provider AI image generation library supporting Gemini, OpenAI, and xAI.

Features

• Unified ImageClient API across providers
• Image generation from structured YAML prompts
• Style transfer (Gemini, OpenAI)
• Reference image support for identity consistency (Gemini, OpenAI)
• Consistency checking (generate N images from the same prompt for comparison)
• Image integrity checks (transparency, corruption, truncation)
• Thread-safe usage logging (JSONL)

Setup

uv sync

CLI

pixbridge providers                          # List available providers
pixbridge generate prompt.yaml --model gemini-3-pro-image-preview
pixbridge style-transfer img.png --style anime-dark --model gemini-3-pro-image-preview
pixbridge consistency-check anime-dark -n 5 --model gemini-3-pro-image-preview
pixbridge check output/                      # Check image integrity

# --model is required on generate / style-transfer / consistency-check —
# there is no default model.

Usage as library

from pixbridge.client import ImageClient
from pixbridge.models import ImagePrompt, GenerationNotes

client = ImageClient(provider="gemini")
prompt = ImagePrompt(
    full_prompt="A mountain landscape at sunset",
    generation_notes=GenerationNotes(
        aspect_ratio="16:9",
        key_requirements=["photorealistic"],
    ),
)
path = client.generate_image(
    prompt, output_dir="output", model="gemini-3-pro-image-preview"
)  # model is required — there is no default

Providers

For OpenAI, style transfer and reference images run through the image edits endpoint (a single reference image performs style transfer; multiple references compose) — there is no dedicated "style" parameter.

Any model can be selected at runtime with --model. The CLI also accepts size presets 720p, 1080p, 2160p, or a raw WxH string (resolved per-provider). OpenAI (gpt-image-2) validates sizes by rule — any WxH where both dimensions are divisible by 16, the ratio is within [1:3, 3:1], and max(W, H) ≤ 3840, with 655,360–8,294,400 total pixels — so true 9:16 (1152x2048) and 16:9 (2048x1152) work; 1024x1024, 1024x1536, 1536x1024, 2560x1440, 3840x2160 are recommended values surfaced for autocompletion.

Provider capability surface

Each provider exposes a uniform capability surface via provider.capabilities (a ProviderCapabilities), so callers can reason about size rules without branching on the provider name:

To read a provider's capabilities without instantiating it or supplying credentials (e.g. for offline size resolution), use the registry:

from pixbridge.providers import get_capabilities

caps = get_capabilities("openai")   # also "gemini", "xai", "vertex"; None if unknown
caps.validate_size("1152x2048")     # passes; raises ValueError on invalid sizes
caps.native_size(2048, 1152)        # -> "2048x1152"

get_capabilities("vertex") returns Gemini's surface (Vertex shares it) and never requires GOOGLE_CLOUD_PROJECT.

Style presets

Style-transfer presets are Markdown files looked up by name. Pass --style (or the style argument) as a preset name (anime-dark), a subdir-qualified name (anime/anime-dark), a path to a .md file, or raw prompt text.

The preset directory resolves in this order: an explicit ImageClient(style_presets_dir=...) / --styles-dir argument, then the PIXBRIDGE_STYLE_PRESETS_DIR environment variable, then prompts/style-transfer relative to the current working directory. When none of these contain the named preset, the value is treated as raw prompt text.

export PIXBRIDGE_STYLE_PRESETS_DIR=~/my-styles
pixbridge style-transfer img.png --style anime-dark
pixbridge style-transfer img.png --style anime-dark --styles-dir ./other-styles

client = ImageClient(provider="gemini", style_presets_dir="~/my-styles")

Model selection

There is no default model. A model must always be specified explicitly:

• CLI: pass --model <name> (e.g. --model gpt-image-2). Commands fail with --model is required if omitted.
• Library: pass model= to the ImageClient generation methods.

This is deliberate — model names change often, so the library does not ship a baked-in default that could silently go stale. A model string flows straight through to the provider SDK, except where a provider declares a supported_models allowlist (OpenAI: gpt-image-2, both GPT Image 2.5 aliases and their 2026-09-08 snapshots), which is validated locally before any API call.

Testing

just test

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development setup and PR guidelines. To report a security issue, see SECURITY.md.

License

Licensed under the Apache License 2.0. See the NOTICE file for attribution requirements.

GPT Image 2.5

Select gpt-image-2.5-flare for fast generation or gpt-image-2.5-sunburst for precise editing. Both accept low, medium, high, xhigh, max, and auto quality. The published -2026-09-08 snapshots are also supported. The library keeps its low quality default; no model is chosen automatically. GPT Image 2 continues to accept only low, medium, high, and auto. All three models share the custom-size rules above; resolutions above 2560×1440 are experimental. Quality controls rendering effort independently of dimensions; matching quality names do not guarantee matching per-image cost.

pixbridge generate prompt.yaml --provider openai --model gpt-image-2.5-flare --quality low
pixbridge generate prompt.yaml --provider openai --model gpt-image-2.5-sunburst --quality max --size 2048x1152

Source: OpenAI image generation documentation.