behzadsp/claude-code-image-gen
image-gen
UnverifiedGenerate images from text prompts through OpenAI (gpt-image-2.5), Google Gemini (gemini-3-pro-image), Higgsfield, Black Forest Labs FLUX, or any OpenAI-compatible endpoint such as xAI Grok or Recraft. Use when the user asks to generate, create, render, or make an image, hero image, illustration, logo concept, OG image, poster, thumbnail, or social card, when a project has placeholder images to replace, or when the user names an image model or asks which image providers are available.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
| scripts/generate.pyexecutable | script | 12.9 KB |
scripts/generate.py
View on GitHub#!/usr/bin/env python3
"""Multi-provider image generation. Python stdlib only, no dependencies.
Providers: openai, gemini, higgsfield, bfl, and `compat` for any
OpenAI-compatible image endpoint (xAI, Recraft, OpenRouter, fal, ...).
Usage:
generate.py --prompt "..." [--provider auto] [--model NAME] [--out FILE]
generate.py --list-models --provider openai
generate.py --selftest
"""
import argparse
import base64
import json
import os
import re
import sys
import time
import urllib.error
import urllib.request
TIMEOUT = 180
POLL_INTERVAL = 3
POLL_MAX = 300
# provider -> (env var(s) holding credentials, default model env var, hardcoded default)
PROVIDERS = {
"openai": (["OPENAI_API_KEY"], "OPENAI_IMAGE_MODEL", "gpt-image-2.5-sunburst"),
"gemini": (["GEMINI_API_KEY", "GOOGLE_API_KEY"], "GEMINI_IMAGE_MODEL", "gemini-3-pro-image-preview"),
"higgsfield": (["HF_API_KEY_ID", "HF_API_KEY_SECRET"], "HIGGSFIELD_IMAGE_MODEL", "soul/v2/standard"),
"bfl": (["BFL_API_KEY"], "BFL_IMAGE_MODEL", "flux-pro-1.1"),
"compat": (["COMPAT_API_KEY"], "COMPAT_IMAGE_MODEL", ""),
}
# OpenAI accepts only these sizes; anything else is snapped to the nearest.
OPENAI_SIZES = {"1:1": "1024x1024", "16:9": "1536x1024", "9:16": "1024x1536",
"4:3": "1536x1024", "3:4": "1024x1536", "3:2": "1536x1024", "2:3": "1024x1536"}
class GenError(Exception):
pass
def _post(url, payload, headers, timeout=TIMEOUT):
body = json.dumps(payload).encode()
hdrs = {"Content-Type": "application/json", **headers}
req = urllib.request.Request(url, data=body, headers=hdrs, method="POST")
try:
with urllib.request.urlopen(req, timeout=timeout) as r:
return json.loads(r.read())
except urllib.error.HTTPError as e:
raise GenError(f"HTTP {e.code} from {url}: {e.read()[:600].decode(errors='replace')}")
def _get(url, headers, timeout=TIMEOUT):
req = urllib.request.Request(url, headers=headers, method="GET")
try:
with urllib.request.urlopen(req, timeout=timeout) as r:
return json.loads(r.read())
except urllib.error.HTTPError as e:
raise GenError(f"HTTP {e.code} from {url}: {e.read()[:600].decode(errors='replace')}")
def _creds(provider):
"""Return credential values, reading ~/.zshrc as a fallback.
Non-interactive shells skip ~/.zshrc, so keys exported there are invisible
to this process even though they work in the user's terminal.
"""
names = PROVIDERS[provider][0]
out = []
for name in names:
val = os.environ.get(name)
if not val:
val = _from_zshrc(name)
if not val:
raise GenError(f"{name} not set (provider '{provider}'). Export it or add it to ~/.zshenv.")
out.append(val)
return out
def _from_zshrc(name):
path = os.path.expanduser("~/.zshrc")
try:
with open(path) as f:
text = f.read()
except OSError:
return None
m = re.search(rf'^\s*export\s+{re.escape(name)}=["\']?([^"\'\s]+)', text, re.M)
return m.group(1) if m else None
# --- response harvesting -----------------------------------------------------
# Provider response schemas differ and some are unverified, so pull the image
# out structurally rather than trusting one exact path.
B64_KEYS = ("b64_json", "data", "image_base64", "b64", "bytesBase64Encoded")
URL_RE = re.compile(r"https?://[^\s\"']+?\.(?:png|jpe?g|webp)(?:\?[^\s\"']*)?", re.I)
def harvest(obj):
"""Walk a response and return ('b64', str) or ('url', str). Raises if neither."""
found_b64 = _walk_b64(obj)
if found_b64:
return "b64", found_b64
blob = json.dumps(obj)
m = URL_RE.search(blob)
if m:
return "url", m.group(0)
for key in ("url", "sample", "image_url", "output"):
v = _walk_key(obj, key)
if isinstance(v, str) and v.startswith("http"):
return "url", v
raise GenError(f"no image found in response: {blob[:500]}")
def _walk_b64(obj):
if isinstance(obj, dict):
for k, v in obj.items():
if k in B64_KEYS and isinstance(v, str) and len(v) > 256 and not v.startswith("http"):
return v
r = _walk_b64(v)
if r:
return r
elif isinstance(obj, list):
for item in obj:
r = _walk_b64(item)
if r:
return r
return None
def _walk_key(obj, key):
if isinstance(obj, dict):
if key in obj:
return obj[key]
for v in obj.values():
r = _walk_key(v, key)
if r is not None:
return r
elif isinstance(obj, list):
for item in obj:
r = _walk_key(item, key)
if r is not None:
return r
return None
# --- payload builders (pure; covered by --selftest) --------------------------
def build_openai(prompt, model, aspect, extra):
p = {"model": model, "prompt": prompt, "n": 1,
"size": OPENAI_SIZES.get(aspect, "1024x1024")}
p.update(extra)
return p
def build_gemini(prompt, model, aspect, extra):
cfg = {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": aspect}}
cfg["imageConfig"].update(extra.pop("imageConfig", {}))
cfg.update(extra)
return {"contents": [{"parts": [{"text": prompt}]}], "generationConfig": cfg}
def build_higgsfield(prompt, model, aspect, extra):
p = {"prompt": prompt}
p.update(extra)
return p
def build_bfl(prompt, model, aspect, extra):
p = {"prompt": prompt, "aspect_ratio": aspect}
p.update(extra)
return p
# --- provider calls ----------------------------------------------------------
def call_openai(prompt, model, aspect, extra, base="https://api.openai.com/v1", key_env="openai"):
key = _creds(key_env)[0]
r = _post(f"{base}/images/generations", build_openai(prompt, model, aspect, extra),
{"Authorization": f"Bearer {key}"})
return harvest(r)
def call_gemini(prompt, model, aspect, extra):
key = _creds("gemini")[0]
url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent"
r = _post(url, build_gemini(prompt, model, aspect, extra), {"x-goog-api-key": key})
return harvest(r)
def call_higgsfield(prompt, model, aspect, extra):
kid, secret = _creds("higgsfield")
hdr = {"Authorization": f"Key {kid}:{secret}"}
r = _post(f"https://api.higgsfield.ai/{model.lstrip('/')}",
build_higgsfield(prompt, model, aspect, extra), hdr)
status_url = r.get("status_url") or f"https://api.higgsfield.ai/requests/{r.get('request_id')}/status"
return _poll(status_url, hdr)
def call_bfl(prompt, model, aspect, extra):
key = _creds("bfl")[0]
hdr = {"x-key": key}
r = _post(f"https://api.bfl.ai/v1/{model}", build_bfl(prompt, model, aspect, extra), hdr)
poll_url = r.get("polling_url")
if not poll_url:
return harvest(r)
return _poll(poll_url, hdr)
def _poll(url, headers):
"""Poll an async job until an image appears or it fails."""
deadline = time.time() + POLL_MAX
last = None
while time.time() < deadline:
last = _get(url, headers)
state = str(_walk_key(last, "status") or "").lower()
if state in ("failed", "error", "cancelled", "canceled", "content_moderated"):
raise GenError(f"job {state}: {json.dumps(last)[:400]}")
try:
return harvest(last)
except GenError:
pass # still running
time.sleep(POLL_INTERVAL)
raise GenError(f"timed out after {POLL_MAX}s, last response: {json.dumps(last)[:400]}")
DISPATCH = {
"openai": lambda p, m, a, e: call_openai(p, m, a, e),
"gemini": call_gemini,
"higgsfield": call_higgsfield,
"bfl": call_bfl,
"compat": lambda p, m, a, e: call_openai(
p, m, a, e,
base=os.environ.get("COMPAT_BASE_URL", "").rstrip("/") or _need_compat_base(),
key_env="compat"),
}
def _need_compat_base():
raise GenError("provider 'compat' requires COMPAT_BASE_URL (e.g. https://api.x.ai/v1)")
def pick_provider():
"""First provider whose credentials are all present."""
for name in ("openai", "gemini", "bfl", "higgsfield"):
try:
_creds(name)
return name
except GenError:
continue
raise GenError("no provider credentials found. Set OPENAI_API_KEY, GEMINI_API_KEY, "
"BFL_API_KEY, or HF_API_KEY_ID + HF_API_KEY_SECRET.")
def list_models(provider):
"""Live model list. Only openai and gemini expose a catalog endpoint."""
if provider == "openai":
key = _creds("openai")[0]
r = _get("https://api.openai.com/v1/models", {"Authorization": f"Bearer {key}"})
return sorted(m["id"] for m in r["data"]
if any(k in m["id"] for k in ("image", "dall")))
if provider == "gemini":
key = _creds("gemini")[0]
r = _get("https://generativelanguage.googleapis.com/v1beta/models", {"x-goog-api-key": key})
return sorted(m["name"].split("/")[-1] for m in r.get("models", [])
if "image" in m["name"])
raise GenError(f"provider '{provider}' has no model-list endpoint; see reference.md")
def save(kind, value, out):
if kind == "b64":
data = base64.b64decode(value)
else:
with urllib.request.urlopen(value, timeout=TIMEOUT) as r:
data = r.read()
os.makedirs(os.path.dirname(os.path.abspath(out)) or ".", exist_ok=True)
with open(out, "wb") as f:
f.write(data)
return len(data)
def selftest():
"""Offline checks: payload shape, size mapping, response harvesting."""
assert build_openai("x", "gpt-image-2.5-sunburst", "16:9", {})["size"] == "1536x1024"
assert build_openai("x", "m", "bogus", {})["size"] == "1024x1024"
assert build_openai("x", "m", "1:1", {"quality": "low"})["quality"] == "low"
g = build_gemini("x", "m", "9:16", {})
assert g["generationConfig"]["imageConfig"]["aspectRatio"] == "9:16"
assert g["contents"][0]["parts"][0]["text"] == "x"
assert g["generationConfig"]["responseModalities"] == ["IMAGE"]
assert build_higgsfield("x", "m", "1:1", {})["prompt"] == "x"
assert build_bfl("x", "m", "3:2", {})["aspect_ratio"] == "3:2"
# harvest: OpenAI shape (base64)
assert harvest({"data": [{"b64_json": "A" * 300}]}) == ("b64", "A" * 300)
# harvest: Gemini shape (nested inlineData)
assert harvest({"candidates": [{"content": {"parts": [
{"inlineData": {"mimeType": "image/png", "data": "B" * 300}}]}}]})[0] == "b64"
# harvest: BFL shape (url in result)
assert harvest({"result": {"sample": "https://x.test/a.png"}}) == ("url", "https://x.test/a.png")
# harvest: short b64-looking string is not an image
try:
harvest({"data": [{"b64_json": "short"}]})
raise AssertionError("expected GenError for short payload")
except GenError:
pass
# harvest: a url field with no file extension is still found
assert harvest({"output": {"url": "https://x.test/render?id=9"}})[0] == "url"
print("selftest ok")
def main():
ap = argparse.ArgumentParser(description="Generate an image from any configured provider.")
ap.add_argument("--prompt", "-p")
ap.add_argument("--provider", default="auto", help="auto|" + "|".join(PROVIDERS))
ap.add_argument("--model", "-m", help="overrides the provider default")
ap.add_argument("--aspect", "-a", default="1:1",
help="1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3")
ap.add_argument("--out", "-o", default=None)
ap.add_argument("--extra", default="{}",
help="JSON merged into the request body, for provider-specific options")
ap.add_argument("--list-models", action="store_true")
ap.add_argument("--selftest", action="store_true")
args = ap.parse_args()
if args.selftest:
selftest()
return 0
try:
provider = pick_provider() if args.provider == "auto" else args.provider
if provider not in PROVIDERS:
raise GenError(f"unknown provider '{provider}'. Known: {', '.join(PROVIDERS)}")
if args.list_models:
print("\n".join(list_models(provider)))
return 0
if not args.prompt:
raise GenError("--prompt is required")
_, model_env, model_default = PROVIDERS[provider]
model = args.model or os.environ.get(model_env) or model_default
if not model:
raise GenError(f"provider '{provider}' needs --model or ${model_env}")
extra = json.loads(args.extra)
out = args.out or f"./generated-images/{int(time.time())}-{provider}.png"
kind, value = DISPATCH[provider](args.prompt, model, args.aspect, extra)
size = save(kind, value, out)
print(json.dumps({"success": True, "filePath": os.path.abspath(out),
"provider": provider, "model": model, "bytes": size}))
return 0
except GenError as e:
print(json.dumps({"success": False, "error": str(e)}), file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |