# How Lemon AI's Image Generation Utility Converts Text Prompts into Images

> Discover how Lemon AI's image generation utility transforms text prompts into images. Learn about the four-stage pipeline and the Gemini API integration.

- Repository: [hexdocom/lemonai](https://github.com/hexdocom/lemonai)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Lemon AI converts text prompts into images through a four-stage pipeline managed by the `TextToImageService` class, which constructs enhanced prompts, calls the Gemini 2.5 Flash Image Preview API, and returns formatted data URLs.**

The `hexdocom/lemonai` repository provides a robust text-to-image solution through its dedicated utility module. At the core of this image generation utility lies the `TextToImageService` class defined in [`src/utils/text_to_image.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/text_to_image.js), which orchestrates the entire conversion workflow from raw text to renderable image data.

## The TextToImageService Architecture

The image generation utility centers on a singleton service pattern exposed through `getTextToImageService()`. The `TextToImageService` class encapsulates four primary responsibilities: API credential management, prompt engineering, HTTP communication with Google's generative AI infrastructure, and response normalization. This design allows Lemon AI to maintain stateful configuration while providing a clean interface for both direct text-to-image calls and advanced LLM-assisted portrait generation.

## Step-by-Step Conversion Process

### 1. Service Initialization and API Key Verification

Before processing any text prompts, the service must validate its operational readiness. The `initialize()` method checks for the presence of `process.env.GEMINI_API_KEY` and sets an internal readiness flag. This verification occurs in [`src/utils/text_to_image.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/text_to_image.js) lines 22-33, ensuring that all subsequent API calls have proper authentication credentials before attempting network requests.

### 2. Prompt Construction and Enhancement

Raw user input undergoes significant transformation through the `generateImage(prompt, options)` method. This function merges user-provided parameters with default configurations for style, aspect ratio, quality, and size. The `buildFullPrompt()` helper then constructs an enriched instruction string that appends style cues, quality descriptors, and explicit "high-quality" directives to the original prompt. This prompt engineering occurs in lines 98-125 of the source file, significantly improving the visual quality of the generated output by providing the Gemini model with detailed artistic direction.

### 3. Gemini API Request Execution

The `makeApiRequest(requestBody)` method handles the actual network communication. It POSTs the constructed prompt to `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image-preview:generateContent`, including the API key in the `x-goog-api-key` header. The implementation uses a 5-minute timeout to accommodate the generation latency of the image model. Error handling in lines 56-81 normalizes network failures, API errors, and missing responses into descriptive exception messages that aid debugging without exposing sensitive credential information.

### 4. Response Parsing and Image Formatting

Upon successful API completion, `generateImage` extracts the `inlineData` (or `inline_data`) field containing the base64-encoded image payload. The `parseImageResponse(imageData)` method in lines 254-274 converts this payload into a standard data URL format (`data:<mime>;base64,...`) and returns a structured metadata object. The final result object includes the `imageUrl` (data URL), the full enhanced prompt, original prompt, generation metadata (model version, style, aspect ratio, MIME type), and a timestamp, providing comprehensive provenance for the generated asset.

## LLM-Powered Portrait Generation

Beyond standard text-to-image conversion, Lemon AI offers specialized character portrait capabilities through `generateAgentPortrait`. This advanced workflow first invokes `generateCharacterPortraitDescription()`, which utilizes the generic LLM layer ([`src/completion/llm.one.js`](https://github.com/hexdocom/lemonai/blob/main/src/completion/llm.one.js)) to generate detailed textual character descriptions based on agent names and personality profiles. The `buildLLMBasedPortraitPrompt()` function then transforms this description into the final image prompt, which flows through the standard Gemini pipeline. This two-step approach leverages large language model creativity to produce highly specific, contextually appropriate character imagery while maintaining the core efficiency of the `TextToImageService`.

## Implementation Examples

### Basic Text-to-Image Generation

The following example demonstrates the standard workflow for converting text prompts into images:

```javascript
const { getTextToImageService } = require('@src/utils/text_to_image');

async function simpleDemo() {
  const txt2img = getTextToImageService();
  const result = await txt2img.generateImage('a futuristic city skyline at sunset', {
    style: 'cinematic',
    aspectRatio: '16:9',
    quality: 'high',
    size: 'large'
  });
  console.log('Image data URL:', result.data.imageUrl);
}
simpleDemo();

```

### Generating Agent Portraits with LLM Assistance

For creating character-specific imagery with enhanced descriptive detail:

```javascript
const { getTextToImageService } = require('@src/utils/text_to_image');

async function portraitDemo() {
  const txt2img = getTextToImageService();
  const portrait = await txt2img.generateAgentPortrait(
    'CodeMaster',                               // agent name
    'A senior developer who loves clean code', // agent description
    'conv-12345',                               // conversation id for model lookup
    {
      portraitType: 'realistic',
      composition: 'full-body',
      background: 'office',
      mood: 'professional',
      useLLMDescription: true
    }
  );
  console.log('Portrait URL:', portrait.data.imageUrl);
}
portraitDemo();

```

## Summary

- **Core Architecture**: The image generation utility relies on the `TextToImageService` class in [`src/utils/text_to_image.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/text_to_image.js) to manage the entire conversion pipeline.
- **Prompt Engineering**: User text undergoes enhancement through `buildFullPrompt()`, which adds style, quality, and composition directives before API submission.
- **API Integration**: The service communicates with Google's Gemini 2.5 Flash Image Preview endpoint, handling authentication via `x-goog-api-key` headers and 5-minute timeouts.
- **Response Processing**: Base64-encoded image data is extracted and converted to standard data URLs through `parseImageResponse()`, with comprehensive metadata preservation.
- **Advanced Features**: The `generateAgentPortrait` method leverages the LLM layer ([`llm.one.js`](https://github.com/hexdocom/lemonai/blob/main/llm.one.js)) to create detailed character descriptions before image generation.

## Frequently Asked Questions

### What API does Lemon AI use for image generation?

Lemon AI utilizes Google's **Gemini 2.5 Flash Image Preview** model through the `generativelanguage.googleapis.com` endpoint. The service authenticates using an API key stored in the `GEMINI_API_KEY` environment variable, passed in the `x-goog-api-key` header with each request.

### How does Lemon AI handle errors during image generation?

The `TextToImageService` implements comprehensive error handling in the `makeApiRequest` method. It catches network timeouts, API authentication failures, and malformed responses, normalizing them into descriptive error messages. If the API returns an empty response or the expected `inlineData` field is missing, the service throws specific exceptions to aid debugging without exposing sensitive credential details.

### Can Lemon AI generate specific character portraits?

Yes, through the `generateAgentPortrait` method, Lemon AI can create detailed character images. This feature first uses the LLM completion layer ([`llm.one.js`](https://github.com/hexdocom/lemonai/blob/main/llm.one.js)) to generate rich textual descriptions based on agent names and personality profiles, then feeds this enhanced description into the standard image generation pipeline. This two-step process produces highly specific, contextually appropriate portraits while reusing the core `TextToImageService` infrastructure.

### What file contains the core image generation logic?

The primary implementation resides in **[`src/utils/text_to_image.js`](https://github.com/hexdocom/lemonai/blob/main/src/utils/text_to_image.js)**, which exports the `TextToImageService` class and `getTextToImageService` factory function. This module handles service initialization, prompt construction, API communication with Google's Gemini endpoint, and response parsing. For LLM-assisted portrait generation, the service also interacts with [`src/completion/llm.one.js`](https://github.com/hexdocom/lemonai/blob/main/src/completion/llm.one.js) to generate character descriptions.