Crate ryu_image 

Image-generation modality primitive: generate(prompt) -> image behind a swappable engine seam.

One dispatch (generate) over two engines:

• local stable-diffusion.cpp (default): forwarded to the resident sd-server’s OpenAI-compatible /v1/images/generations (a thin HTTP proxy), lazily started via the host’s ImageHost::start_local_engine.
• cloud (openrouter / replicate / fal, selected by a "provider" field in the body): routed through the Gateway’s /v1/images/generations with the per-attribute x-ryu-slot-image-provider header, so the full firewall/budget/metering pipeline governs the call.

Per the Core-vs-Gateway rule the dispatch is a Core concern (it decides what runs — which media engine renders the pixels); this crate owns the reusable image-gen abstraction + routing, while the host couplings it cannot own — the local sd-server base-url, the Gateway url/token, and lazy-starting the sd.cpp sidecar — are injected via the narrow ImageHost trait. The crate has ZERO dependency on apps/core (mirrors the ryu-stt seam).

The generic media proxy/gateway-forward helpers (proxy, forward_to_gateway, cloud_provider, media_client) are pub so the sibling video data path (which stays in Core, out of this crate’s image scope) reuses the same routing mechanics rather than duplicating them.

Constants

CLOUD_PROVIDERS

Cloud media providers routed through the Gateway (governed, metered) rather than the local stable-diffusion.cpp engine. A request selects one via a "provider" field in the body; anything else (or absent) uses the local engine, so the default local path is unchanged.

Traits

ImageHost

Narrow host seam for image generation: the couplings the crate cannot own because they read Core config/sidecar state (the local sd-server base-url, the Gateway url + token, and lazy-starting the off-by-default sd.cpp sidecar). Core implements this in apps/core/src/image_host.rs.

Functions

cloud_provider

Returns the normalized cloud provider id when the body selects one, else None (⇒ the local sd-server path).

forward_to_gateway

Forward a media request to the Gateway, routing to provider via the per-request slot header for modality (image/video). The Gateway runs the full firewall/budget/metering pipeline and returns a normalized body.

generate

Text-to-image dispatch: validate prompt, default a single-image count, then route to the Gateway (cloud provider selected) or the local sd-server engine. This is the reusable image-gen entry; Core’s POST /api/images/generate handler is a thin wrapper over it, injecting ImageHost.

media_client

Diffusion on CPU can take minutes; use a generous client timeout independent of the short-lived shared ServerState client.

proxy

Forward a JSON body to a media-engine endpoint ({base_url}{endpoint}) and pass the response through. base_url is the local sd-server base (ImageHost::sd_base_url).

Type Aliases

MediaResponse

A media data-path response: the HTTP status code and the JSON body. Core maps the u16 back to an axum StatusCode and wraps the body in Json, so the wire behavior is byte-identical to the pre-extraction handlers.