pixbridge
Multi-provider AI image generation library supporting Gemini, OpenAI, and xAI.
Features
- Unified
ImageClientAPI 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
| Provider | Models | Style Transfer | Reference Images |
|---|---|---|---|
| Gemini | gemini-3-pro-image-preview | yes | yes |
| OpenAI | gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst | yes | yes |
| xAI | grok-imagine-image | no | no |
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:
| Method | Returns | OpenAI | Gemini / Vertex | xAI |
|---|---|---|---|---|
validate_size(size) |
raises ValueError if invalid |
rule-based (÷16, ratio, max-dim) | must be 1K/2K |
no-op (unconstrained) |
recommended_sizes() |
list[str] for docs/autocomplete |
7 sizes incl. true 9:16/16:9 | ["1K", "2K"] |
[] |
aspect_to_size(ratio) |
str | None (named ratio → WxH) |
e.g. "9:16" → "1152x2048" |
None (ratio passed to API) |
None |
max_dim() |
int | None (px ceiling) |
3840 |
None |
None |
native_size(w, h) |
str | None (raw WxH → native size) |
validates + passes WxH through |
buckets to 1K/2K |
None |
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 requiredif omitted. - Library: pass
model=to theImageClientgeneration 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
Metadata
Release files for pixbridge 0.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pixbridge-0.2.4.tar.gz | 69.3 kB | Without provenance | Details for pixbridge-0.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pixbridge-0.2.4-py3-none-any.whl | Python 3 | none | any | Details for pixbridge-0.2.4-py3-none-any.whl |
Total release size: 111.8 kB
Release files / pixbridge-0.2.4.tar.gz
| Download URL | pixbridge-0.2.4.tar.gz |
|---|---|
| Size | 69.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71a26cedd2efe3e5c04cd80b03e3c452d3a8b7f6e8edaacc6f861f53e44b81ce
|
|
BLAKE2b-256 checksum How to use checksums |
2332956787ad33ea639e06373be6ce3f2161d7122c56268f92f3d8dc38734073
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / pixbridge-0.2.4-py3-none-any.whl
| Download URL | pixbridge-0.2.4-py3-none-any.whl |
|---|---|
| Size | 42.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
df50e975a8b4df569b9c6afd0175b56173d661cbc96dca9d4e68089f47267c10
|
|
BLAKE2b-256 checksum How to use checksums |
4bce3d44e39ac18bdf97a0fb8224d11c0e5e566df525ff78af2ac4764a26f890
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for pixbridge 0.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.