Hugging Face Service

Relevant source files

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

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

The Hugging Face Service, encapsulated within services/hfService.ts, is a client-side module responsible for interfacing with various external AI model APIs to provide the core functionalities of the application. Its primary roles include generating images from text prompts using different models, upscaling generated images, and optimizing user prompts for better results.

This service abstracts the complexities of interacting with multiple APIs, most of which are hosted on Hugging Face Spaces and follow a Gradio API pattern. It provides a set of asynchronous functions that the main application component (App.tsx) consumes to perform these AI-driven tasks.

Sources: services/hfService.ts, README.md, App.tsx

Core Architecture

The service is not a class but a collection of exported functions. It communicates with several distinct API endpoints to fulfill its tasks.

API Endpoints

The service relies on the following external APIs:

Service	Base URL	Purpose
Z-Image Turbo	https://luca115-z-image-turbo.hf.space	High-speed image generation
Qwen Image Fast	https://mcp-tools-qwen-image-fast.hf.space	Alternative fast image generation
Image Upscaler	https://tuan2308-upscaler.hf.space	4x image resolution enhancement
Prompt Optimization	https://text.pollinations.ai/openai	AI-powered prompt enhancement

Sources: services/hfService.ts:3-6, 224

Authentication

Authentication with the Hugging Face APIs is optional and handled by the getAuthHeaders function. This function retrieves a Hugging Face token from the browser's localStorage and includes it as a Bearer token in the Authorization header of API requests. This allows users to leverage their personal Hugging Face quota for higher rate limits. The token is saved to localStorage via the settings modal.

The diagram below illustrates the authentication flow.

Image Generation

The primary function for image generation is generateImage, which acts as a router based on the selected model. It delegates the request to the appropriate model-specific generation function.

Sources: services/hfService.ts:188-196

Gradio API Interaction Flow

Both image generation and upscaling functions follow a common pattern for interacting with the Gradio APIs hosted on Hugging Face Spaces.

1. A POST request is sent to a /call/<function_name> endpoint to queue the generation task.
2. The API responds with an event_id.
3. A GET request is then made to /call/<function_name>/<event_id> to listen for Server-Sent Events (SSE).
4. The SSE stream is parsed by extractCompleteEventData to find the complete event, which contains the final result.

SSE Data Parsing (extractCompleteEventData)

This utility function is crucial for handling responses from the Gradio APIs. It processes the raw text stream, looking for specific events.

• It searches for a line starting with event: complete.
• Once found, it parses the JSON content from the next line starting with data:.
• If it encounters an event: error, it throws an exception with a user-friendly message about quotas.

Sources: services/hfService.ts:74-98

Z-Image Turbo Model (generateZImage)

This function handles generation for the z-image-turbo model. It first determines the correct image dimensions using getZImageDimensions based on the selected aspect ratio and whether HD is enabled. It then follows the standard Gradio API flow to generate the image.

The following sequence diagram shows the process for generateZImage.

Image Dimensions (getZImageDimensions)

The dimensions for the z-image-turbo model are hardcoded based on aspect ratio and the enableHD flag.

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
...	...	...

Sources: services/hfService.ts:8-59, services/hfService.ts:111-140

Qwen Image Fast Model (generateQwenImage)

This function is similar to generateZImage but interacts with the qwen-image-fast API endpoint and uses a slightly different payload structure. It does not support an enableHD option.

Sources: services/hfService.ts:142-171

Image Upscaling (upscaler)

The upscaler function enhances the resolution of a given image by 4x. It uses the tuan2308-upscaler Gradio API and the RealESRGAN_x4plus model. The interaction follows the same queue-and-poll pattern as image generation. The UI triggers this from the handleUpscale function in App.tsx.

The sequence diagram below details the upscaling flow.

Prompt Optimization (optimizePrompt)

The optimizePrompt function enhances a user's text prompt by sending it to the Pollinations.ai API, which is OpenAI-compatible. A detailed system message instructs the AI to act as a prompt engineering expert, rewriting the prompt to be more cinematic, detailed, and evocative while adhering to a 300-word limit and maintaining the original language.

Unlike the Gradio APIs, this is a standard REST API call that returns a JSON object directly.

Sources: services/hfService.ts:223-268, App.tsx:244-256

Data Structures

The service relies on several key types defined in types.ts to ensure consistency between the application logic and the service layer.

Type / Interface	Description
GeneratedImage	Represents a generated image with its metadata, including id, url, prompt, model, and timestamp.
ModelOption	A string literal type for the supported models: "qwen-image-fast" or "z-image-turbo".
AspectRatioOption	A string literal type for all supported aspect ratios, e.g., "1:1", "16:9".

Sources: types.ts

Conclusion

The hfService.ts module is a vital component that serves as the bridge between the application's user interface and the various external AI services. By abstracting the specific API protocols (especially the Gradio SSE pattern) and providing a clean, function-based interface, it allows the main application to easily request complex AI operations like image generation, upscaling, and prompt optimization without needing to know the underlying implementation details. This separation of concerns is key to the application's architecture.