simple-chatbot-imaging

Standalone image generation package with pluggable providers, opt-in fallback orchestration, and a true async API.

Installation

uv add simple-chatbot-imaging            # core + OpenRouter provider
uv add "simple-chatbot-imaging[huggingface]"  # + Hugging Face provider
uv add "simple-chatbot-imaging[all]"      # everything

The fallback extra enables fallback orchestration only; install the provider extras you want in the chain yourself (e.g. [huggingface]).

Quick start

from simple_chatbot_imaging import create_image_generator

gen = create_image_generator("openrouter", media_path="media")
path = await gen.generate_image_async("a neon cyberpunk city at night")

Synchronous use:

path = gen.generate_image("a neon cyberpunk city at night")

Provider configuration file

Provider defaults live in src/simple_chatbot_imaging/providers.json. You can edit that file to change API endpoints, model IDs, or add your own providers without changing library code.

{
  "openrouter": {
    "kwargs": {
      "base_url": "https://openrouter.ai/api/v1/images",
      "model": "meta/muse-image",
      "api_key_env": "OPENROUTER_API_KEY"
    }
  },
  "custom_provider": {
    "factory": "your_package.providers:YourCustomProvider",
    "kwargs": {
      "base_url": "https://example.com/api/v1/images",
      "api_key_env": "CUSTOM_API_KEY"
    }
  }
}

You can also pass a custom config path explicitly:

from simple_chatbot_imaging import create_image_generator

gen = create_image_generator(
    "openrouter",
    config_path="./providers.json",
    base_url="https://example.com/api/v1/images",
)

OpenRouter (openrouter)

• Uses the OpenRouter images/generations API via httpx (native async).
• Requires the OPENROUTER_API_KEY environment variable.
• Options: model (default meta/muse-image), base_url, api_key_env, request_timeout_seconds.

Hugging Face (huggingface, extra: huggingface)

• Runs a Gradio Space (ZeroGPU) via gradio-client.
• Uses HUGGINGFACE_ACCESS_TOKEN if set.
• Options: space_id (default hugging-apps/qwen-image-2-1), hf_token_env.

Fallback (opt-in)

Fallback is never implicit. Build it explicitly with a caller-defined chain:

from simple_chatbot_imaging import FallbackImageGenerator, create_image_generator

providers = [create_image_generator("openrouter"), create_image_generator("huggingface")]
gen = FallbackImageGenerator(generators=providers)

Each provider runs its full lifecycle (retries, state, output movement); the fallback only advances to the next provider on failure.

API

• BaseImageGenerator — abstract provider base; prompt validation, retries with backoff, timeouts, state tracking, output movement.
• generate_image(...) — synchronous entry point.
• generate_image_async(...) — true async entry point (native async providers).
• ImageGenerationError(retryable=...) — permanent errors (bad key, no credits, 403/404) are not retried.
• ImageGenerationState — IDLE, GENERATING, ERROR, SUCCESS.
• create_image_generator(provider, **kwargs) — factory; raises a clear error when an optional provider's extra is not installed.
• register_provider(name, factory) — plugin hook.

Environment variables