sd-webui-infinite-image-browsing/skills/iib/references/agent-patterns.md

Agent Patterns

Task-oriented patterns for common IIB operations when working with AI agents.

Decision Tree

User wants to find images
├── By keyword/prompt text → POST /db/search_by_substr (surstr)
├── By regex pattern → POST /db/search_by_substr (regexp)
├── By tag → POST /db/match_images_by_tags
└── Random selection → GET /db/random_images

User wants to organize images
├── Move specific files → POST /move_files
├── Copy specific files → POST /copy_files
├── Auto-organize by theme → POST /db/organize_files_start
└── Delete files → POST /delete_files

User wants image info
├── Generation params → GET /image_geninfo
├── Batch metadata → POST /image_geninfo_batch
└── File listing → GET /files

User wants to manage tags
├── List all tags → GET /db/basic_info
├── Create tag → POST /db/add_custom_tag
├── Apply tag to images → POST /db/batch_update_image_tag
└── Search by tag → POST /db/match_images_by_tags

User wants to manage library
├── List paths → GET /db/extra_paths
├── Add folder → POST /db/extra_paths
├── Remove folder → DELETE /db/extra_paths
└── Rebuild index → POST /db/rebuild_index

Common Workflows

Find and tag images

# 1. Search for images
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "sunset", "cursor": "", "size": 100}'
# Note the fullpath values from response

# 2. Check existing tags
curl http://127.0.0.1:<port>/infinite_image_browsing/db/basic_info
# Note tag IDs, or create new tag:

# 3. Create tag if needed
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/add_custom_tag \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "sunset-photos"}'
# Returns: {"id": 5, "name": "sunset-photos", ...}

# 4. Apply tag to found 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": 5}'

Organize messy folder

# 1. Start AI organization
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/organize_files_start \
  -H "Content-Type: application/json" \
  -d '{
    "folder_paths": ["/Downloads/ai-images"],
    "dest_folder": "/Pictures/organized",
    "threshold": 0.85,
    "lang": "en",
    "action": "move"
  }'
# Returns: {"job_id": "abc123"}

# 2. Poll for completion
curl "http://127.0.0.1:<port>/infinite_image_browsing/db/organize_files_status?job_id=abc123"
# Wait until status is "completed"

# 3. 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": "abc123"}'

Add new folder to library

# 1. Add path
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"]}'

# 2. Trigger index update
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/update_image_data \
  -H "Content-Type: application/json" \
  -d '{"path": "/new/image/folder"}'

# 3. Verify images are indexed
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "", "folder_paths": ["/new/image/folder"], "cursor": "", "size": 10}'

Paginate large results

# First page
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "landscape", "cursor": "", "size": 100}'
# Response: {"files": [...], "cursor": {"has_next": true, "next": "cursor_abc"}}

# Next page
curl -X POST http://127.0.0.1:<port>/infinite_image_browsing/db/search_by_substr \
  -H "Content-Type: application/json" \
  -d '{"surstr": "landscape", "cursor": "cursor_abc", "size": 100}'
# Continue until has_next is false

Error Handling

Status	Meaning	Action
200	Success	Parse response
400	Bad request	Check JSON syntax and parameters
404	Not found	Verify file path exists
500	Server error	Check IIB logs
Connection refused	Service not running	Start IIB service

Performance Tips

1. Use folder_paths to limit search scope when possible
2. Use batch endpoints (image_geninfo_batch, batch_update_image_tag) for multiple items
3. Use pagination for large result sets
4. Call update_image_data for specific folders instead of full rebuild_index