Core Feature: Image Generation

Relevant source files

The following files were used as context for generating this wiki page:

• App.tsx
• services/hfService.ts
• types.ts
• README.md
• components/SettingsModal.tsx
• components/ImageComparison.tsx
• translations.ts

The core functionality of the Peinture application is generating images from text prompts using AI models hosted on Hugging Face. This system is designed to be a client-side-only experience, where the React application communicates directly with external AI service APIs. It supports multiple generation models, prompt enhancement, image upscaling, and local history management.

The entire generation process is initiated from the user interface, managed by the main App.tsx component, and executed through asynchronous calls defined in services/hfService.ts. The results are stored in the browser's localStorage, ensuring user privacy.

Architecture Overview

The image generation feature follows a simple client-service architecture. The React frontend acts as the user interface and state manager, while the hfService.ts module encapsulates all logic for communicating with external Hugging Face (HF) and Pollinations.ai APIs.

This diagram illustrates the high-level data flow from user input to a displayed image.

UI and State Management

The primary user interface and logic for image generation are managed within the App.tsx component. It holds the state for user inputs, loading status, and generated image history.

Sources: App.tsx

Key State Variables

State Variable	Type	Description
prompt	string	The user-provided text prompt for image generation.
model	ModelOption	The selected AI model ('z-image-turbo' or 'qwen-image-fast').
aspectRatio	AspectRatioOption	The desired aspect ratio for the output image.
seed	string	An optional seed for reproducible results.
enableHD	boolean	A flag to enable high-definition generation for the 'z-image-turbo' model.
isLoading	boolean	Tracks the loading state of the generation process.
currentImage	`GeneratedImage	null`
history	GeneratedImage[]	An array of previously generated images, persisted in localStorage.

Sources: App.tsx:75-84, App.tsx:102-109, types.ts:1-12

Generation Flow

The handleGenerate function orchestrates the image generation process. It is an async function triggered by the user clicking the "Generate" button.

The following flowchart details the logic within handleGenerate:

Backend Service Integration

All communication with external AI models is handled by the services/hfService.ts module. It provides abstracted functions to generate images, upscale them, and optimize prompts.

Sources: services/hfService.ts

API Endpoints

The service relies on several public Hugging Face Spaces and the Pollinations.ai API.

Service	Base API URL
Z-Image Turbo	https://luca115-z-image-turbo.hf.space
Qwen Image Fast	https://mcp-tools-qwen-image-fast.hf.space
Upscaler	https://tuan2308-upscaler.hf.space
Prompt Optimization	https://text.pollinations.ai/openai

Sources: services/hfService.ts:3-6

Authentication

API requests can be authenticated using a Hugging Face User Access Token to increase rate limits. The getAuthHeaders function retrieves this token from localStorage and adds it to the request headers if it exists.

// services/hfService.ts:63-72
const getAuthHeaders = (): Record<string, string> => {
  const token = typeof localStorage !== 'undefined' ? localStorage.getItem('huggingFaceToken') : null;
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };
  if (token) {
    headers["Authorization"] = `Bearer ${token}`;
  }
  return headers;
};

The token itself is managed via the SettingsModal component, which saves it to localStorage.
Sources: services/hfService.ts:63-72, components/SettingsModal.tsx:19-22

Gradio API Interaction

The Hugging Face Spaces used for image generation and upscaling expose a Gradio API. Interacting with this API is a two-step process:

1. Queue Request: A POST request is sent to a /call/<function_name> endpoint. This returns an event_id.
2. Fetch Result: A GET request is sent to /call/<function_name>/<event_id> to stream Server-Sent Events (SSE) until a complete event with the final data is received.

The extractCompleteEventData function is responsible for parsing the SSE stream and extracting the JSON data from the complete event.

This sequence diagram shows the flow for generateZImage:

Ancillary Services

Prompt Optimization

The optimizePrompt function sends the user's prompt to the Pollinations.ai API, which uses an OpenAI model to enhance it for better results. The system prompt instructs the AI to act as a prompt engineering expert and return a refined, cinematic prompt under 300 words.
Sources: services/hfService.ts:223-268, README.md:10

Image Upscaling

The upscaler function sends an image URL to a dedicated Hugging Face Space running a Real-ESRGAN model. This service returns a new URL for the 4x upscaled image. The UI then enters a comparison mode using the ImageComparison component before the user decides to apply the change.
Sources: services/hfService.ts:195-221, App.tsx:216-231, components/ImageComparison.tsx, README.md:12

Data Models and Types

The application uses a set of well-defined types to manage data consistently.

Sources: types.ts

GeneratedImage Interface

This is the central data structure for a generated image, containing all relevant metadata.

Enumerated Types

The application uses string literal types to constrain the available options for models and aspect ratios, ensuring type safety.

• ModelOption: Defines the allowed image generation models.
  • "qwen-image-fast"
  • "z-image-turbo"
• AspectRatioOption: Defines the allowed aspect ratios.
  • "1:1", "3:2", "2:3", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9"

Sources: types.ts:14-16, App.tsx:40-43

Configuration

Models

Two primary models are available for generation, each with different characteristics.

Model Value	Label	Notes
z-image-turbo	Z-Image Turbo	Supports an optional "HD" mode for higher resolution outputs.
qwen-image-fast	Qwen Image Fast	A faster alternative model.

Sources: App.tsx:40-43, README.md:9

Aspect Ratios & Dimensions

The z-image-turbo model supports different output dimensions based on the selected aspect ratio and whether HD mode is enabled. The getZImageDimensions function in hfService.ts maps these options to pixel values.

Aspect Ratio	Standard Dimensions	HD Dimensions
1:1	1024 x 1024	2048 x 2048
16:9	1280 x 720	2048 x 1152
9:16	720 x 1280	1152 x 2048
4:3	1024 x 768	2048 x 1536
3:4	768 x 1024	1536 x 2048
3:2	1536 x 1024	1920 x 1280
2:3	1024 x 1536	1280 x 1920
5:4	1280 x 1024	1920 x 1536
4:5	1024 x 1280	1536 x 1920

Sources: services/hfService.ts:8-61, translations.ts:24-32