В WordPress 7.0 появился встроенный PHP-клиент для работы с AI-провайдерами. В этой инструкции мы разберём архитектуру AI Client и на практическом примере соберём плагин, который генерирует изображения в медиабиблиотеке: от построения промпта и REST-эндпоинтов до подключения интерфейса и загрузки файла.
Как устроен WordPress AI Client: архитектура и ключевые принципы
WordPress AI Client построен так, чтобы плагин никогда не обращался к AI-провайдеру напрямую. Вы описываете, что нужно получить — текст, изображение, конкретный выходной формат — и как это должно выглядеть: пропорции для картинки, температура для текста и так далее. На основе этих требований WordPress сам направляет запрос к подходящей модели у провайдера, которого настроил владелец сайта.
Такой подход даёт несколько практических преимуществ. Владелец сайта сохраняет контроль: он выбирает провайдера и управляет API-ключами через экран «Настройки → Connectors», поэтому плагину не нужна собственная страница настроек для учётных данных. Плагин становится переносимым: код, работающий с одним провайдером, работает и с остальными. Наконец, экосистема масштабируется: когда появляются новые провайдеры и модели, существующие плагины получают их поддержку автоматически, без обновлений.
Из этого следует главное правило: не пишите код, который предполагает работу с конкретным провайдером или моделью. Описывайте требования, а подходящее совпадение найдёт AI Client.
Точка входа: wp_ai_client_prompt
Любое взаимодействие с AI Client начинается с одного вызова:
$builder = wp_ai_client_prompt();
Функция возвращает экземпляр WP_AI_Client_Prompt_Builder — fluent-строителя, который следует соглашениям WordPress об именовании методов в snake_case и оборачивает базовую библиотеку php-ai-client.
Дальше вы цепочкой вызываете методы, описывающие запрос. Пример для генерации текста:
$builder = wp_ai_client_prompt()
->with_text( 'Summarize the benefits of caching in WordPress' )
->using_temperature( 0.7 );
Метод with_text устанавливает сам промпт. Метод using_temperature задаёт необязательный параметр, управляющий случайностью вывода. Когда всё готово, вызывается метод генерации:
$result = $builder->generate_text_result();
Переменная $result содержит объект GenerativeAiResult — сериализуемый DTO, в котором лежат сгенерированный контент и метаданные о том, какой провайдер и модель обработали запрос. Его можно напрямую передать в rest_ensure_response, что упрощает предоставление AI-функций через REST API. Тот же паттерн строителя используется и для генерации изображений — именно он лежит в основе плагина из этой статьи.
Предпочтения моделей, а не жёсткие требования
Плагин не контролирует, какой провайдер и модель доступны на каждом конкретном сайте. Поэтому AI Client использует систему предпочтений, а не строгих требований к моделям.
Метод using_model_preference принимает один или несколько slug моделей, которые считаются оптимальными для вашей задачи. AI Client пробует их по порядку: если первая доступна, используется она; если нет — следующая. Если ни одна из предпочтительных моделей не найдена, выбирается любая модель, поддерживающая запрошенную возможность. Плагин в любом случае продолжает работать.
$builder = wp_ai_client_prompt()
->with_text( 'Summarize the benefits of caching in WordPress' )
->using_temperature( 0.7 )
->using_model_preference( 'gpt-5.4', 'gemini-3.1-pro-preview', 'claude-opus-4.6' );
Это именно предпочтение, а не условие. Привязка к конкретной модели навязывает пользователям плагина зависимость от одного вендора или вообще не даёт им воспользоваться плагином. Используйте предпочтения моделей, когда определённая модель особенно хорошо справляется с вашей задачей, но проектируйте плагин так, чтобы он работал и без неё.
Проверки поддержки: показывайте AI-функции только там, где они работают
Не на каждом сайте настроен AI-провайдер, и не каждый провайдер поддерживает все возможности и параметры конфигурации. Прежде чем показывать пользователю AI-функцию, нужно проверить, сможет ли она реально выполниться.
$is_available = wp_ai_client_prompt()
->with_text( 'test' )
->is_supported_for_image_generation();
Метод is_supported_for_image_generation возвращает true, только если на сайте есть настроенный провайдер с моделью, поддерживающей генерацию изображений. Для текстовой генерации существуют аналогичные методы.
Важная деталь: проверка поддержки не выполняет API-запрос и не проводит инференс. Сам текст промпта для этой проверки не анализируется. Метод работает детерминированно: он сопоставляет конфигурацию строителя — запрошенную возможность, параметры вывода и другие опции — с возможностями, заявленными доступными моделями. Вызов не создаёт никаких расходов.
Такая проверка необходима. С её помощью можно условно загружать интерфейс, показывать уведомление о недоступности функции или вообще не регистрировать элементы UI. Никогда не предполагайте, что AI-функции доступны только потому, что установлен WordPress 7.0: владельцу сайта всё равно нужно настроить провайдера.
Реализация плагина генерации изображений
Плагин добавляет в медиабиблиотеку кнопку «Generate Image File». По клику открывается диалог, в котором пользователь вводит текстовый промпт. Плагин отправляет его в AI Client, показывает сгенерированное изображение как предпросмотр и позволяет сохранить его как новое вложение медиабиблиотеки. Полный исходный код доступен в репозитории wptrainingteam/ai-client-imagegen на GitHub.
Подготовка окружения
Для повторения примера понадобятся установленный и запущенный WordPress 7.0 или новее; настроенный AI-провайдер с поддержкой генерации изображений — его можно добавить в разделе «Настройки → Connectors», например OpenAI или Google AI, при этом у провайдера должна быть хотя бы одна модель, способная генерировать изображения; Node.js версии 20 или новее для сборки фронтенд-ассетов. Также нужно базовое понимание разработки плагинов WordPress, REST API и PHP.
Структура файлов плагина
Плагин использует простую структуру:
ai-client-imagegen/
├── plugin.php
├── includes/
│ ├── prompt.php
│ ├── rest-api.php
│ └── admin.php
├── src/
│ └── index.ts
├── build/
│ ├── index.js
│ └── index.asset.php
├── package.json
└── composer.json
Файл plugin.php — основная точка входа: он загружает остальные файлы и регистрирует хуки. В includes/prompt.php находятся переиспользуемые функции для построения промптов AI Client. В includes/rest-api.php — REST-эндпоинты для генерации изображений и сохранения их в медиабиблиотеку. includes/admin.php отвечает за регистрацию скриптов и их подключение на экране медиабиблиотеки. src/index.ts — фронтенд: интерфейс диалога и вызовы API. Каталог build содержит скомпилированный JavaScript, который создаётся инструментами @wordpress/scripts.
Главный файл плагина
Файл plugin.php минимален: он объявляет заголовок плагина, проверяет доступность AI Client, подключает файлы с кодом и регистрирует хуки. Указание «Requires at least: 7.0» в заголовке не даст WordPress активировать плагин на более старых версиях. Проверка function_exists( ‘wp_ai_client_prompt’ ) служит дополнительной страховкой на этапе выполнения: если функция AI Client по какой-то причине недоступна, плагин сразу завершает работу. Три вызова add_action подключают маршруты REST API, регистрацию ассетов и условное подключение скриптов.
Построение промпта
Ядро интеграции с AI Client находится в includes/prompt.php. Файл определяет переиспользуемую функцию, которая настраивает строителя промпта для генерации изображений.
Функция возвращает строителя, а не результат — это осознанное проектное решение. Вызывающий код сам решает, когда выполнить промпт через generate_image_result, и может добавить дополнительную конфигурацию. Кроме того, тот же строитель используется для проверок поддержки: эта же функция вызывается позже с методом is_supported_for_image_generation в коде админки.
Значение FileTypeEnum::inline запрашивает в ответе base64-закодированные данные изображения. Это удобно, когда плагину нужно показать картинку в браузере до сохранения. Параметр MediaOrientationEnum необязателен: он задаёт желаемые пропорции — квадрат, альбомную или портретную ориентацию. Метод MediaOrientationEnum::from преобразует строку в значение enum. Провайдер и модель не указываются: маршрутизацией занимается AI Client. Промпт описывает, что нужно получить, а WordPress решает, как это выполнить. Такая функция будет работать с любым провайдером, поддерживающим генерацию изображений.
Вынос конфигурации промпта в отдельную функцию делает её переиспользуемой: REST API вызывает её для генерации изображений, а код админки — для проверки доступности этой функции.
REST API плагина
Плагин предоставляет два REST-эндпоинта в пространстве имён ai-client-imagegen/v1: один генерирует изображение, второй загружает сгенерированную картинку в медиабиблиотеку. Можно было бы объединить обе операции в одном эндпоинте, но пользователь должен иметь возможность сначала просмотреть изображение и только потом сохранить его, поэтому разделение на два шага логичнее.
Генерация изображения
Маршрут генерации принимает текстовый промпт и необязательную ориентацию. Колбэк использует переиспользуемую функцию промпта из includes/prompt.php, вызывает generate_image_result и сразу возвращает результат.
Функция регистрации маршрута объявляет параметры: prompt — обязательная строка; orientation — необязательная строка с допустимыми значениями square, landscape и portrait. Права доступа проверяются по capability upload_files.
Поскольку объект GenerativeAiResult, который возвращает generate_image_result, сериализуем, rest_ensure_response превращает его непосредственно в JSON-ответ. В ответе содержатся сами данные изображения и метаданные о провайдере и модели — фронтенд может показывать их как атрибуцию. Если в процессе возникает ошибка, generate_image_result возвращает WP_Error, и её тоже можно обработать как REST-ответ напрямую, без условной логики.
Загрузка в медиабиблиотеку
Когда пользователя устраивает результат, фронтенд отправляет данные на второй эндпоинт. Маршрут принимает base64-закодированное изображение, имя файла и MIME-тип. Колбэк декодирует данные, записывает их на диск и создаёт вложение WordPress.
В обработчике сначала выполняется строгая проверка base64-декодирования: если данные некорректны, возвращается WP_Error с кодом 400. Затем функция wp_upload_bits записывает файл, а wp_insert_attachment создаёт запись в базе данных. После этого вызываются wp_generate_attachment_metadata и wp_update_attachment_metadata для создания миниатюр и метаданных изображения.
Это стандартная обработка медиафайлов WordPress, и ничего специфичного для AI здесь нет. На этом серверная часть функции завершена.
Интеграция с админкой
PHP-код фронтенду нужен только для управления скриптом, который отвечает за динамический интерфейс и взаимодействия. Файл includes/admin.php решает три задачи: регистрирует скрипт, условно подключает его на экране медиабиблиотеки и показывает уведомление, когда генерация изображений не поддерживается.
Регистрация скрипта
Функция регистрации сначала загружает build/index.asset.php, если он существует. Этот файл автоматически создаётся @wordpress/scripts на этапе сборки и содержит зависимости скрипта и хеш версии, основанный на содержимом. Если файла нет, используются запасные значения: пустой массив зависимостей и версия «1.0.0». Сам скрипт регистрируется вызовом wp_register_script с путём к build/index.js и стратегией defer.
Условное подключение с проверкой поддержки
Подключение скрипта выполняется только после нескольких проверок. Сначала проверяется экран: функция выполняется только на странице upload.php, то есть в медиабиблиотеке. Затем — права пользователя: только те, кто может загружать файлы. Важно использовать ту же capability, что и в REST-эндпоинтах, чтобы UI закрывался по тем же критериям, по которым работает серверная часть. Иначе можно отобразить интерфейс для действия, которое фактически не выполнится.
Третья проверка — поддержка генерации изображений. Для неё вызывается is_supported_for_image_generation на строителе промпта. Если настроенный провайдер не может генерировать изображения, функция завершает работу досрочно; в этом случае стоит показать уведомление, которое укажет владельцу сайта на настройки Connectors.
Здесь переиспользуется та же функция aicig_get_image_generation_prompt из includes/prompt.php. Текста «test» в качестве промпта достаточно: метод проверяет только возможности провайдера и модели, а не содержимое запроса. Именно поэтому функция возвращает строителя, а не финальный результат, — так её можно применять и для генерации, и для проверки поддержки. Скрипт подключается только при выполнении всех трёх условий, поэтому кнопка «Generate Image File» появляется лишь тогда, когда функция действительно будет работать.
Фронтенд, сборка и проверка
Фронтенд-код в src/index.ts — это около 590 строк обычной работы с DOM на TypeScript. Он создаёт модальное окно, обрабатывает отправку формы через @wordpress/api-fetch, показывает предпросмотр сгенерированного изображения с атрибуцией провайдера и модели и сохраняет файл в медиабиблиотеку. Глубокий разбор этого кода выходит за рамки материала, поэтому достаточно взять его из репозитория wptrainingteam/ai-client-imagegen и положить в локальный src/index.ts. После сборки он появится как build/index.js — по тому же пути, который зарегистрирован в PHP.
Клиентский код написан на ванильном JavaScript без фреймворковых зависимостей, кроме @wordpress/api-fetch и @wordpress/i18n. Для автономного диалога такой подход лёгкий и производительный. Для более сложных интерфейсов плагина лучше подойдёт встроенная в WordPress версия React.
Для сборки фронтенда в корне плагина нужны два конфигурационных файла. Первый — package.json — объявляет инструменты сборки и зависимости: @wordpress/api-fetch, @wordpress/i18n, @wordpress/env, @wordpress/scripts и typescript. Скрипты сборки задают команды build для wp-scripts build и wp-env для wp-env. Второй файл — .wp-env.json — запускает локальное окружение WordPress 7.0 с уже активированным плагином через wp-env. Для этого понадобится Node.js, а для встроенного окружения на основе @wordpress/env — ещё и Docker. Если Docker недоступен, можно использовать любую другую среду разработки.
После установки зависимостей команда npm run build запускает @wordpress/scripts, которая компилирует src/index.ts в build/index.js и генерирует build/index.asset.php. PHP-часть отдельного шага сборки не требует: AI Client — часть ядра WordPress.
Для проверки плагина окружение запускается командой npm run wp-env. По умолчанию сайт доступен на http://localhost:8888 с учётными данными admin и password. Дальше нужно перейти в «Настройки → Connectors» и настроить AI-провайдера с поддержкой генерации изображений, затем открыть «Медиафайлы → Библиотека», нажать «Generate Image File», ввести промпт и сгенерировать изображение. Когда результат устроит, нажать «Save to Media Library»; при желании можно изменить имя файла. Если вместо кнопки отображается уведомление о недоступности, значит настроенный провайдер не поддерживает генерацию изображений — нужно проверить настройки Connectors.
Итог и направления развития
Если посмотреть на код плагина, AI-часть оказывается совсем небольшой. Функция-строитель промпта в includes/prompt.php занимает около десяти строк, REST-колбэк с вызовом generate_image_result — ещё несколько. Остальное — стандартная разработка WordPress: регистрация REST API, работа с медиафайлами, подключение скриптов, проверки прав. В этом и смысл: WordPress AI Client берёт на себя сложность общения с провайдерами, аутентификацию, выбор модели и нормализацию ответов. Плагин сосредотачивается на собственной задаче, а AI-часть остаётся просто вызовом API.
Статья показывает базовый сценарий генерации изображений, но на нём можно строить дальше. Например, добавить редактирование существующего изображения по пользовательскому запросу. Функция промпта для редактирования почти не отличается от генерации: к тексту добавляется вызов with_file, который передаёт исходное изображение как объект File, а AI Client сам направляет запрос к провайдеру и модели с поддержкой редактирования изображений.
Среди других возможных улучшений — генерация нескольких вариантов изображения на один промпт, чтобы пользователь выбрал лучший; создание описательного имени файла через текстовую генерацию AI Client вместо программно заполненного поля; интеграция с уже загруженными в медиабиблиотеку изображениями через поле промпта и кнопку редактирования. Для более широкого примера профессионального AI-плагина на основе нового AI Client стоит посмотреть официальный WordPress AI plugin.
Источники и материалы
How to build an image generation plugin with the WordPress AI Client