AI Provider Guide

This guide explains how to configure and choose the right AI provider for the Virtual Media Folders AI Organizer plugin.

Table of Contents

• Overview
• Choosing a Model
• Provider Setup
  • WordPress AI (Recommended)
  • OpenAI
  • Azure OpenAI
  • Anthropic Claude
  • Google Gemini
  • Ollama (Local)
  • Grok (xAI)
  • Exo (Distributed Local)
• Troubleshooting

Overview

This plugin uses vision-capable AI models to analyze actual image content. The AI looks at what’s in the image (objects, scenes, people, colors, activities) to determine the best folder for each media file.

Important: You must configure an AI provider before scanning. Documents (PDF, Word, etc.) and videos are automatically assigned to “Documents” and “Videos” folders without requiring AI.

Quick Provider Comparison

Provider	Type	Best For
WordPress AI	Core	WP 7.0+, centralized connector config
OpenAI	Cloud	General use, easiest setup
Azure OpenAI	Cloud	Enterprise, data residency, compliance
Anthropic	Cloud	Nuanced understanding, detailed analysis
Gemini	Cloud	Cost-effective, free tier available
Ollama	Local	Privacy, no API costs, offline use
Grok	Cloud	xAI ecosystem
Exo	Local	Distributed computing across devices

Choosing a Model

The Most Important Requirement: Vision Support

This plugin requires a vision-capable model. Models without vision support cannot analyze images.

How to identify vision-capable models:

• Look for “vision” in the model name
• Check for “multimodal” capabilities in documentation
• Confirm the model accepts image input

Model Tiers Explained

Most providers offer models in different tiers. Understanding these helps you choose wisely:

Tier	Characteristics	Best For
Flagship	Highest quality, more expensive, sometimes slower	Complex categorization needing nuanced understanding
Balanced	Good quality at moderate cost	Most typical use cases
Fast/Mini	Lower cost, faster, slightly reduced quality	Large media libraries, simple categorization

Recommendation: Start with a “balanced” or “mini/flash” tier model. You can upgrade later if needed.

What to Consider When Choosing

1. Cost vs. Quality

• Budget-conscious: Use the provider’s cheapest vision-capable model
• Quality-focused: Use the flagship vision model
• Large libraries (1000s of images): Cheaper models keep costs manageable

2. Speed

• Mini/Flash models process faster
• Flagship models may be slower but more accurate
• Local models (Ollama) depend entirely on your hardware

3. Privacy

• Cloud providers: Images are sent to external servers
• Local providers (Ollama, Exo): All processing stays on your infrastructure

4. Reliability

• Major cloud providers (OpenAI, Anthropic, Google) offer high availability
• Local solutions require your server to be capable and running

Finding Current Models

Model offerings change frequently. Always check your provider’s official documentation for the latest vision-capable models:

Provider	Documentation
OpenAI	platform.openai.com/docs/models
Anthropic	docs.anthropic.com/en/docs/models
Google Gemini	ai.google.dev/gemini-api/docs/models
Ollama	ollama.com/library (filter for “vision”)
Grok/xAI	docs.x.ai

Tip: When reviewing model lists, look for terms like “vision”, “multimodal”, “image input”, or “visual understanding”.

---

Provider Setup

WordPress AI (Recommended)

Available in WordPress 7.0+

WordPress 7.0 introduced a built-in AI Client that centralizes AI connector configuration. This is the recommended option when available because:

• Centralized configuration: Configure AI connectors once in WordPress settings, use across all plugins
• No duplicate API keys: Don’t store API keys in multiple plugins
• Core integration: Uses WordPress’s maintained AI infrastructure
• Easy switching: Change AI providers without updating individual plugins

Requirements

• WordPress 7.0 or later
• At least one AI connector configured in Settings → Connectors

Configuration

1. Go to Settings → Connectors (wp-admin/options-general.php?page=connectors-wp-admin)
2. Add an AI connector — for example, install AI Provider for Azure OpenAI for Azure-hosted models
3. Configure your API credentials in the Connectors settings
4. In Media → AI Organizer → AI Provider:
   • Set AI Provider to “WordPress AI (Core)”
   • That’s it! The connector handles the rest

Checking Availability

The “WordPress AI (Core)” option only appears when:

• WordPress 7.0+ is detected (the wp_ai_client_prompt() function is available)
• At least one AI connector is configured in Settings → Connectors

If you don’t see this option, either you’re on an older WordPress version or no connectors have been configured yet. Use one of the providers below as an alternative.

---

OpenAI

OpenAI is the most popular choice and easiest to set up.

Getting Started

1. Create an account at platform.openai.com
2. Generate an API key at API Keys
3. Check Models documentation for current vision-capable models

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “OpenAI”
• Set OpenAI Type to “OpenAI”
• Enter your API Key
• Set Model to a current vision-capable model

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'openai' );
define( 'VMFA_AI_OPENAI_KEY', 'sk-...' );
define( 'VMFA_AI_OPENAI_MODEL', 'your-chosen-model' );

Tips

• Start with a “mini” or budget-tier model for testing
• Upgrade to flagship models if you need better accuracy
• Check OpenAI’s pricing page for current costs

---

Azure OpenAI

Azure OpenAI is ideal for enterprises needing data residency, compliance, and Azure integration.

There are two ways to use Azure OpenAI with this plugin:

1. Via WordPress AI (Recommended on WP 7.0+) — Install the AI Provider for Azure OpenAI connector plugin and select “WordPress AI (Core)” as your provider.
2. Direct configuration — Configure Azure credentials directly in the AI Organizer settings.

Option 1: WordPress AI Connector (Recommended)

This approach uses the WordPress 7.0+ AI Client so your Azure credentials are configured once and shared across all plugins.

Prerequisites

• WordPress 7.0 or later
• An Azure subscription with an Azure OpenAI resource and a deployed vision-capable model

Setup

1. Download and install AI Provider for Azure OpenAI (Plugins → Add New → Upload Plugin)
2. Go to Settings → Connectors and click Set Up next to Azure OpenAI
3. Enter your API Key (from Azure Portal → Your OpenAI Resource → Keys and Endpoint)
4. Enter your Endpoint URL (e.g., https://your-resource.openai.azure.com)
5. Enter your API Version, Deployment ID, and select Capabilities
6. Click Save Settings
7. In Media → AI Organizer → AI Provider, set AI Provider to “WordPress AI (Core)”

The connector supports text generation, image generation, embeddings, text-to-speech, and multimodal input (text, image, audio, document combinations).

Environment Variables (Connector)

The connector plugin also supports environment variables as fallbacks:

export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_API_VERSION="2024-02-15-preview"    # Optional
export AZURE_OPENAI_DEPLOYMENT_ID="gpt-4o"               # Optional
export AZURE_OPENAI_CAPABILITIES="text_generation,chat_history"  # Optional, comma-separated

Available capabilities: text_generation, image_generation, chat_history, embedding_generation, text_to_speech_conversion.

Option 2: Direct Configuration

Use this approach on WordPress < 7.0 or if you prefer per-plugin credentials.

Getting Started

1. Have an Azure subscription
2. Create an Azure OpenAI resource in Azure Portal
3. Deploy a vision-capable model with a deployment name
4. Note your endpoint URL and key

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “OpenAI”
• Set OpenAI Type to “Azure”
• Enter your Azure Endpoint (e.g., https://your-resource.openai.azure.com)
• Enter your API Key
• Set Model/Deployment to your deployment name (not the model name)

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'openai' );
define( 'VMFA_AI_OPENAI_TYPE', 'azure' );
define( 'VMFA_AI_OPENAI_KEY', 'your-azure-api-key' );
define( 'VMFA_AI_OPENAI_MODEL', 'your-deployment-name' );
define( 'VMFA_AI_AZURE_ENDPOINT', 'https://your-resource.openai.azure.com' );
define( 'VMFA_AI_AZURE_API_VERSION', '2024-02-15-preview' );

Tips

• On WP 7.0+, the connector approach is preferred — configure once, use everywhere
• The Model field must be your deployment name, not the underlying model name
• Use a recent API version for vision support (check Azure docs for current versions)
• Deploy a vision-capable model (e.g., GPT-4o, GPT-4.1) in your Azure OpenAI resource
• Azure OpenAI uses api-key header auth instead of Authorization: Bearer — the plugin handles this automatically

---

Anthropic Claude

Anthropic’s Claude models are known for nuanced understanding and detailed analysis.

Getting Started

1. Create an account at console.anthropic.com
2. Generate an API key
3. Check Models documentation for current vision-capable models

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “Anthropic”
• Enter your API Key
• Set Model to a current vision-capable model (Claude 3+ models support vision)

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'anthropic' );
define( 'VMFA_AI_ANTHROPIC_KEY', 'sk-ant-...' );
define( 'VMFA_AI_ANTHROPIC_MODEL', 'your-chosen-model' );

Tips

• All Claude 3 and later models support vision
• Sonnet models offer a good balance of quality and cost
• Haiku models are faster and cheaper for high-volume use

---

Google Gemini

Google Gemini offers competitive vision capabilities with a generous free tier.

Getting Started

1. Get an API key from Google AI Studio
2. Check Models documentation for current options

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “Gemini”
• Enter your API Key
• Set Model to a current vision-capable model (Flash models recommended for cost)

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'gemini' );
define( 'VMFA_AI_GEMINI_KEY', 'your-api-key' );
define( 'VMFA_AI_GEMINI_MODEL', 'your-chosen-model' );

Tips

• Gemini has a free tier with rate limits - great for testing
• Flash models are optimized for speed and cost
• Pro models offer higher capability for complex tasks

---

Ollama (Local)

Ollama runs AI models entirely on your own hardware - completely free and private.

Prerequisites

1. A server with sufficient RAM (8GB+ recommended) and ideally a GPU
2. Ollama installed

Getting Started

# Install Ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Browse available models at ollama.com/library
# Look for vision-capable models (e.g., models with "llava" or "vision")

# Pull a vision model
ollama pull <model-name>

# Verify Ollama is running
curl http://localhost:11434/api/tags

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “Ollama”
• Set Ollama URL to http://localhost:11434
• Click Refresh Models to populate the model dropdown from your running Ollama server
• Select a model from the dropdown
• Optionally adjust Ollama Timeout (default 120 seconds) for larger models or slower hardware

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'ollama' );
define( 'VMFA_AI_OLLAMA_URL', 'http://localhost:11434' );
define( 'VMFA_AI_OLLAMA_MODEL', 'your-vision-model' );
define( 'VMFA_AI_OLLAMA_TIMEOUT', 120 ); // Optional: timeout in seconds (10-600)

Tips

• Click Refresh Models to see all models installed in your Ollama instance
• Search the Ollama library for “vision” to find compatible models
• Larger models need more VRAM/RAM but produce better results
• Increase the timeout setting for larger models or slower hardware
• If WordPress is in Docker, use http://host.docker.internal:11434
• Processing is slower than cloud APIs but completely free and private

---

Grok (xAI)

Grok is xAI’s AI assistant with vision capabilities.

Getting Started

1. Get an API key from xAI Console
2. Check their documentation for current vision-capable models

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

• Set AI Provider to “Grok”
• Enter your API Key
• Set Model to a vision-capable Grok model

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'grok' );
define( 'VMFA_AI_GROK_KEY', 'your-api-key' );
define( 'VMFA_AI_GROK_MODEL', 'your-chosen-model' );

---

Exo (Distributed Local)

Exo allows running AI models across multiple local devices, pooling their compute power. It exposes an OpenAI-compatible API locally.

Getting Started

1. Install Exo
2. Start the Exo cluster on your device(s)
3. Note the API endpoint (default: http://localhost:52415)

Configuration (Admin UI)

In Media → AI Organizer → AI Provider:

1. Set AI Provider to “Exo (Distributed Local)”
2. Enter your Exo Endpoint (e.g., http://localhost:52415)
3. Click Check Connection to verify connectivity (you’ll see ✅ or ❌)
4. Click Refresh Models to populate the model dropdown from your running cluster
5. Select a model from the dropdown

Features:

• Health Check Button: Visual indicator (✅/❌) shows connection status
• Dynamic Model List: Models are fetched directly from your running Exo cluster
• No API Key Required: Exo runs locally on your network

Configuration (wp-config.php)

define( 'VMFA_AI_PROVIDER', 'exo' );
define( 'VMFA_AI_EXO_ENDPOINT', 'http://localhost:52415' );
define( 'VMFA_AI_EXO_MODEL', 'llama-3.2-3b' );

Tips

• Ensure at least one model is loaded in your Exo cluster before configuring
• The timeout for Exo requests is 60 seconds (local inference can be slower)
• Vision support depends on the model being used in your cluster

---

Troubleshooting

”No AI provider configured”

You must select and configure an AI provider in Media → AI Organizer → AI Provider.

”API key not configured” or authentication errors

1. Verify your API key is entered correctly
2. For Azure, ensure the endpoint URL format is correct
3. Check that your API key has the necessary permissions

Empty responses or parse errors

1. Ensure you’re using a vision-capable model
2. Check that images are in a supported format (JPEG, PNG, GIF, WebP)
3. Try a different model - some handle certain images better
4. Check your provider’s status page for outages

Ollama connection refused

1. Ensure Ollama is running: ollama serve
2. Verify the URL is correct (default: http://localhost:11434)
3. If WordPress is in Docker, use http://host.docker.internal:11434
4. Check firewall settings if accessing remotely

Ollama timeout errors

Vision models can take 30+ seconds per image, and complex or high-resolution images may take even longer. If you’re seeing timeout errors:

1. Increase the Ollama Timeout setting in the AI Provider tab (default is 120 seconds, max 600 seconds)
2. Or add to wp-config.php:

   define( 'VMFA_AI_OLLAMA_TIMEOUT', 180 ); // 3 minutes

3. Larger models take longer to load into memory on first request
4. Consider using a smaller/faster model for quicker responses (e.g., moondream instead of llama3.2-vision)
5. Ensure your hardware meets the model’s requirements (RAM/VRAM)

Exo connection issues

1. Ensure your Exo cluster is running: check with curl http://localhost:52415/v1/models
2. Verify the endpoint URL matches your Exo configuration (default port is 52415)
3. Use the Check Connection button in settings to verify connectivity
4. Click Refresh Models to see available models from your cluster
5. Ensure at least one model is loaded in your Exo cluster
6. Check firewall allows local connections on the configured port
7. If WordPress is in Docker, use http://host.docker.internal:52415

Rate limiting

1. Reduce the Batch Size in settings
2. The plugin automatically handles rate limits with retries
3. Consider upgrading your API plan for higher limits

High costs

1. Switch to a cheaper/mini model tier
2. Use Organize Unassigned mode instead of re-analyzing everything
3. Use Preview Mode first to verify results before applying
4. Consider Ollama for free local processing

Model not found

1. Verify the model name is spelled correctly
2. Check if the model is available in your region/account
3. For Azure, ensure you’re using the deployment name, not the model name
4. Check the provider’s documentation for current available models

📦 Source: soderlind/vmfa-ai-organizer · Edit on GitHub