IIB (Infinite Image Browsing)

IIB is an image/video browsing and management tool that parses metadata from AI generation tools (Stable Diffusion, ComfyUI, etc.).

---

Quick Links to Detailed Guides

Topic	Description
API Reference	Complete API endpoint documentation
Search Strategies	Multi-word, regex, tag combination searches
Agent Patterns	Common workflows and decision trees

---

Before You Start

IMPORTANT: Always do these two things first:

1. Ask the user for the port if they started the service themselves (common ports: <port> standalone, 7860 SD WebUI extension)
2. Test connectivity with a hello request before any other operation

curl --noproxy "*" -s http://127.0.0.1:<PORT>/infinite_image_browsing/hello
# Returns: "hello" if service is running

Note: Use --noproxy "*" to bypass proxy for localhost connections.

If service is not running, start it:

cd /path/to/sd-webui-infinite-image-browsing
python app.py --port <port>

To run as a background daemon:

nohup python app.py --port <port> > iib.log 2>&1 &

Quick Reference

Task	Method	Endpoint
Search images	POST	/db/search_by_substr
Search by tags	POST	/db/match_images_by_tags
Random images	GET	/db/random_images
List folder	GET	/files?folder_path=...
Move files	POST	/move_files
Copy files	POST	/copy_files
Tag images	POST	/db/batch_update_image_tag
Get image metadata	GET	/image_geninfo?path=...
Add library path	POST	/db/extra_paths
Remove library path	DELETE	/db/extra_paths

Base URL: http://127.0.0.1:<port>/infinite_image_browsing

Core Operations

Search Images

Basic Keyword Search

Search by keyword in file path or generation parameters:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "landscape", "size": 50}'

Advanced Search

For complex searches (multi-word, regex patterns, tag combinations), see Search Strategies.

Quick tips:

• Multi-word searches? Use regex OR: (word1|word2)
• Need tag combinations? Use /db/match_images_by_tags with AND/OR/NOT logic
• See Search Strategies for detailed strategies

Limit to Specific Folders

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "portrait", "folder_paths": ["/path/to/folder"], "size": 50}'

Response:

{
  "files": [{"fullpath": "/path/to/image.png", "name": "image.png", "size": "1.2 MB", ...}],
  "cursor": {"has_next": true, "next": "cursor_string"}
}

Tag Management

Get all tags:

curl http://127.0.0.1:<port>/infinite_image_browsing/db/basic_info
# Response includes: {"tags": [{"id": 1, "name": "favorites", "type": "custom"}, ...]}

Create a tag:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/add_custom_tag \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "favorites"}'

Tag multiple images:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/batch_update_image_tag \
  -H "Content-Type: application/json" \
  -d '{"img_paths": ["/path/to/img1.png", "/path/to/img2.png"], "action": "add", "tag_id": 1}'

Search by tags (AND/OR/NOT logic):

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/match_images_by_tags \
  -H "Content-Type: application/json" \
  -d '{"and_tags": [1], "or_tags": [], "not_tags": [2], "cursor": "", "size": 50}'

File Operations

List folder contents:

curl "http://127.0.0.1:<port>/infinite_image_browsing/files?folder_path=/path/to/images"

Move files:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/move_files \
  -H "Content-Type: application/json" \
  -d '{"file_paths": ["/path/to/img1.png"], "dest": "/new/folder", "create_dest_folder": true}'

Copy files:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/copy_files \
  -H "Content-Type: application/json" \
  -d '{"file_paths": ["/path/to/img1.png"], "dest": "/backup/folder", "create_dest_folder": true}'

Delete files:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/delete_files \
  -H "Content-Type: application/json" \
  -d '{"file_paths": ["/path/to/unwanted.png"]}'

Image Metadata

Get generation parameters (prompt, seed, model, etc.):

curl "http://127.0.0.1:<port>/infinite_image_browsing/image_geninfo?path=/path/to/image.png"

Batch get metadata:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/image_geninfo_batch \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/path/to/img1.png", "/path/to/img2.png"]}'

Library Management

List registered paths:

curl http://127.0.0.1:<port>/infinite_image_browsing/db/extra_paths

Add a folder to library:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/extra_paths \
  -H "Content-Type: application/json" \
  -d '{"path": "/new/image/folder", "types": ["scanned"]}'

Remove a folder (also cleans up orphaned image records):

curl -X DELETE http://127.0.0.1:<port>/infinite_image_browsing/db/extra_paths \
  -H "Content-Type: application/json" \
  -d '{"path": "/old/folder", "types": ["scanned"]}'

Rebuild index after adding paths:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/rebuild_index

Path types:

• scanned: Indexed, appears in search results
• scanned-fixed: Like scanned, but pinned in UI
• walk: Browse only, not indexed

AI Features

Smart File Organization

Automatically organize images into themed folders:

# Start organization job
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/organize_files_start \
  -H "Content-Type: application/json" \
  -d '{
    "folder_paths": ["/messy/folder"],
    "dest_folder": "/organized/folder",
    "threshold": 0.85,
    "lang": "en",
    "action": "move"
  }'
# Returns: {"job_id": "uuid"}

# Check status
curl "http://127.0.0.1:<port>/infinite_image_browsing/db/organize_files_status?job_id=<job_id>"

# Confirm and execute
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/organize_files_confirm \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<job_id>"}'

Image Clustering

Analyze images and group by semantic similarity:

curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/cluster_iib_output_job_start \
  -H "Content-Type: application/json" \
  -d '{
    "folder_paths": ["/path/to/images"],
    "threshold": 0.85,
    "min_cluster_size": 3,
    "lang": "en",
    "recursive": true
  }'

Reference

See references/api-reference.md for complete API documentation.

Viewing Images

When helping users view images, always provide BOTH:

1. A link to view the first/selected image
2. A link to the search results page showing all matching images

Image Search Results

When a user searches for images (by keyword, tag, etc.):

1. Provide a summary: Show how many images were found
2. First image link: Use the quick view URL for the first result
3. Search results page link: Use the fuzzy-search or tag-search pane URL

Example response format:

Found 150+ images matching "sunset":

[View First Image](http://127.0.0.1:<port>/infinite_image_browsing?action=view&path=/first/image.png)

[View All Results in IIB](http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22sunset%22%7D)

| # | Name | Path | Size |
|---|------|------|------|
| 1 | image1.png | /folder | 1.2 MB |
| 2 | image2.png | /folder | 1.1 MB |
...

Note: The search results page link includes the search term in the URL, so it will automatically display the matching results when opened.

Building Shareable URLs

When generating URLs for users to open in their browser, you need to properly encode the props parameter (JSON URL-encoded).

URL Format:

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=<pane_type>&props=<url_encoded_json>

Encoding the props: The props parameter must be URL-encoded JSON. Use this encoding method:

JSON Props	URL Encoded	Notes
{"substr":"sunset"}	%7B%22substr%22%3A%22sunset%22%7D	Standard encoding
{"substr":"(词1|词2)","isRegex":true}	%7B%22substr%22%3A%22(%E8%AF%8D1%7C%E8%AF%8D2)%22%2C%22isRegex%22%3Atrue%7D	Chinese chars encoded
{"substr":"a|b","isRegex":true}	%7B%22substr%22%3A%22(a%7Cb)%22%2C%22isRegex%22%3Atrue%7D	Pipe | encoded as %7C

Common URL patterns:

Use Case	URL Pattern
Simple keyword search	?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22keyword%22%7D
Regex OR search	?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22(word1%7Cword2)%22%2C%22isRegex%22%3Atrue%7D
Search in folder	?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22keyword%22%2C%22searchScope%22%3A%22%2Fpath%22%7D
View single image	?action=view&path=/path/to/image.png

Tip: When generating URLs with non-ASCII characters (Chinese, Japanese, etc.), use proper URL encoding (UTF-8 percent encoding).

Example: Multi-word search with regex (Chinese)

# Search for "太空电梯" OR "三体"
# JSON: {"substr":"(太空电梯|三体)","isRegex":true}
# Encoded: %7B%22substr%22%3A%22(%E5%A4%AA%E7%A9%BA%E7%94%B5%E6%A2%AF%7C%E4%B8%89%E4%BD%93)%22%2C%22isRegex%22%3Atrue%7D
?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22(%E5%A4%AA%E7%A9%BA%E7%94%B5%E6%A2%AF%7C%E4%B8%89%E4%BD%93)%22%2C%22isRegex%22%3Atrue%7D

Available View Options

1. Quick View (Single Image)

http://127.0.0.1:<port>/infinite_image_browsing?action=view&path=/path/to/image.png

Opens IIB directly to the image in fullscreen preview.

2. Keyword Search Page

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=fuzzy-search

Opens the keyword search page where users can search.

With pre-filled search term:

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22sunset%22%7D

Automatically searches for "sunset" when opened.

Available props for fuzzy-search (URL → Component mapping):

URL Prop	Component Prop	Type	Description
substr	initialSubstr	string	Search keyword or regex pattern
isRegex	initialIsRegex	boolean	Use regex mode (default: false)
searchScope	searchScope	string	Folder path to limit search
pathOnly	initialPathOnly	boolean	Search only file paths (default: false)
mediaType	initialMediaType	string	Filter by media type: "all", "image", "video"
autoSearch	autoSearch	boolean	Auto-trigger search (default: true when substr is set)

Note: Use the URL prop names (left column) when constructing URLs. The component prop names (middle column) are for internal use.

Examples:

# Regex search for multiple keywords (OR logic)
?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22(sunset%7Csunrise%7Cdawn)%22%2C%22isRegex%22%3Atrue%7D

# Search in specific folder
?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22portrait%22%2C%22searchScope%22%3A%22%2Foutputs%22%7D

# Search images only
?action=pane&type=fuzzy-search&props=%7B%22substr%22%3A%22landscape%22%2C%22mediaType%22%3A%22image%22%7D

3. Tag Search Page

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=tag-search

Opens the tag search page for filtering by tags.

4. Tag Search Results (Pre-filtered)

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=tag-search-matched-image-grid&props=%7B%22selectedTagIds%22%3A%7B%22and_tags%22%3A%5B1%2C2%5D%7D%7D%7D

Shows images matching specific tags (replace tag IDs with actual values).

5. Image Comparison

http://127.0.0.1:<port>/infinite_image_browsing?action=pane&type=img-sli&props=%7B%22left%22%3A%7B%22fullpath%22%3A%22%2Fa.png%22%7D%2C%22right%22%3A%7B%22fullpath%22%3A%22%2Fb.png%22%7D%7D

Compare two images side by side.

Note: The props parameter must be URL-encoded JSON.