Generating image guide

Author: cescoffier

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/EndpointGeneration.java

@@ -0,0 +1,33 @@
+package io.quarkiverse.langchain4j.samples.images;
+
+import java.io.IOException;
+import java.net.URI;
+
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+
+@Path("/endpoint")
+public class EndpointGeneration {
+
+    @Inject
+    ImageGenerationAiService imageGenerationAiService;
+
+    @GET
+    @Path("/generate-image")
+    @Produces("image/png")
+    public byte[] generateImage() {
+        var image = imageGenerationAiService.generateImage("a rabbit in a space suit");
+        return readBytes(image.url());
+    }
+
+    private byte[] readBytes(URI url) {
+        try (var is = url.toURL().openStream()) {
+            return is.readAllBytes();
+        } catch (IOException e) {
+            throw new RuntimeException("Failed to read image from URL: " + url, e);
+        }
+    }
+
+}

docs/modules/ROOT/examples/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java

@@ -0,0 +1,21 @@
+// tag::head[]
+package io.quarkiverse.langchain4j.samples.images;
+
+import dev.langchain4j.data.image.Image;
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import io.quarkiverse.langchain4j.RegisterAiService;
+
+@RegisterAiService
+@SystemMessage("You are an AI that generates images from text prompts.")
+public interface ImageGenerationAiService {
+    // end::head[]
+
+    // tag::generation[]
+    @UserMessage("Generate an image of a {subject}.")
+    Image generateImage(String subject);
+    // end::generation[]
+
+    // tag::head[]
+}
+// end::head[]

docs/modules/ROOT/nav.adoc

@@ -18,6 +18,7 @@
 * xref:guide-csv.adoc[Index CSVs in a RAG pipeline]
 * xref:guide-web-search.adoc[Using Tavily Web Search]
 * xref:guide-passing-image.adoc[Passing Images to Models]
+* xref:guide-generating-image.adoc[Generating Images]
 // * xref:guide-agentic-patterns.adoc[Implementing Agentic patterns]
 // * xref:guide-structured-output.adoc[Returning structured data from a model]
 // * xref:guide-streamed-responses.adoc[Using function calling]

docs/modules/ROOT/pages/guide-generating-image.adoc

@@ -0,0 +1,73 @@
+= Generating Images
+
+include::./includes/attributes.adoc[]
+include::./includes/customization.adoc[]
+
+Text completions are powerful, but many modern AI use cases also demand image generation.
+With Quarkus LangChain4j’s Image model support, you can declare a service method that returns a `dev.langchain4j.data.image.Image` instance, letting your microservice request, receive, and expose AI‐generated visuals seamlessly.
+
+== Prerequisites
+
+* A Quarkus project with the `quarkus-langchain4j-openai` extension on the classpath (or another model provider that supports image models)
+* OpenAI (or another provider) API Key configured in `application.properties` or via `QUARKUS_LANGCHAIN4J_OPENAI_API_KEY`
+* An **Image Model** enabled (e.g. `dall-e-3` or `GPT-Image-1`) in your config:
+
+[source,properties]
+----
+quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
+quarkus.langchain4j.openai.image-model.model-name=dall-e-3 # This is the default model, but you can specify another one if needed
+----
+
+* Extended timeout for image generation, which can take longer than text completions. For example:
+
+[source,properties]
+----
+quarkus.langchain4j.openai.timeout=60s
+----
+
+== Step 1. Define the AI service
+
+Declare an AI Service interface to encapsulate image generation calls:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java[tags=head]
+----
+
+Here, `@RegisterAiService` creates the xref:ai-services.adoc[AI Service], and `@SystemMessage` supplies the global instruction for all methods in the service.
+
+== Step 2. Define the Generation Method
+
+Add a method annotated with `@UserMessage` that returns Image.
+Quarkus LangChain4j will call the configured image model and wrap the response in an `Image` object.
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/ImageGenerationAiService.java[tags=head;generation]
+----
+
+When invoked, Quarkus will substitute the subject into the prompt, send it to the AI model provider, and return the generated image (URL or Base64).
+
+NOTE: When using OpenAI image model, the returned `Image` object contains a URL to the generated image, which you can use to display or download the image.
+
+
+== Step 3. Expose an HTTP Endpoint
+
+Finally, expose a REST resource that injects and calls your AI Service:
+
+Use the `Image` data type for local or in-memory images:
+
+[source,java]
+----
+include::{examples-dir}/io/quarkiverse/langchain4j/samples/images/EndpointGeneration.java[]
+----
+
+== Conclusion
+
+You’ve now seen how to:
+1.	Register an image‐generation AI service (`@RegisterAiService`).
+2.	Declare a method returning `Image` with `@UserMessage`.
+3.	Expose a REST endpoint that returns the generated image back to clients.
+
+With this pattern, you can build rich, AI‐driven visual applications—everything from dynamic marketing graphics to in‐app illustration.
+