bookshelf/books_flutter/OPENAI_SERVICE_SETUP.md

OpenAI Service Setup Guide

This document explains how to configure and use the OpenAI service for parsing book metadata from images.

Overview

The Bookshelf app now supports two AI services for book cover analysis:

1. Google Gemini (original service)
2. OpenAI (new alternate service)

The app will automatically try OpenAI first if configured, and fall back to Gemini if OpenAI fails or is not configured.

Configuration

Step 1: Configure API Keys

Edit lib/config/api_config.dart:

class ApiConfig {
  // Gemini API (original service)
  static const String geminiApiKey = 'YOUR_GEMINI_API_KEY_HERE';
  
  // OpenAI API (new service)
  static const String openaiApiKey = 'YOUR_OPENAI_API_KEY_HERE';
  
  // OpenAI API endpoint
  static const String openaiBaseUrl = 'http://localhost:8317';
}

Step 2: Replace API Keys

Replace the placeholder values with your actual API keys:

• OpenAI API Key: Get from your OpenAI account or local OpenAI-compatible server
• Gemini API Key: Get from Google AI Studio (fallback)

OpenAI Service Details

Endpoint Configuration

The OpenAI service is configured to use:

• Default endpoint: http://localhost:8317/v1/chat/completions
• Model: glm-4 (vision-capable)
• Max tokens: 500
• Temperature: 0.3

Important: The server must support the glm-4 model. This is a required model name for this OpenAI-compatible endpoint.

You can customize the endpoint by changing the openaiBaseUrl in api_config.dart.

How It Works

1. The app captures an image using the camera
2. The image is converted to base64 format
3. A prompt is sent to the OpenAI API with the image
4. The API analyzes the image and extracts:
   • Book title
   • Author name
   • Genre (fiction/fantasy/science/detective/biography/other)
   • Brief annotation/description
5. The parsed data is returned and pre-filled in the add book form

Service Priority

The app follows this priority order:

1. OpenAI (if API key is configured) - tried first
2. Gemini (if OpenAI fails or is not configured) - fallback

This ensures you always have a working service available.

Testing

To test the OpenAI service:

1. Make sure your OpenAI server is running at http://localhost:8317
2. Configure your OpenAI API key in api_config.dart
3. Run the app: flutter run
4. Navigate to the "Add Book" screen
5. Tap the camera icon to scan a book cover
6. The app will use OpenAI to analyze the image

Troubleshooting

"API ключ не настроен (ни OpenAI, ни Gemini)"

This error means neither OpenAI nor Gemini API keys are configured. At least one must be set in api_config.dart.

"Не удалось распознать книгу"

This can occur if:

• The API request failed (check your server logs)
• The image quality is poor
• The API returned invalid JSON
• Network connectivity issues

OpenAI Service Not Working

If OpenAI fails, the app will automatically fall back to Gemini. Check the console output to see which service is being used:

Using OpenAI service for analysis

or

Using Gemini service for analysis

Network Issues

Make sure:

• Your OpenAI server is accessible from the device/emulator
• For Android emulator: Use 10.0.2.2 instead of localhost
• For iOS simulator: localhost should work
• For physical device: Use your machine's actual IP address

Files Modified

1. lib/services/openai_service.dart - New OpenAI service implementation
2. lib/config/api_config.dart - Added OpenAI configuration
3. lib/screens/scanner_screen.dart - Updated to support both services
4. lib/screens/add_book_screen.dart - Updated to pass OpenAI configuration
5. pubspec.yaml - Added http package dependency

Future Enhancements

Possible improvements:

• Add UI option to manually select which service to use
• Add retry logic with different services
• Implement caching of recognized books
• Add support for multiple OpenAI models
• Add detailed error messages and logging