TrueGrowth/openspec/changes/add-local-image-provider/design.md

Context

The current image generation path already supports provider profiles, runtime model discovery, model bindings, and image adapters. The safest first local model integration is a provider profile for locally running OpenAI-compatible services.

Goals / Non-Goals

• Goals: support local /v1/models discovery, no-auth local calls, generic /v1/images/generations image requests, Model Center image model installation/application, and user-facing defaults for LocalAI-style runtimes.
• Non-Goals: ComfyUI, A1111/Forge native APIs, remote LAN exposure, direct execution of every downloaded model format, or hidden license acceptance.

Decisions

• Represent local image services as openai-compatible provider profiles with authType: none.
• Keep the request schema as openai.image.basic-json so existing image adapter routing remains compatible.
• Treat optional fields such as negative_prompt, steps, cfg_scale, and seed as provider extensions in the JSON body.
• Store downloaded/imported image models in a lightweight local registry separate from AIGCPanel config.json model packages.
• Model Center can register official model metadata and local paths, but actual generation requires a reachable OpenAI-compatible local service that has loaded the model.

Risks / Trade-offs

• Some local runtimes use non-OpenAI APIs. They remain out of scope until a dedicated adapter is added.
• Local runtimes differ in supported parameters. Unsupported extension fields are expected to be ignored or rejected by the local service with a visible API error.
• Hugging Face model downloads may require large files, authentication, or license acknowledgement. The first implementation exposes official links and supports importing a local path instead of silently pretending all models can be downloaded through the app.