Supported AI Models
Relevant source files
The following files were used as context for generating this wiki page:This document provides a technical overview of the AI models and services integrated into the 1mage application. The application leverages multiple external Hugging Face and other AI APIs to provide a rich feature set, including multi-model image generation, prompt optimization, and image upscaling. All interactions with these models are managed through the hfService.ts service layer.
The core functionality allows users to switch between different image generation models for varied styles and speeds. Additionally, the application integrates ancillary AI services to enhance the user experience by refining text prompts and improving the resolution of generated images.
Model Integration Architecture
The application's architecture is designed to be modular, allowing different AI models to be selected by the user. The main App.tsx component manages the user's model selection and orchestrates calls to the appropriate service functions.
Sources: App.tsx, services/hfService.ts
Model Selection
Users can choose a model from a predefined list. This selection is managed in the App.tsx component's state and passed to the image generation service.
The available models are defined as a constant in App.tsx:
// App.tsx:30-33
const MODEL_OPTIONS = [
{ value: 'z-image-turbo', label: 'Z-Image Turbo' },
{ value: 'qwen-image-fast', label: 'Qwen Image Fast' }
];
The ModelOption type is strictly defined to ensure type safety.
// types.ts:15
export type ModelOption = "qwen-image-fast" | "z-image-turbo";
The following diagram illustrates the model selection and image generation flow.
This diagram shows how a user's selection in the CustomSelect component updates the application state, which is then used by the handleGenerate function to call the correct service in hfService.ts.
Sources: App.tsx:30-33, 70, 172-192, services/hfService.ts:186-194, types.ts:15, components/CustomSelect.tsx
Image Generation Models
The application supports two primary Hugging Face models for text-to-image generation.
Z-Image Turbo
This model is accessed via the https://luca115-z-image-turbo.hf.space Gradio API endpoint. It supports standard and high-definition (HD) image generation, configurable via an enableHD flag.
The generateZImage function in hfService.ts constructs the request payload and handles the API communication.
API Request Parameters
| Parameter | Type | Description | Source |
|---|---|---|---|
prompt | string | The text prompt for image generation. | services/hfService.ts:121 |
height | number | The height of the image in pixels. | services/hfService.ts:121 |
width | number | The width of the image in pixels. | services/hfService.ts:121 |
steps | number | Hardcoded to 8. | services/hfService.ts:121 |
seed | number | A random seed for reproducibility. | services/hfService.ts:121 |
use_refiner | boolean | Hardcoded to false. | services/hfService.ts:121 |
Supported Resolutions
The output dimensions are determined by the selected aspect ratio and whether the HD option is enabled. This logic is encapsulated in the getZImageDimensions function.
| Aspect Ratio | Standard Definition (SD) | High Definition (HD) |
|---|---|---|
1:1 | 1024 x 1024 | 2048 x 2048 |
16:9 | 1280 x 720 | 2048 x 1152 |
5:4 | 1280 x 1024 | 1920 x 1536 |
4:3 | 1024 x 768 | 2048 x 1536 |
3:2 | 1536 x 1024 | 1920 x 1280 |
9:16 | 720 x 1280 | 1152 x 2048 |
4:5 | 1024 x 1280 | 1536 x 1920 |
3:4 | 768 x 1024 | 1536 x 2048 |
2:3 | 1024 x 1536 | 1280 x 1920 |
Sources: services/hfService.ts:8-57
Qwen Image Fast
This model is accessed via the https://mcp-tools-qwen-image-fast.hf.space Gradio API endpoint. It provides an alternative style and generation speed.
The generateQwenImage function in hfService.ts handles the API interaction.
API Request Parameters
| Parameter | Type | Description | Source |
|---|---|---|---|
prompt | string | The text prompt for image generation. | services/hfService.ts:151 |
seed | number | A seed for generation. Defaults to 42 if not provided. | services/hfService.ts:151 |
random_seed | boolean | true if no seed is provided, false otherwise. | services/hfService.ts:151 |
aspect_ratio | string | The desired aspect ratio (e.g., "1:1"). | services/hfService.ts:151 |
style | number | Hardcoded to 3. | services/hfService.ts:151 |
steps | number | Hardcoded to 8. | services/hfService.ts:151 |
Sources: services/hfService.ts:143-172, README.md:6
Ancillary AI Services
Beyond core image generation, the application uses other AI models for prompt engineering and image upscaling.
Prompt Optimization
To help users create more detailed and effective prompts, the application integrates a prompt enhancement feature using the Pollinations.ai API.
The optimizePrompt function sends the user's original prompt to the openai-fast model via the https://text.pollinations.ai/openai endpoint. A specialized system prompt instructs the model to act as a prompt engineering expert, expanding the user's idea into a more descriptive and cinematic prompt under 300 words.
This diagram shows the sequence of events when a user optimizes a prompt.
Sources: services/hfService.ts:223-273, App.tsx:241-252
Image Upscaling
The application provides a "4x Resolution" feature that upscales generated images. This is achieved using the RealESRGAN_x4plus model hosted at https://tuan2308-upscaler.hf.space.
The upscaler function in hfService.ts takes the URL of an image and sends it to the Gradio API. The API returns a new URL for the upscaled image. The UI then enters a comparison mode to show the before and after versions.
Sources: services/hfService.ts:196-221, App.tsx:206-223, README.md:12
API Communication
Interaction with the Hugging Face Gradio APIs follows a consistent, two-step, asynchronous pattern.
Gradio API Flow
- Queue Job: An initial
POSTrequest is sent to a/call/<function_name>endpoint with the payload. This request queues the generation task and returns anevent_id. - Fetch Result: A
GETrequest is then made to/call/<function_name>/<event_id>. This endpoint streams Server-Sent Events (SSE). The client listens to this stream. - Parse Event: The
extractCompleteEventDatafunction parses the SSE stream, looking specifically for theevent: completemessage. The data associated with this event contains the final result, such as the image URL. It also handlesevent: error.
This diagram illustrates the standard asynchronous communication pattern with the Gradio APIs.
Sources: services/hfService.ts:80-103, 115-127, 149-159
Authentication
API requests can be authenticated using a Hugging Face User Access Token. The getAuthHeaders function retrieves a token from localStorage (key: huggingFaceToken) if it exists and adds it to the request as a Bearer token in the Authorization header. This is optional but provides users with higher rate limits. The token can be set in the application's settings modal.
Sources: services/hfService.ts:59-69, components/SettingsModal.tsx:21-26
Summary
The 1mage application integrates a curated set of AI models to offer a flexible and powerful image generation toolkit. It supports two distinct text-to-image models (Z-Image Turbo and Qwen Image Fast) with different characteristics, allowing users to choose the best fit for their creative needs. The experience is further enhanced by ancillary AI services for prompt optimization and high-resolution upscaling, all communicating with backend Hugging Face spaces through a standardized asynchronous API pattern.