tessl/maven-dev-langchain4j--langchain4j-open-ai

LangChain4j OpenAI Integration providing Java access to OpenAI APIs including chat models, embeddings, image generation, audio transcription, and moderation.

Overview

Eval results

Files

Image Models

Name: tessl/maven-dev-langchain4j--langchain4j-open-ai
Author: tessl

Image models generate artistic images from text descriptions using OpenAI's DALL-E technology. Both DALL-E 2 and DALL-E 3 are supported, with DALL-E 3 offering improved quality, better prompt following, and enhanced creative capabilities.

Generated images can be returned as URLs for immediate viewing or as base64-encoded data for direct integration. DALL-E 3 provides additional controls for artistic style and image quality.

Capabilities

OpenAiImageModel

Synchronous image generation model that creates images from text prompts. Supports generating single or multiple images per request.

public class OpenAiImageModel implements ImageModel {
    public static OpenAiImageModelBuilder builder();

    // Core generation methods
    public Response<Image> generate(String prompt);
    public Response<List<Image>> generate(String prompt, int n);

    // Model information
    public String modelName();
}

OpenAiImageModelBuilder

Builder for configuring OpenAiImageModel instances with authentication, model selection, and image generation parameters.

public static class OpenAiImageModelBuilder {
    // Core configuration
    public OpenAiImageModelBuilder modelName(String modelName);
    public OpenAiImageModelBuilder modelName(OpenAiImageModelName modelName);
    public OpenAiImageModelBuilder baseUrl(String baseUrl);
    public OpenAiImageModelBuilder apiKey(String apiKey);
    public OpenAiImageModelBuilder organizationId(String organizationId);
    public OpenAiImageModelBuilder projectId(String projectId);

    // Image generation parameters
    public OpenAiImageModelBuilder size(String size);
    public OpenAiImageModelBuilder quality(String quality);
    public OpenAiImageModelBuilder style(String style);
    public OpenAiImageModelBuilder user(String user);
    public OpenAiImageModelBuilder responseFormat(String responseFormat);

    // HTTP configuration
    public OpenAiImageModelBuilder httpClientBuilder(HttpClientBuilder httpClientBuilder);
    public OpenAiImageModelBuilder timeout(Duration timeout);
    public OpenAiImageModelBuilder maxRetries(Integer maxRetries);
    public OpenAiImageModelBuilder customHeaders(Map<String, String> customHeaders);
    public OpenAiImageModelBuilder customHeaders(Supplier<Map<String, String>> customHeadersSupplier);
    public OpenAiImageModelBuilder customQueryParams(Map<String, String> customQueryParams);

    // Logging
    public OpenAiImageModelBuilder logRequests(Boolean logRequests);
    public OpenAiImageModelBuilder logResponses(Boolean logResponses);
    public OpenAiImageModelBuilder logger(Logger logger);

    // Build
    public OpenAiImageModel build();
}

Basic Usage Example

import dev.langchain4j.model.openai.OpenAiImageModel;
import dev.langchain4j.model.openai.OpenAiImageModelName;
import dev.langchain4j.data.image.Image;
import dev.langchain4j.model.output.Response;
import java.net.URI;

// Create image model (DALL-E 3)
OpenAiImageModel model = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_3)
    .size("1024x1024")
    .quality("standard")
    .style("vivid")
    .build();

// Generate single image
String prompt = "A serene Japanese garden with cherry blossoms, koi pond, and traditional architecture";
Response<Image> response = model.generate(prompt);

Image image = response.content();
System.out.println("Image URL: " + image.url());
System.out.println("Revised prompt: " + image.revisedPrompt());

// Download and display or save the image
URI imageUri = image.url();
// Use imageUri to download and process the image

Multiple Images Example (DALL-E 2)

// DALL-E 2 supports generating multiple images
OpenAiImageModel dalle2Model = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_2)
    .size("512x512")
    .build();

// Generate multiple variations
String prompt = "A cute robot playing with a puppy in a park";
Response<List<Image>> response = dalle2Model.generate(prompt, 4);

List<Image> images = response.content();
System.out.println("Generated " + images.size() + " images");

for (int i = 0; i < images.size(); i++) {
    Image img = images.get(i);
    System.out.println("Image " + (i + 1) + ": " + img.url());
    // Process or display each image
}

Base64 Format Example

import java.util.Base64;
import java.nio.file.Files;
import java.nio.file.Paths;

// Configure for base64 response
OpenAiImageModel model = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_3)
    .size("1024x1024")
    .responseFormat("b64_json")  // Get base64 instead of URL
    .build();

String prompt = "A futuristic city skyline at sunset with flying cars";
Response<Image> response = model.generate(prompt);

Image image = response.content();
String base64Data = image.base64Data();

// Decode and save to file
byte[] imageBytes = Base64.getDecoder().decode(base64Data);
Files.write(Paths.get("generated_image.png"), imageBytes);

System.out.println("Image saved to generated_image.png");

Quality and Style Control (DALL-E 3)

// High quality, natural style
OpenAiImageModel naturalModel = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_3)
    .size("1024x1792")  // Portrait orientation
    .quality("hd")      // High definition
    .style("natural")   // Natural, realistic style
    .build();

Response<Image> naturalImage = naturalModel.generate(
    "A professional photograph of a mountain landscape at golden hour"
);

// Vivid, dramatic style
OpenAiImageModel vividModel = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_3)
    .size("1792x1024")  // Landscape orientation
    .quality("hd")
    .style("vivid")     // Hyper-real, dramatic style
    .build();

Response<Image> vividImage = vividModel.generate(
    "A vibrant abstract painting with bold colors and dynamic shapes"
);

Advanced Configuration Example

import java.time.Duration;

OpenAiImageModel advancedModel = OpenAiImageModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiImageModelName.DALL_E_3)
    .size("1024x1024")
    .quality("hd")
    .style("vivid")
    .timeout(Duration.ofMinutes(5))  // Image generation can take time
    .maxRetries(3)
    .user("user-123")  // Track usage by user
    .logRequests(true)
    .logResponses(true)
    .build();

String detailedPrompt = """
    A detailed digital illustration of a steampunk-inspired mechanical owl
    perched on a brass gear, with intricate clockwork visible through
    transparent sections, warm golden lighting, Victorian aesthetic
    """;

Response<Image> response = advancedModel.generate(detailedPrompt);
System.out.println("Generated image: " + response.content().url());
System.out.println("AI revised prompt to: " + response.content().revisedPrompt());

Error Handling Example

try {
    OpenAiImageModel model = OpenAiImageModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName(OpenAiImageModelName.DALL_E_3)
        .timeout(Duration.ofMinutes(2))
        .build();

    Response<Image> response = model.generate("A beautiful sunset");
    Image image = response.content();

    if (image.url() != null) {
        System.out.println("Success! Image URL: " + image.url());
    }
} catch (Exception e) {
    System.err.println("Image generation failed: " + e.getMessage());
    // Handle content policy violations, rate limits, etc.
}

Model Names

public enum OpenAiImageModelName {
    DALL_E_2("dall-e-2"),
    DALL_E_3("dall-e-3");

    public String toString();
}

Model Comparison

Feature	DALL-E 2	DALL-E 3
Image Quality	Good	Excellent
Prompt Following	Good	Superior
Multiple Images	Yes (up to 10)	No (1 per request)
Sizes	256x256, 512x512, 1024x1024	1024x1024, 1024x1792, 1792x1024
Quality Levels	Standard only	Standard, HD
Style Control	No	Yes (natural, vivid)
Cost	Lower	Higher
Generation Speed	Faster	Slower

Types

Image

public class Image {
    public URI url();
    public String base64Data();
    public String revisedPrompt();

    public static Image from(URI url);
    public static Image from(String base64Data);
}

ImageModel Interface

public interface ImageModel {
    Response<Image> generate(String prompt);
}

Response

public class Response<T> {
    public T content();
    public TokenUsage tokenUsage();
    public FinishReason finishReason();
}

Configuration Options

Size

Image dimensions in pixels:

DALL-E 2:

"256x256": Small, fast, low cost
"512x512": Medium size
"1024x1024": Square, high resolution (default)

DALL-E 3:

"1024x1024": Square format (default)
"1024x1792": Portrait orientation
"1792x1024": Landscape orientation

Quality

Image quality level (DALL-E 3 only):

"standard": Standard quality, faster, lower cost (default)
"hd": High definition, enhanced detail, higher cost

Style

Artistic style (DALL-E 3 only):

"vivid": Hyper-real and dramatic (default)
"natural": More natural, less dramatic, photorealistic

Response Format

Format for returned images:

"url": Return URLs to images (default, expires after 1 hour)
"b64_json": Return base64-encoded image data

User Identifier

Optional string to track end-users:

Helps OpenAI monitor and detect abuse
Useful for multi-tenant applications

Timeout

Maximum time to wait for image generation:

Default varies by HTTP client
Image generation can take 10-60 seconds
Recommended: 2-5 minutes for HD images

Max Retries

Number of retry attempts on failure:

Default: 2
Automatic retry on transient failures
Exponential backoff between retries

Best Practices

Writing Effective Prompts

Be Specific:

// Vague
model.generate("A dog");

// Specific
model.generate("A golden retriever puppy playing in autumn leaves, natural lighting, soft focus background");

Include Style Details:

String prompt = "A coffee cup, watercolor painting style, warm colors, minimalist composition";
Response<Image> response = model.generate(prompt);

Specify Composition:

String prompt = "A close-up portrait of an elderly man with a wise expression, dramatic side lighting, shallow depth of field";
Response<Image> response = model.generate(prompt);

Choosing Model and Settings

Use DALL-E 2 when:

Budget is limited
Need multiple variations quickly
Standard quality is sufficient
Want to generate many options to choose from

Use DALL-E 3 when:

Need highest quality
Prompt following accuracy is critical
Want creative, artistic results
Budget allows higher costs

Use HD quality when:

Need maximum detail
Images will be printed or displayed large
Fine details are important
Budget allows

Use Standard quality when:

Budget is a concern
Images are for digital/web use only
Fast generation is preferred

Content Policy Compliance

OpenAI's content policy prohibits:

Violent or hateful imagery
Adult or sexual content
Illegal activities
Public figures (without permission)
Copyrighted characters or styles

// This will likely be rejected
try {
    Response<Image> response = model.generate("violent scene...");
} catch (Exception e) {
    // Handle content policy violation
    System.err.println("Content policy violation: " + e.getMessage());
}

Handling Revised Prompts

DALL-E 3 may revise prompts for safety or clarity:

String originalPrompt = "A robot";
Response<Image> response = model.generate(originalPrompt);

String revisedPrompt = response.content().revisedPrompt();
if (!originalPrompt.equals(revisedPrompt)) {
    System.out.println("OpenAI revised the prompt:");
    System.out.println("Original: " + originalPrompt);
    System.out.println("Revised: " + revisedPrompt);
}

Caching and Storage

URLs expire after 1 hour:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public void downloadAndSaveImage(Image image, String filename) throws Exception {
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(image.url())
        .build();

    HttpResponse<byte[]> response = client.send(
        request,
        HttpResponse.BodyHandlers.ofByteArray()
    );

    Files.write(Paths.get(filename), response.body());
}

// Use immediately after generation
Response<Image> response = model.generate(prompt);
downloadAndSaveImage(response.content(), "image.png");

Batch Generation

DALL-E 2 supports multiple images per request:

// Generate variations efficiently
OpenAiImageModel model = OpenAiImageModel.builder()
    .apiKey(apiKey)
    .modelName(OpenAiImageModelName.DALL_E_2)
    .build();

// Get 4 variations in one request
Response<List<Image>> response = model.generate("A logo for a tech startup", 4);

// Pick the best one
List<Image> images = response.content();
for (int i = 0; i < images.size(); i++) {
    System.out.println("Option " + (i + 1) + ": " + images.get(i).url());
}

Integration with Applications

public class ImageGenerationService {
    private final OpenAiImageModel model;

    public ImageGenerationService(String apiKey) {
        this.model = OpenAiImageModel.builder()
            .apiKey(apiKey)
            .modelName(OpenAiImageModelName.DALL_E_3)
            .quality("hd")
            .timeout(Duration.ofMinutes(3))
            .build();
    }

    public String generateAndSave(String prompt, String outputPath) {
        try {
            Response<Image> response = model.generate(prompt);
            Image image = response.content();

            // Download and save
            downloadImage(image.url(), outputPath);

            return image.revisedPrompt();
        } catch (Exception e) {
            throw new RuntimeException("Image generation failed", e);
        }
    }

    private void downloadImage(URI url, String path) throws Exception {
        // Implementation to download and save
    }
}

Common Use Cases

Marketing Materials

Generate images for:

Social media posts
Blog illustrations
Product mockups
Advertisement concepts

Creative Projects

Create artwork for:

Game assets (concept art)
Book illustrations
Album covers
Design inspiration

Prototyping

Quick visual prototypes:

UI mockups
Product designs
Architecture concepts
Fashion designs

Content Creation

Generate unique images for:

Educational materials
Presentations
Documentation
Website graphics

Personalization

Dynamic image generation:

Custom avatars
Personalized greetings
User-specific visuals

Performance and Limits

Generation Time

DALL-E 2: ~10-30 seconds
DALL-E 3 Standard: ~20-40 seconds
DALL-E 3 HD: ~30-60 seconds

Rate Limits

Rate limits vary by account tier:

Free tier: Lower limits
Pay-as-you-go: Moderate limits
Increased limits available on request

Cost Considerations

Approximate costs (check current pricing):

DALL-E 2: Lower cost per image
DALL-E 3 Standard: Medium cost
DALL-E 3 HD: Higher cost
Larger sizes may cost more

Image Expiration

Generated image URLs expire after 1 hour
Download and store images if needed longer
Use base64 format for immediate storage

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-open-ai

docs

advanced-features.md

audio-transcription-models.md