Pollinations.ai Integration

Relevant source files

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

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

The Pollinations.ai integration provides an AI-powered prompt enhancement feature within the application. Its purpose is to take a user's basic text prompt and automatically rewrite it into a more detailed, cinematic, and descriptive version optimized for generative AI models. This process, referred to as "Prompt Engineering," aims to improve the quality and artistic output of the generated images.

This integration is a distinct service used for text manipulation before the main image generation request is sent to the Hugging Face models. It is exposed to the user through an "Optimize" button in the main interface.

Sources: README.md, services/hfService.ts:208-258, App.tsx:280-292

Architecture and Data Flow

The prompt optimization feature is initiated from the main App component and executed by a dedicated function in the hfService module. The flow involves the user interface triggering a function, which in turn makes an external API call to Pollinations.ai and updates the application's state with the result.

High-Level Data Flow

The following diagram illustrates the process from user interaction to the prompt being updated in the UI.

This diagram shows the flow of data starting from the user's action, through the service layer to the external API, and back to update the UI.

Sources: App.tsx:280-292, services/hfService.ts:208-258

UI Integration

The feature is accessible via an "Optimize" button located next to the prompt input field. The button's state and text change dynamically to provide feedback to the user.

Sources: App.tsx:501-517

Components and State

• Optimize Button: A <button> element that triggers the handleOptimizePrompt function. It is disabled when a request is in progress (isOptimizing is true) or when the prompt is empty.
• isOptimizing State: A boolean state (const [isOptimizing, setIsOptimizing] = useState<boolean>(false);) in App.tsx that tracks the loading status of the optimization request. It is used to show a loader icon and disable the button.
• error State: A string state that holds any error message if the API call fails, which is then displayed to the user.

UI Text Labels

The text labels for the button and its title are managed in the translations.ts file to support multiple languages.

Key	English Value	Chinese Value	Description
optimize	"Optimize"	"优化"	Default button text.
optimizing	"Optimizing..."	"优化中..."	Text shown during the API call.
optimizeTitle	"Enhance prompt with AI"	"使用 AI 优化提示词"	Tooltip text for the button.

Sources: App.tsx:80, 281, 504, translations.ts:7-9, 44-46

API Interaction

The core logic resides in the optimizePrompt function within services/hfService.ts. This function is responsible for communicating with the Pollinations.ai backend.

API Endpoint

• URL: https://text.pollinations.ai/openai
• Method: POST

This endpoint is defined as the constant POLLINATIONS_API_URL.

Sources: services/hfService.ts:5, 210

Request Payload

The function sends a JSON payload with a specific structure. The key part is the messages array, which contains a system message defining the AI's role and a user message with the original prompt.

{
  "model": "openai-fast",
  "messages": [
    {
      "role": "system",
      "content": "I am a master AI image prompt engineering advisor... My output will consist exclusively of the refined image prompt text... The text will strictly avoid markdown, quotation marks, conversational preambles, explanations, or concluding remarks..."
    },
    {
      "role": "user",
      "content": "/* originalPrompt from user */"
    }
  ],
  "stream": false
}

The system prompt instructs the AI to act as a prompt engineering expert, rewrite the user's prompt to be more cinematic and detailed, and return only the refined text, ensuring it's under 300 words and in the same language as the input.

Sources: services/hfService.ts:211-239

Sequence Diagram

This diagram shows the sequence of calls when a user optimizes a prompt.

Error Handling

Both handleOptimizePrompt in App.tsx and optimizePrompt in services/hfService.ts are wrapped in try...catch blocks. If the fetch call fails (e.g., network error or non-200 status), an error is thrown. This error is caught in App.tsx, and the error state is updated with a user-friendly message, which is then rendered in the UI.

// App.tsx
try {
    const optimized = await optimizePrompt(prompt);
    setPrompt(optimized);
} catch (err: any) {
    console.error("Optimization failed", err);
    setError("Failed to optimize prompt. Please try again.");
} finally {
    setIsOptimizing(false);
}

Sources: App.tsx:283-291, services/hfService.ts:254-257

Summary

The Pollinations.ai integration serves as a powerful utility for prompt engineering. It is seamlessly integrated into the application's UI, providing users with a one-click method to enhance their creative ideas. The feature is implemented through a clean separation of concerns, with the App.tsx component handling user interaction and state management, while the services/hfService.ts module encapsulates the external API communication, making the system modular and easy to maintain.