Skip to content

behzadsp/claude-code-image-gen

image-gen

Unverified

Generate 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.

FileKindSize
SKILL.mdskill md5.7 KB
scripts/generate.pyexecutablescript12.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())
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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 321kUpdated Claude CodeCodexVerifiedInstall