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

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.

No API key in code

Once the connector is connected to a WP Engine account, it handles authentication automatically on every request. There is no Authorization header for you to set.

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();

Without a preference, the connector uses the model chosen on its settings screen (Claude Sonnet 5.5 by default). If that model can’t handle the prompt, it falls back to the newest Claude Sonnet, then Haiku, then Fable, then Gemini Flash. Web search needs a Claude model; structured output (a JSON schema) needs Gemini, because the Claude models return text only. Reorder that chain with the wpe/ai/connector/fallback_models filter:

add_filter(
    'wpe/ai/connector/fallback_models',
    function ( array $models ): array {
        // Try Haiku before Sonnet.
        usort(
            $models,
            fn ( string $a, string $b ): int =>
                (int) str_contains( $b, 'claude-haiku-' ) <=> (int) str_contains( $a, 'claude-haiku-' )
        );

        return $models;
    }
);

The filter orders models; it can’t exclude them. Any model the connector offers that isn’t in the chain still comes after it, so removing one from the chain only moves it down the list. The order is stored with the cached model list, so a change takes effect after the connector settings are saved, the plugin is updated, or the cache expires (24 hours).

The connector reports itself as unavailable when the site isn’t connected, when the current request isn’t allowed to use the connection (see Who can make requests), and for about a minute after WP Engine AI fails to list its models. Check that before showing an AI feature, so the feature is hidden 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

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

For any other request — including one made while rendering a page for an anonymous visitor — AiClient::isConfigured( 'wpengine' ) returns false and the connector is skipped when WordPress picks a model. A call pinned to the connector with using_provider( 'wpengine' ) returns a WP_Error instead of reaching WP Engine AI.

To allow other requests, filter wpe_ai_connector_authorize_request. The filter also decides whether the connector is offered at all: it is called with a GET request to v1/models for that check, so a filter that inspects the request URL must allow that request too.

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

Every authorized request uses the site’s credits

Authorizing anonymous visitors lets anyone who can reach that code path spend the site’s AI credits. Put your own rate limiting or abuse protection in front of any public-facing AI feature.

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

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.

Where to learn more

The AI Client also supports speech and text-to-speech generation with the same fluent surface. See Introducing the AI Client in WordPress 7.0 for the full builder API and provider model — that announcement post is the authoritative reference for the AI Client’s method surface, not this page.

---

Going beyond the AI Client

• API reference — every operation the AI Client does not wrap
• Getting started — call the API directly
• Authentication — the key the gateway expects