Building Your First AI-Powered WordPress Plugin with Core APIs

Introduction to Modern WordPress AI Architecture

Recent WordPress releases introduced foundational APIs designed to standardize artificial intelligence integration for developers. Instead of writing custom cURL requests to third-party endpoints or hardcoding specific model providers, you can leverage three core pillars: the Abilities API, the WordPress AI Client, and the Connectors API. These layers allow you to register standard units of functionality, interact with any LLM provider transparently, and manage authentication securely through a unified WordPress administration interface.

In this technical walkthrough, we will examine how these building blocks stitch together inside a real plugin named Photo to Post. This plugin accepts an image URL, processes it using a vision-capable AI model, drafts post copy based on that description, and saves a new WordPress draft complete with an automatically sideloaded featured image.

Understanding the Core AI Building Blocks

Before modifying code, it is critical to understand the separation of concerns among the core APIs:

• The Abilities API: Provides a standardized mechanism to register executable units of functionality. Once registered, an ability can be invoked via the WordPress REST API, standard PHP calls, or exposed to external AI agents via the Model Context Protocol (MCP) Adapter.
• The WordPress AI Client: A provider-agnostic PHP library that abstracts interactions with large language models. Your custom code interacts with a unified fluent interface, meaning it remains agnostic whether OpenAI, Anthropic, Google, or a local Ollama instance processes the request.
• The Connectors API: Eliminates the fragmentation of custom settings pages for API keys. It offers a centralized interface under the WordPress Settings menu where administrators securely store credentials for various services.

Setting Up the Development Environment

To run and test the plugin code in this tutorial, ensure your local development stack meets the following requirements:

• A local WordPress environment running version 7.0 or later on PHP 8.1 or higher.
• Composer and Node.js installed globally for dependency management.
• API credentials for an AI provider supporting a vision-capable model (such as Anthropic Claude or OpenAI GPT-4o).

Begin by downloading and extracting the starter plugin from the official workshop repository. Navigate to the plugin directory in your terminal and execute the package installation commands:

composer install
npm install

Activate the WP AI Workshop Demo plugin within your local WordPress administration dashboard. This registers a dedicated admin page under the Tools menu powered by the WordPress DataForm package.

Step 1: Registering Abilities and Categories

All ability registrations take place within your plugin’s include files. First, group your custom functionalities by registering an ability category using wp_register_ability_category(). Then, register individual capabilities using wp_register_ability(), supplying explicit input and output schemas.

wp_register_ability(
    'wp-ai-workshop-demo/describe-image',
    array(
        'label' => __( 'Describe an image via AI', 'wp-ai-workshop-demo' ),
        'description' => __( 'Given an image URL, use AI vision to produce a detailed text description.', 'wp-ai-workshop-demo' ),
        'category' => 'wp-ai-workshop-demo',
        'input_schema' => array(
            'type' => 'object',
            'properties' => array(
                'image_url' => array(
                    'type' => 'string',
                    'description' => 'The URL of the image to describe.',
                ),
            ),
            'required' => array( 'image_url' ),
        ),
        'output_schema' => array(
            'type' => 'object',
            'properties' => array(
                'description' => array(
                    'type' => 'string',
                    'description' => 'A detailed description of the image.',
                ),
            ),
            'required' => array( 'description' ),
        ),
        'execute_callback' => 'wp_ai_workshop_demo_describe_image',
        'permission_callback' => function () {
            return current_user_can( 'edit_posts' );
        },
        'meta' => array(
            'show_in_rest' => true,
        ),
    )
);

By declaring 'show_in_rest' => true, WordPress automatically exposes the ability over the REST API without requiring manual endpoint routing.

Step 2: Hooking Abilities and Testing via REST

Wire your registration functions to the dedicated Core action hooks within your main plugin initialization file:

add_action( 'wp_abilities_api_categories_init', 'wp_ai_workshop_demo_register_ability_categories' );
add_action( 'wp_abilities_api_init', 'wp_ai_workshop_demo_register_describe_image_ability' );

Verify your setup by generating an Application Password for an administrator account and querying the REST endpoint via cURL:

curl -u 'USERNAME:APPLICATION_PASSWORD' https://yoursite.local/wp-json/wp-abilities/v1/abilities

The resulting JSON payload should list core system abilities alongside your newly registered wp-ai-workshop-demo/* endpoints.

Step 3: Implementing Vision Calls with the AI Client

Inside your execution callbacks, leverage the fluent builder provided by the WordPress AI Client. Because frontier models handle image inputs differently, convert remote images into base64 data URIs for cross-provider compatibility:

function wp_ai_workshop_demo_describe_image( $arguments ) {
    $image_url = $arguments['image_url'];
    $data_uri = wp_ai_workshop_demo_image_url_to_data_uri( $image_url );
    
    if ( is_wp_error( $data_uri ) ) {
        return $data_uri;
    }

    $prompt = 'Describe this image in detail focusing on subjects, setting, and tone.';
    
    $description = wp_ai_client_prompt()
        ->with_text( $prompt )
        ->with_file( $data_uri )
        ->generate_text();

    if ( is_wp_error( $description ) ) {
        return $description;
    }

    return array(
        'description' => trim( $description ),
    );
}

Note that the AI Client returns a WP_Error object upon failure rather than throwing uncaught exceptions, streamlining error handling routines.

Step 4: Ability Composition and Post Orchestration

The primary advantage of the Abilities API is ability composition, where one ability orchestrates execution across other registered units. The create-post-from-photo ability fetches the description ability, executes it, passes output data into the generation ability, and handles post creation without invoking the AI client directly:

$describe_ability = wp_get_ability( 'wp-ai-workshop-demo/describe-image' );
$description_result = $describe_ability->execute( array( 'image_url' => $image_url ) );

$generate_ability = wp_get_ability( 'wp-ai-workshop-demo/generate-post-from-description' );
$copy_result = $generate_ability->execute( array(
    'description' => $description_result['description'],
    'prompt' => $prompt,
) );

return wp_ai_workshop_demo_create_post( $copy_result['title'], $copy_result['content'], $image_url );

Limitations, Security, and Best Practices

When developing AI-integrated extensions for production environments, developers must account for several technical constraints:

• Non-Deterministic Outputs: LLMs do not output strictly deterministic code. Always incorporate defensive parsing layers—such as regex filters stripping markdown code fences—when requesting structured JSON payloads.
• Execution Timeouts: Vision tasks and multi-step generations require external HTTP requests that can exceed standard PHP execution limits. Ensure timeout parameters on remote fetches are explicitly defined.
• Authorization Checks: Always enforce strict permission callbacks (e.g., current_user_can('edit_posts')) on registered abilities to prevent unauthorized resource consumption.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.