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

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, 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 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) 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:

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:

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 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) 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) 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, 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 to generate character descriptions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}