Skip to content
WP EngineDocumentation

Using the WordPress AI Client

If you’re building a WordPress plugin or theme, you may not need to call the AI API directly. WordPress 7.0 ships a built-in AI Client with a fluent PHP API for text, image, and speech generation, and the WP Engine AI Connector plugin registers a wpengine provider for it — so your code never touches an API key, and auth, retries, and provider routing are handled for you.

Prerequisites

Section titled “Prerequisites”
  1. Install and activate the WP Engine AI Connector and WP Engine AI plugins.
  2. From Settings → Connectors → WP Engine AI Connector, connect the site to a WP Engine account.
  3. Run WordPress 7.0 or later. The AI Client is part of WordPress core, so your plugin or theme calls it directly — there is nothing extra to install.

What it looks like

Section titled “What it looks like”

Generate text with the fluent builder. The AI Client picks a suitable model from the registered providers, sends the request through the connector, and returns the generated text.

<?php
declare( strict_types = 1 );


$summary = wp_ai_client_prompt( 'Summarize the speed of light in one sentence.' )
    ->using_system_instruction( 'You are concise.' )
    ->using_temperature( 0.2 )
    ->generate_text();


if ( is_wp_error( $summary ) ) {
    // Log the error and fall back to a non-AI code path.
    return;
}

generate_text() returns a string on success and a WP_Error on failure — wp_ai_client_prompt() converts every AI Client exception into a WP_Error, so always check the result with is_wp_error(). For the full result object (token usage, the model that answered, finish reason) use generate_text_result() instead. The wpengine provider returns one candidate per request, so ask for a single result rather than several via generate_texts().

Pin specific models when you need them for cost, latency, or capability reasons. List them in order of preference — the AI Client uses the first one the connector exposes:

$summary = wp_ai_client_prompt( 'Summarize the speed of light in one sentence.' )
    ->using_provider( 'wpengine' )
    ->using_model_preference( 'google/gemini-3.5-flash', 'google/gemini-3.7-flash' )
    ->generate_text();

The connector reports itself as unavailable when the site isn’t connected. Check that before showing an AI feature, so a disconnected site hides it instead of surfacing an error. WordPress core doesn’t wrap this check, so call the bundled SDK class directly:

use WordPress\AiClient\AiClient;


if ( ! AiClient::isConfigured( 'wpengine' ) ) {
    // Show an admin notice or fall back to a non-AI code path.
    return;
}

Swap generate_text() for generate_image() to produce an image instead. It returns a WordPress\AiClient\Files\DTO\File whose image data is inline and base64-encoded. Decode it to save the image to the uploads directory:

$image = wp_ai_client_prompt( 'A pixel-art lighthouse at sunset' )
    ->using_provider( 'wpengine' )
    ->generate_image();


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


// $image->getMimeType() reports the format, e.g. image/png.
$upload = wp_upload_bits(
    'lighthouse.png',
    null,
    base64_decode( $image->getBase64Data() )
);

Who can make requests

Section titled “Who can make requests”

The connector only attaches the site’s credentials to a request when it runs as one of:

  • A logged-in user with the edit_posts capability (Contributor and above)
  • WP-CLI
  • WP-Cron

Any other request — including one made while rendering a page for an anonymous visitor — is sent without credentials, and the call returns a WP_Error for a 401 response. AiClient::isConfigured() still returns true in that case: it reports whether the site is connected, not whether the current request is allowed to use the connection.

To allow other requests, filter wpe_ai_connector_authorize_request:

add_filter(
    'wpe_ai_connector_authorize_request',
    function ( bool $authorized ): bool {
        return $authorized || my_plugin_can_use_ai();
    }
);

Connector Approvals

Section titled “Connector Approvals”

Sites can also restrict which plugins use the connector. The WordPress AI plugin has an optional Connector Approval experiment, off by default. When a site admin turns it on, calls from a plugin that hasn’t been approved to use the wpengine connector return a WP_Error with the code prompt_network_error and a message saying the connector has not been approved for that plugin. The blocked plugin then appears as a pending request under Tools → Connector Approvals, where an admin can approve it.

What it doesn’t cover

Section titled “What it doesn’t cover”

The AI Client is a provider-agnostic content-generation layer, not a full AI API client. It’s built to work against any registered AI provider, so it only exposes generation primitives generic enough to make sense across providers — it has no method surface for:

  • Token counting, transcription, image alt-text, content summarization, or taxonomy suggestion
  • Usage analytics or credit balance
  • Site registration or connection management (handled entirely by the AI Connector plugin, not the AI Client)
  • Agents, sessions, or knowledge base collections
  • The MCP transport used by external clients like Claude Code

For any of those, call the AI API directly — see the API reference for every operation.

Last updated: