wordpress / ai-provider-for-google
AI Provider for Google for the PHP AI Client SDK. Works as both a Composer package and WordPress plugin.
Package info
github.com/WordPress/ai-provider-for-google
pkg:composer/wordpress/ai-provider-for-google
Requires
- php: >=7.4
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- phpcompatibility/php-compatibility: dev-develop
- phpstan/phpstan: ~2.1
- phpunit/phpunit: ^9.6
- slevomat/coding-standard: ^8.20
- squizlabs/php_codesniffer: ^3.7 || ^4.0
- wordpress/php-ai-client: ^1.3.1
Suggests
- wordpress/php-ai-client: Required. The core PHP AI Client SDK that this provider extends.
Provides
None
Conflicts
None
Replaces
None
README
A Google AI (Gemini) provider for the PHP AI Client SDK. Works as both a Composer package and a WordPress plugin.
Requirements
- PHP 7.4 or higher
- When using with WordPress, requires WordPress 7.0 or higher
- If using an older WordPress release, the wordpress/php-ai-client package must be installed
Installation
As a Composer Package
composer require wordpress/ai-provider-for-google
As a WordPress Plugin
- Download the plugin files
- Upload to
/wp-content/plugins/ai-provider-for-google/ - Ensure the PHP AI Client plugin is installed and activated
- Activate the plugin through the WordPress admin
Usage
With WordPress
The provider automatically registers itself with the PHP AI Client on the init hook. Simply ensure both plugins are active and configure your API key:
// Set your Google API key (or use the GOOGLE_API_KEY environment variable) putenv('GOOGLE_API_KEY=your-api-key'); // Use the provider $result = AiClient::prompt('Hello, world!') ->usingProvider('google') ->generateTextResult();
As a Standalone Package
use WordPress\AiClient\AiClient; use WordPress\GoogleAiProvider\Provider\GoogleProvider; // Register the provider $registry = AiClient::defaultRegistry(); $registry->registerProvider(GoogleProvider::class); // Set your API key putenv('GOOGLE_API_KEY=your-api-key'); // Generate text $result = AiClient::prompt('Explain quantum computing') ->usingProvider('google') ->generateTextResult(); echo $result->toText();
Generating Embeddings
Embedding generation always requires you to name a model. Vectors are only comparable to other vectors produced by the same model, so a stored corpus is permanently tied to the model that created it — letting the library pick could silently invalidate embeddings you already saved.
use WordPress\AiClient\AiClient; use WordPress\GoogleAiProvider\Provider\GoogleProvider; // Generate a single embedding. $embedding = AiClient::input('PHP powers a large part of the web.') ->usingModel(GoogleProvider::model('gemini-embedding-001')) ->generateEmbedding(); $values = $embedding->getValues(); // Generate embeddings for multiple inputs in a single batch. $embeddings = AiClient::input([ 'PHP powers a large part of the web.', 'WordPress makes publishing accessible.', ]) ->usingModel(GoogleProvider::model('gemini-embedding-001')) ->generateEmbeddings(); // Request a specific number of output dimensions. $embedding = AiClient::input('PHP powers a large part of the web.') ->usingModel(GoogleProvider::model('gemini-embedding-001')) ->usingDimensions(512) ->generateEmbedding();
Multimodal Embeddings
The gemini-embedding-2 model embeds images, audio, video and PDF documents in addition to text,
mapping every modality into the same vector space. That means a text embedding can be compared
directly against an image embedding, which is what makes cross-modal search possible.
use WordPress\AiClient\Files\DTO\File; // Embed an image. Remote URLs, such as WordPress attachment URLs, are passed through directly. $embedding = AiClient::input(new File(wp_get_attachment_url($attachment_id))) ->usingModel(GoogleProvider::model('gemini-embedding-2')) ->generateEmbedding(); // Embed a local file instead. The file is read and sent inline as base64 data. $embedding = AiClient::input(new File(get_attached_file($attachment_id))) ->usingModel(GoogleProvider::model('gemini-embedding-2')) ->generateEmbedding(); // Text and media can be mixed in a single batch. One embedding is returned per input, in order. $embeddings = AiClient::input([ 'A golden retriever running on a beach.', new File('https://example.com/dog-on-beach.jpg'), new File('https://example.com/clip.mp4'), ]) ->usingModel(GoogleProvider::model('gemini-embedding-2')) ->generateEmbeddings();
Remote URLs are fetched by Google, not by your server, so they must be publicly reachable. URLs on
a localhost, staging or password-protected site, or behind a login, will fail. In those cases, pass
a local file path (such as the result of get_attached_file()) or a base64 data URI instead, so the
file contents are sent inline with the request. Google limits remote URLs to 15 MB per file and
inline data to 100 MB per request (50 MB for PDFs); see Google's
file input methods documentation.
Input modalities are advertised per model, so the model you name is matched against the inputs you
provide. Passing an image to a text-only model such as gemini-embedding-001 is rejected. On PHP AI
Client versions that validate the named model, this happens locally before any request is sent, with
a message naming the unsupported option:
Model "gemini-embedding-001" from provider "google" cannot fulfill this embedding request.
Unsupported options: inputModalities ([image]).
Supported input per model:
| Model | Text | Image | Audio | Video | |
|---|---|---|---|---|---|
gemini-embedding-2 |
Yes | Yes | Yes | Yes | Yes |
gemini-embedding-001 |
Yes | No | No | No | No |
A few Google-specific notes:
- Each input produces its own embedding. Combining several parts into a single fused vector is not currently expressible through the PHP AI Client.
taskTypeis honored bygemini-embedding-001but ignored bygemini-embedding-2; for the latter, describe the task in the input text instead.gemini-embedding-2normalizes truncated dimension vectors automatically, whilegemini-embedding-001requires callers to renormalize them.gemini-embedding-2reports token usage on the embedding result;gemini-embedding-001does not, and reports zero.
Supported Models
Available models are dynamically discovered from the Google AI API. This includes Gemini models for text generation (with multimodal input support), Imagen models for image generation, embedding models (such as gemini-embedding-2 for multimodal embeddings and gemini-embedding-001 for text-only embeddings), and Text to Speech generation. See the Google AI documentation for the full list of available models.
Configuration
The provider uses the GOOGLE_API_KEY environment variable for authentication. You can set this in your environment or via PHP:
putenv('GOOGLE_API_KEY=your-api-key');
Maintainers
Maintainers for this repo are David Stone (@superdav42), Felix Arntz (@felixarntz), Jason Adams (@JasonTheAdams), Jeffrey Paul (@jeffpaul), and Lauri Saarni (@saarnilauri); all can be reached using the @WordPress/ai-provider-for-google-maintainers team.
License
GPL-2.0-or-later