Database Schema and Core API Endpoints

This page outlines the core database schema and primary API endpoints that power the Infinite Image Browsing application.

Database Schema

The application uses an SQLite database (iib.db) to store and manage image metadata, tags, and internal settings. Below is an overview of the main tables and their purposes:

• Image

  • Purpose: Stores information about individual media files (images, videos, audio) such as their path, extracted generation metadata (EXIF), file size, and modification date.
  • Key Fields:
    • id (INTEGER PRIMARY KEY AUTOINCREMENT): Unique identifier for the image.
    • path (TEXT UNIQUE): Absolute file path to the media file.
    • exif (TEXT): Raw generation information (e.g., Stable Diffusion parameters, ComfyUI prompt JSON).
    • size (INTEGER): File size in bytes.
    • date (TEXT): Last modified date of the file.

• ImageEmbedding

  • Purpose: Stores vector embeddings of image prompt text, used for semantic search and topic clustering.
  • Key Fields:
    • image_id (INTEGER PRIMARY KEY): Foreign key referencing Image.id.
    • model (TEXT NOT NULL): The embedding model used (e.g., text-embedding-3-small).
    • dim (INTEGER NOT NULL): Dimensionality of the embedding vector.
    • text_hash (TEXT NOT NULL): SHA256 hash of the normalized prompt text, used for incremental updates.
    • vec (BLOB NOT NULL): The embedding vector, stored as float32 bytes.
    • updated_at (TEXT NOT NULL): Timestamp of the last update.

• ImageEmbeddingFail

  • Purpose: Caches information about failed embedding generation attempts to prevent repeated, costly API calls for known problematic inputs.
  • Key Fields:
    • image_id (INTEGER NOT NULL): Foreign key referencing Image.id.
    • model (TEXT NOT NULL): The embedding model that failed.
    • text_hash (TEXT NOT NULL): Hash of the normalized prompt text that caused the failure.
    • error (TEXT NOT NULL): Error message from the failed attempt.
    • updated_at (TEXT NOT NULL): Timestamp of the last update.

• TopicTitleCache

  • Purpose: Caches LLM-generated titles and keywords for image clusters, reducing redundant API calls to chat models.
  • Key Fields:
    • cluster_hash (TEXT PRIMARY KEY): A hash representing the unique configuration of a cluster (member images, clustering parameters, etc.).
    • title (TEXT NOT NULL): The LLM-generated concise title for the cluster.
    • keywords (TEXT NOT NULL): JSON string of LLM-generated keywords.
    • model (TEXT NOT NULL): The chat model used for title generation.
    • updated_at (TEXT NOT NULL): Timestamp of the last update.

• TopicClusterCache

  • Purpose: Persists the final result of a topic clustering operation (clusters, noise, etc.) to avoid re-running the entire process if the input data or parameters haven't changed.
  • Key Fields:
    • cache_key (TEXT PRIMARY KEY): A hash derived from the folders, embedding model, and clustering parameters.
    • folders (TEXT NOT NULL): JSON array of the folders included in the clustering scope.
    • model (TEXT NOT NULL): The embedding model used for the clusters.
    • params (TEXT NOT NULL): JSON string of the clustering parameters used.
    • embeddings_count (INTEGER NOT NULL): Count of images with embeddings at the time of caching.
    • embeddings_max_updated_at (TEXT NOT NULL): Latest updated_at timestamp of any embedding used.
    • result (TEXT NOT NULL): JSON string representing the full clustering result (clusters, noise, etc.).
    • updated_at (TEXT NOT NULL): Timestamp of the last update.

• Tag

  • Purpose: Stores various tags associated with images, including auto-generated tags (e.g., model, sampler, prompt keywords) and user-defined custom tags.
  • Key Fields:
    • id (INTEGER PRIMARY KEY AUTOINCREMENT): Unique identifier for the tag.
    • name (TEXT): The name of the tag.
    • score (INTEGER): A numerical score, potentially for relevance or frequency.
    • type (TEXT): Category of the tag (e.g., 'pos' for positive prompt, 'lora', 'custom', 'size', 'Media Type').
    • count (INTEGER): Number of times the tag has been applied to images.
    • color (TEXT): Custom color for the tag (especially for 'custom' type).

• ImageTag

  • Purpose: A many-to-many join table linking Image records to Tag records, indicating which tags are applied to which images.
  • Key Fields:
    • image_id (INTEGER): Foreign key referencing Image.id.
    • tag_id (INTEGER): Foreign key referencing Tag.id.
    • created_at (TIMESTAMP): Timestamp when the tag was associated with the image.

• Folder

  • Purpose: Tracks directories that have been scanned for images and records their last modification date. This helps in efficiently detecting changes and performing incremental updates.
  • Key Fields:
    • id (INTEGER PRIMARY KEY AUTOINCREMENT): Unique identifier for the folder record.
    • path (TEXT): Absolute file path to the folder.
    • modified_date (TEXT): Last modified date of the folder.

• ExtraPath

  • Purpose: Stores user-defined extra paths that should be included in browsing, scanning, or other operations, beyond the default Stable Diffusion WebUI output directories.
  • Key Fields:
    • path (TEXT PRIMARY KEY): Absolute file path to the extra directory.
    • type (TEXT NOT NULL): Defines how the path is used (e.g., 'scanned', 'walk', 'cli_access_only').
    • alias (TEXT DEFAULT ''): An optional, user-friendly alias for the path.

• GlobalSetting

  • Purpose: A general-purpose key-value store for application-wide settings, including frontend preferences and various backend configurations.
  • Key Fields:
    • name (TEXT PRIMARY KEY): The name of the setting.
    • setting_json (TEXT): The value of the setting, stored as a JSON string.
    • created_time (TEXT): Timestamp when the setting was created.
    • modified_time (TEXT): Timestamp of the last modification.

Core API Endpoints

The Infinite Image Browsing application exposes a FastAPI-based API for interacting with the backend. The base path for the API is /infinite_image_browsing (or a configurable alternative).

General Endpoints

• GET /infinite_image_browsing/hello

  • Description: Returns a simple "hello" message to check API connectivity.

• GET /infinite_image_browsing/global_setting

  • Description: Retrieves global application settings, including current working directory, OS information, custom tags, extra paths, access control status, and launch mode.

• POST /infinite_image_browsing/app_fe_setting

  • Description: Updates a frontend-specific setting in the GlobalSetting table.
  • Request: name (string), value (string, JSON representation).

• DELETE /infinite_image_browsing/app_fe_setting

  • Description: Removes a frontend-specific setting from the GlobalSetting table.
  • Request: name (string).

• GET /infinite_image_browsing/version

  • Description: Retrieves version information for the Python environment, platform, and key dependencies, along with the current Git commit hash and tag of the extension.

• POST /infinite_image_browsing/delete_files

  • Description: Deletes specified files or empty folders from the filesystem and removes their records from the database.
  • Request: file_paths (List[str]).

• POST /infinite_image_browsing/mkdirs

  • Description: Creates a new directory at the specified path.
  • Request: dest_folder (str).

• POST /infinite_image_browsing/copy_files

  • Description: Copies specified files (and their associated .txt metadata files) to a destination folder.
  • Request: file_paths (List[str]), dest (str), create_dest_folder (Optional[bool]).

• POST /infinite_image_browsing/move_files

  • Description: Moves specified files (and their associated .txt metadata files) to a destination folder, updating database paths accordingly.
  • Request: file_paths (List[str]), dest (str), create_dest_folder (Optional[bool]).

• GET /infinite_image_browsing/files

  • Description: Lists files and subdirectories within a given folder, including basic file information.
  • Query Parameter: folder_path (str).

• POST /infinite_image_browsing/batch_get_files_info

  • Description: Retrieves detailed file information for a batch of specified paths.
  • Request: paths (List[str]).

• GET /infinite_image_browsing/image-thumbnail

  • Description: Serves image thumbnails. If a thumbnail does not exist, it generates and caches it.
  • Query Parameters: path (str), t (str, timestamp for cache busting), size (str, e.g., "256x256").

• GET /infinite_image_browsing/file

  • Description: Serves static file content, with appropriate caching headers for media files.
  • Query Parameters: path (str), t (str, timestamp for cache busting), disposition (Optional[str], filename for download).

• GET /infinite_image_browsing/stream_video

  • Description: Streams video content using HTTP Range Requests.
  • Query Parameter: path (str).

• GET /infinite_image_browsing/video_cover

  • Description: Serves video cover images. If a cover does not exist, it generates and caches it.
  • Query Parameters: path (str), mt (str, timestamp for cache busting).

• POST /infinite_image_browsing/set_target_frame_as_video_cover

  • Description: Sets a base64 encoded image as the video cover for a given video file.
  • Request: base64_img (str), path (str), updated_time (str).

• POST /infinite_image_browsing/send_img_path

  • Description: Sets an image path to be processed and potentially sent to other UI tabs.
  • Query Parameter: path (str).

• GET /infinite_image_browsing/gen_info_completed

  • Description: Polls to check if the image information generation process (triggered by send_img_path) has completed.

• GET /infinite_image_browsing/image_geninfo

  • Description: Retrieves the raw generation metadata (EXIF data or content of .txt sidecar files) for a single image or video.
  • Query Parameter: path (str).

• POST /infinite_image_browsing/image_geninfo_batch

  • Description: Retrieves raw generation metadata for a batch of images or videos.
  • Request: paths (List[str]).

• POST /infinite_image_browsing/check_path_exists

  • Description: Checks if a list of specified file paths exists and is accessible by the application.
  • Request: paths (List[str]).

• GET /infinite_image_browsing

  • Description: Serves the main frontend HTML file for the application.

• GET /infinite_image_browsing/fe-static/{file_path:path}

  • Description: Serves static frontend assets (JavaScript, CSS, etc.).

• POST /infinite_image_browsing/open_folder

  • Description: Opens a specified folder using the operating system's default file explorer.
  • Request: path (str).

• POST /infinite_image_browsing/shutdown

  • Description: Shuts down the FastAPI application instance. This endpoint is typically disabled by default and used in specific client environments like Tauri.

• POST /infinite_image_browsing/zip

  • Description: Archives a list of specified files or directories into a ZIP file.
  • Request: paths (List[str]), compress (bool), pack_only (bool).

• POST /infinite_image_browsing/open_with_default_app

  • Description: Opens a specified file using the operating system's default associated application.
  • Request: path (str).

• POST /infinite_image_browsing/batch_top_4_media_info

  • Description: Retrieves information for the top 4 media files within a batch of specified directories, primarily used for generating folder cover previews.
  • Request: paths (List[str]).

Database & Tag Management Endpoints (at /infinite_image_browsing/db)

• GET /infinite_image_browsing/db/basic_info

  • Description: Retrieves fundamental database statistics, including image count, all tags, and information about expired (modified) directories.

• GET /infinite_image_browsing/db/random_images

  • Description: Retrieves a batch of random images from the database.

• GET /infinite_image_browsing/db/expired_dirs

  • Description: Checks the database for directories that have been modified since their last scan and returns a list of these "expired" directories.

• POST /infinite_image_browsing/db/update_image_data

  • Description: Triggers an update of image metadata in the database, typically scanning specified directories for changes.

• POST /infinite_image_browsing/db/search_by_substr

  • Description: Searches for images by substring matching in their path or EXIF data. Supports regex and filtering by folder paths and media type.
  • Request: surstr (str), cursor (str), regexp (str), folder_paths (List[str]), size (Optional[int]), path_only (Optional[bool]), media_type (Optional[str]).

• POST /infinite_image_browsing/db/match_images_by_tags

  • Description: Searches for images based on complex combinations of 'AND', 'OR', and 'NOT' tag logic.
  • Request: and_tags (List[int]), or_tags (List[int]), not_tags (List[int]), cursor (str), folder_paths (List[str]), size (Optional[int]), random_sort (Optional[bool]).

• GET /infinite_image_browsing/db/img_selected_custom_tag

  • Description: Retrieves all custom tags currently associated with a specific image.
  • Query Parameter: path (str).

• POST /infinite_image_browsing/db/get_image_tags

  • Description: Retrieves all tags (including custom, model, sampler, etc.) for a batch of specified image paths.
  • Request: paths (List[str]).

• POST /infinite_image_browsing/db/update_tag

  • Description: Updates properties of an existing tag, such as its color.
  • Request: id (int), color (str).

• POST /infinite_image_browsing/db/toggle_custom_tag_to_img

  • Description: Adds a custom tag to an image if it's not present, or removes it if it is.
  • Request: img_path (str), tag_id (int).

• POST /infinite_image_browsing/db/batch_update_image_tag

  • Description: Performs a batch operation to add or remove a specific custom tag for multiple images.
  • Request: img_paths (List[str]), action ('add' | 'remove'), tag_id (int).

• POST /infinite_image_browsing/db/add_custom_tag

  • Description: Creates a new user-defined custom tag.
  • Request: tag_name (str).

• POST /infinite_image_browsing/db/rename

  • Description: Renames a file or folder and updates its path in the database.
  • Request: path (str), name (str).

• POST /infinite_image_browsing/db/remove_custom_tag

  • Description: Removes a custom tag and all its associations from images.
  • Request: tag_id (int).

• POST /infinite_image_browsing/db/remove_custom_tag_from_img

  • Description: Removes a specific custom tag from a specific image.
  • Request: img_id (int), tag_id (str).

• POST /infinite_image_browsing/db/extra_paths

  • Description: Adds a new "extra path" to the application's configuration, specifying its type (e.g., 'scanned', 'walk').
  • Request: path (str), types (List[str]).

• POST /infinite_image_browsing/db/alias_extra_path

  • Description: Assigns an alias (user-friendly name) to an existing extra path.
  • Request: path (str), alias (str).

• GET /infinite_image_browsing/db/extra_paths

  • Description: Retrieves all configured extra paths, including their types and aliases.

• DELETE /infinite_image_browsing/db/extra_paths

  • Description: Removes an extra path from the configuration.
  • Request: path (str), types (List[str]).

• POST /infinite_image_browsing/db/rebuild_index

  • Description: Triggers a complete rebuild of the image index, re-scanning all configured directories.

AI Related Endpoints (at /infinite_image_browsing/db)

These endpoints are part of the [Natural Language AI Features (Experimental)] and are integrated into the main API.

• POST /infinite_image_browsing/db/build_iib_output_embeddings

  • Description: Builds or incrementally updates vector embeddings for image prompt texts within a specified folder.
  • Request: folder (Optional[str]), model (Optional[str]), force (Optional[bool]), batch_size (Optional[int]), max_chars (Optional[int]).

• POST /infinite_image_browsing/db/cluster_iib_output_cached

  • Description: Retrieves a cached clustering result if available, along with metadata indicating if the cache is stale. Does not trigger new computation.
  • Request: folder (Optional[str]), folder_paths (Optional[List[str]]), model (Optional[str]), force_embed (Optional[bool]), threshold (Optional[float]), min_cluster_size (Optional[int]), lang (Optional[str]), force_title (Optional[bool]), use_title_cache (Optional[bool]), assign_noise_threshold (Optional[float]).

• POST /infinite_image_browsing/db/cluster_iib_output_job_start

  • Description: Initiates a background job for image embedding, clustering, and LLM-based title generation for specified folders. Returns a job_id for status polling.
  • Request: (Same as cluster_iib_output_cached).

• GET /infinite_image_browsing/db/cluster_iib_output_job_status

  • Description: Retrieves the current status, stage, and progress of a previously started background clustering job.
  • Query Parameter: job_id (str).

• POST /infinite_image_browsing/db/search_iib_output_by_prompt

  • Description: Performs a natural language search for images within specified folders, using vector embeddings to find semantically similar results.
  • Request: query (str), folder (Optional[str]), folder_paths (Optional[List[str]]), model (Optional[str]), top_k (Optional[int]), min_score (Optional[float]), ensure_embed (Optional[bool]), max_chars (Optional[int]).

• POST /infinite_image_browsing/db/cluster_tag_graph

  • Description: Generates a hierarchical tag graph based on existing clustering results, with LLM-driven abstraction layers, for visualization.
  • Request: folder_paths (List[str]), lang (Optional[str]).

• POST /infinite_image_browsing/db/cluster_tag_graph_cluster_paths

  • Description: Fetches the full image paths for a specific cluster within a tag graph, identified by its cluster_id and the topic_cluster_cache_key.
  • Request: topic_cluster_cache_key (str), cluster_id (str).

• POST /infinite_image_browsing/ai-chat

  • Description: A generic AI chat interface that forwards messages to a configured OpenAI-compatible chat API endpoint.
  • Request: messages (List[dict]), temperature (Optional[float]), max_tokens (Optional[int]), stream (Optional[bool]).