API Reference (Backend)

This document provides a reference for the FastAPI endpoints exposed by the Infinite Image Browsing backend. The base path for the API is typically /infinite_image_browsing unless configured otherwise. Database-related endpoints are under /infinite_image_browsing/db.

Pydantic Request/Response Models

Many API endpoints utilize Pydantic models for structured data exchange.

• AppFeSettingReq:
  • name: str
  • value: str
• AppFeSettingDelReq:
  • name: str
• DeleteFilesReq:
  • file_paths: List[str]
• CreateFoldersReq:
  • dest_folder: str
• MoveFilesReq:
  • file_paths: List[str]
  • dest: str
  • create_dest_folder: Optional[bool] = False
• PathsReq:
  • paths: List[str]
• SetTargetFrameAsCoverReq:
  • base64_img: str
  • path: str
  • updated_time: str
• GeninfoBatchReq:
  • paths: List[str]
• CheckPathExistsReq:
  • paths: List[str]
• PackReq:
  • paths: List[str]
  • compress: bool
  • pack_only: bool
• OpenFolderReq:
  • path: str
• UpdateTagReq:
  • id: int
  • color: str
• ToggleCustomTagToImgReq:
  • img_path: str
  • tag_id: int
• BatchUpdateImageReq:
  • img_paths: List[str]
  • action: str (e.g., "add", "remove")
  • tag_id: int
• AddCustomTagReq:
  • tag_name: str
• RenameFileReq:
  • path: str
  • name: str
• RemoveCustomTagReq:
  • tag_id: int
• RemoveCustomTagFromReq:
  • img_id: int
  • tag_id: str
• ExtraPathModel:
  • path: str
  • types: List[str] (e.g., "scanned", "walk")
  • alias: str = ''
• ExtraPathAliasModel:
  • path: str
  • alias: str
• AIChatRequest:
  • messages: List[dict]
  • temperature: Optional[float] = 0.7
  • max_tokens: Optional[int] = None
  • stream: Optional[bool] = False
• AIChatResponse:
  • id: str
  • object: str
  • created: int
  • model: str
  • choices: List[dict] (contains message: AIChatMessage, finish_reason: str)
  • usage: dict (contains prompt_tokens, completion_tokens, total_tokens)
• SearchBySubstrReq:
  • surstr: str
  • cursor: str
  • regexp: str
  • path_only: Optional[bool] = False
  • folder_paths: Optional[List[str]] = None
  • size: Optional[int] = 200
  • media_type: Optional[str] = None (e.g., "all", "image", "video")
• MatchImagesByTagsReq:
  • and_tags: List[int]
  • or_tags: List[int]
  • not_tags: List[int]
  • cursor: str
  • folder_paths: Optional[List[str]] = None
  • size: Optional[int] = 200
  • random_sort: Optional[bool] = False
• BuildIibOutputEmbeddingReq:
  • folder: Optional[str] = None
  • model: Optional[str] = None
  • force: Optional[bool] = False
  • batch_size: Optional[int] = 64
  • max_chars: Optional[int] = 4000
• ClusterIibOutputReq:
  • folder: Optional[str] = None
  • folder_paths: Optional[List[str]] = None
  • model: Optional[str] = None
  • force_embed: Optional[bool] = False
  • threshold: Optional[float] = 0.90
  • batch_size: Optional[int] = 64
  • max_chars: Optional[int] = 4000
  • min_cluster_size: Optional[int] = 2
  • title_model: Optional[str] = None
  • assign_noise_threshold: Optional[float] = None
  • use_title_cache: Optional[bool] = True
  • force_title: Optional[bool] = False
  • lang: Optional[str] = None
• PromptSearchReq:
  • query: str
  • folder: Optional[str] = None
  • folder_paths: Optional[List[str]] = None
  • model: Optional[str] = None
  • top_k: Optional[int] = 50
  • min_score: Optional[float] = 0.0
  • ensure_embed: Optional[bool] = True
  • max_chars: Optional[int] = 4000
• TagGraphReq:
  • folder_paths: List[str]
  • lang: Optional[str] = "en"
• TagGraphResp:
  • layers: List[GraphLayer]
  • links: List[GraphLink]
  • stats: dict
• GraphLayer:
  • level: int
  • name: str
  • nodes: List[LayerNode]
• LayerNode:
  • id: str
  • label: str
  • size: float
  • metadata: Optional[dict]
• GraphLink:
  • source: str
  • target: str
  • weight: float
• ClusterPathsReq:
  • topic_cluster_cache_key: str
  • cluster_id: str

API Endpoints

General Endpoints (/infinite_image_browsing)

• GET /infinite_image_browsing/hello
  • Description: Returns a "hello" message.
  • Response: str
• GET /infinite_image_browsing/global_setting
  • Description: Returns global settings, current working directory, OS info, custom tags, extra paths, access control status, launch mode, frontend export functions flag, and app frontend settings.
  • Response: Dict[str, Any] (e.g., {"global_setting": {...}, "cwd": "...", "is_win": true, ...})
• POST /infinite_image_browsing/app_fe_setting
  • Description: Saves a frontend application setting.
  • Request: AppFeSettingReq
  • Response: (No explicit return, typically 200 OK)
• DELETE /infinite_image_browsing/app_fe_setting
  • Description: Removes a frontend application setting.
  • Request: AppFeSettingDelReq
  • Response: (No explicit return, typically 200 OK)
• GET /infinite_image_browsing/version
  • Description: Returns version information for Python, platform, current commit hash, and various Python package versions.
  • Response: Dict[str, Any]
• POST /infinite_image_browsing/delete_files
  • Description: Deletes specified files or empty folders.
  • Request: DeleteFilesReq
  • Response: {"ok": True}
• POST /infinite_image_browsing/mkdirs
  • Description: Creates a new folder at the specified destination.
  • Request: CreateFoldersReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/copy_files
  • Description: Copies specified files to a destination.
  • Request: MoveFilesReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/move_files
  • Description: Moves specified files to a destination.
  • Request: MoveFilesReq
  • Response: (No explicit return, typically 200 OK)
• GET /infinite_image_browsing/files
  • Description: Returns a list of files and directories within the specified folder.
  • Parameters:
    • folder_path: str
  • Response: Dict[str, List[FileInfoDict]]
• POST /infinite_image_browsing/batch_get_files_info
  • Description: Returns file information for a batch of paths.
  • Request: PathsReq
  • Response: Dict[str, FileInfoDict]
• GET /infinite_image_browsing/image-thumbnail
  • Description: Generates and returns a thumbnail for an image, using caching.
  • Parameters:
    • path: str
    • t: str
    • size: str = "256x256"
  • Response: FileResponse (image/webp)
• GET /infinite_image_browsing/file
  • Description: Serves a file, with optional content disposition for download.
  • Parameters:
    • path: str
    • t: str
    • disposition: Optional[str] = None
  • Response: FileResponse
• GET /infinite_image_browsing/stream_video
  • Description: Streams a video file using range requests.
  • Parameters:
    • path: str
    • request: Request
  • Response: StreamingResponse
• GET /infinite_image_browsing/video_cover
  • Description: Generates and returns a cover image for a video file, using caching.
  • Parameters:
    • path: str
    • mt: str
  • Response: FileResponse (image/webp)
• POST /infinite_image_browsing/set_target_frame_as_video_cover
  • Description: Sets a specific frame of a video as its cover image.
  • Request: SetTargetFrameAsCoverReq
  • Response: FileResponse (image/webp)
• POST /infinite_image_browsing/send_img_path
  • Description: Sets the path of an image to be sent to other UI tabs.
  • Parameters:
    • path: str
  • Response: (No explicit return, typically 200 OK)
• GET /infinite_image_browsing/gen_info_completed
  • Description: Checks if image information generation is completed.
  • Response: bool
• GET /infinite_image_browsing/image_geninfo
  • Description: Retrieves raw generation information (exif data) for a given image or video file.
  • Parameters:
    • path: str
  • Response: str
• POST /infinite_image_browsing/image_geninfo_batch
  • Description: Retrieves raw generation information for a batch of image or video files.
  • Request: GeninfoBatchReq
  • Response: Dict[str, str]
• POST /infinite_image_browsing/check_path_exists
  • Description: Checks if a list of paths exist and are trusted.
  • Request: CheckPathExistsReq
  • Response: Dict[str, bool]
• GET /infinite_image_browsing
  • Description: Serves the main HTML page for the Infinite Image Browsing application.
  • Response: Response (text/html)
• POST /infinite_image_browsing/open_folder
  • Description: Opens a folder using the system's default file browser.
  • Request: OpenFolderReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/shutdown
  • Description: Shuts down the FastAPI application. (Typically used in Tauri applications)
  • Response: Dict[str, str]
• POST /infinite_image_browsing/zip
  • Description: Compresses specified files into a ZIP archive and optionally allows download.
  • Request: PackReq
  • Response: FileResponse (application/zip)
• POST /infinite_image_browsing/open_with_default_app
  • Description: Opens a target file with the system's default application.
  • Request: OpenFolderReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/batch_top_4_media_info
  • Description: Retrieves information for the top 4 media files in a batch of folders (for directory covers).
  • Request: PathsReq
  • Response: Dict[str, List[Dict[str, Any]]]

Database Endpoints (/infinite_image_browsing/db)

• GET /infinite_image_browsing/db/basic_info
  • Description: Returns basic database information, including image count, tags, and expired directories.
  • Response: Dict[str, Any]
• GET /infinite_image_browsing/db/random_images
  • Description: Returns a list of random images from the database.
  • Response: List[FileInfoDict]
• GET /infinite_image_browsing/db/expired_dirs
  • Description: Returns information about expired directories in the database.
  • Response: Dict[str, Any]
• POST /infinite_image_browsing/db/update_image_data
  • Description: Triggers an update of image data in the database, including scanning new or modified directories.
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/search_by_substr
  • Description: Searches for images by substring in their paths or EXIF data, supporting regular expressions and folder filtering.
  • Request: SearchBySubstrReq
  • Response: {"files": List[Image], "cursor": Cursor}
• POST /infinite_image_browsing/db/match_images_by_tags
  • Description: Retrieves images based on a combination of AND, OR, and NOT tags, with support for folder filtering and random sorting.
  • Request: MatchImagesByTagsReq
  • Response: {"files": List[Image], "cursor": Cursor}
• GET /infinite_image_browsing/db/img_selected_custom_tag
  • Description: Returns custom tags associated with a specific image.
  • Parameters:
    • path: str
  • Response: List[Tag]
• POST /infinite_image_browsing/db/get_image_tags
  • Description: Retrieves all tags for a batch of images.
  • Request: PathsReq
  • Response: Dict[str, List[Tag]]
• POST /infinite_image_browsing/db/update_tag
  • Description: Updates the color of a specified tag.
  • Request: UpdateTagReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/toggle_custom_tag_to_img
  • Description: Adds or removes a custom tag from an image.
  • Request: ToggleCustomTagToImgReq
  • Response: {"is_remove": bool}
• POST /infinite_image_browsing/db/batch_update_image_tag
  • Description: Adds or removes a specified tag for a batch of images.
  • Request: BatchUpdateImageReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/add_custom_tag
  • Description: Adds a new custom tag.
  • Request: AddCustomTagReq
  • Response: Tag
• POST /infinite_image_browsing/db/rename
  • Description: Renames a file and updates its path in the database.
  • Request: RenameFileReq
  • Response: {"detail": str, "new_path": str}
• POST /infinite_image_browsing/db/remove_custom_tag
  • Description: Removes a custom tag and all its associations from images.
  • Request: RemoveCustomTagReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/remove_custom_tag_from_img
  • Description: Removes a custom tag from a specific image.
  • Request: RemoveCustomTagFromReq
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/extra_paths
  • Description: Adds or updates an extra path for scanning or walking.
  • Request: ExtraPathModel
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/alias_extra_path
  • Description: Sets an alias for an existing extra path.
  • Request: ExtraPathAliasModel
  • Response: ExtraPath
• GET /infinite_image_browsing/db/extra_paths
  • Description: Retrieves all configured extra paths.
  • Response: List[ExtraPath]
• DELETE /infinite_image_browsing/db/extra_paths
  • Description: Removes an extra path based on its path and types.
  • Request: ExtraPathModel
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/db/rebuild_index
  • Description: Triggers a complete rebuild of the image index.
  • Response: (No explicit return, typically 200 OK)
• POST /infinite_image_browsing/ai-chat
  • Description: Generic AI chat interface, forwarding requests to an OpenAI-compatible API.
  • Request: AIChatRequest
  • Response: AIChatResponse

Topic Clustering Endpoints (/infinite_image_browsing/db)

• POST /infinite_image_browsing/db/build_iib_output_embeddings
  • Description: Builds embeddings for image prompt texts within a specified folder.
  • Request: BuildIibOutputEmbeddingReq
  • Response: Dict[str, Any] (e.g., {"folder": str, "count": int, "updated": int, "skipped": int, "model": str})
• POST /infinite_image_browsing/db/cluster_iib_output_cached
  • Description: Returns a cached clustering result if available, along with a stale signal indicating if the cache needs updating.
  • Request: ClusterIibOutputReq
  • Response: Dict[str, Any] (e.g., {"cache_key": str, "cache_hit": bool, "stale": bool, "result": ClusterIibOutputResp | null, ...})
• POST /infinite_image_browsing/db/cluster_iib_output_job_start
  • Description: Starts a background job to perform embedding, clustering, and LLM-driven titling for specified folders. Returns a job ID.
  • Request: ClusterIibOutputReq
  • Response: {"job_id": str}
• GET /infinite_image_browsing/db/cluster_iib_output_job_status
  • Description: Retrieves the current status and progress of a topic clustering background job.
  • Parameters:
    • job_id: str
  • Response: Dict[str, Any] (e.g., {"job_id": str, "status": str, "stage": str, "progress": dict, "error": str, "result": ClusterIibOutputResp | null})
• POST /infinite_image_browsing/db/search_iib_output_by_prompt
  • Description: Performs a semantic search for images based on a natural language query within specified folders.
  • Request: PromptSearchReq
  • Response: Dict[str, Any] (e.g., {"query": str, "folder": str, "model": str, "count": int, "top_k": int, "results": List[dict]})

Tag Graph Endpoints (/infinite_image_browsing/db)

• POST /infinite_image_browsing/db/cluster_tag_graph
  • Description: Builds a hierarchical tag graph visualization from clustering results, with LLM-driven abstraction for higher layers.
  • Request: TagGraphReq
  • Response: TagGraphResp
• POST /infinite_image_browsing/db/cluster_tag_graph_cluster_paths
  • Description: Fetches the full image paths for a specific cluster from a cached clustering result.
  • Request: ClusterPathsReq
  • Response: Dict[str, List[str]] (e.g., {"paths": List[str]})