Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/google/llms.txt

Use this file to discover all available pages before exploring further.

The aisdk/google provider authenticates every request to the Gemini API by attaching your API key as the x-goog-api-key HTTP header. This header is constructed inside GoogleOptions::authHeaders(), which merges the resolved key with any extra headers you supply, and is sent automatically on every outbound request — you never need to set it manually.

​
Environment Variables

The recommended way to supply credentials in any environment is through environment variables. The provider reads the following variables at runtime:
VariableDescriptionRequired
GOOGLE_GENERATIVE_AI_API_KEYPrimary Gemini API keyYes (or GEMINI_API_KEY)
GEMINI_API_KEYFallback API key variableYes (or GOOGLE_GENERATIVE_AI_API_KEY)
GOOGLE_GENERATIVE_AI_BASE_URLOverride the API base URLNo
At least one of the two key variables must be set. Both are checked so you can migrate between naming conventions without code changes.

​
Key Resolution Order

When GoogleOptions::fromArray() is called, the provider resolves the API key using the following precedence — the first non-empty value wins:
  1. Explicit apiKey in the config array — value passed directly to Google::create(['apiKey' => '...']).
  2. GEMINI_API_KEY environment variable — checked via $_ENV, $_SERVER, and getenv().
  3. GOOGLE_GENERATIVE_AI_API_KEY environment variable — the canonical variable name, resolved last via the SDK’s Env::loadApiKey() helper.
If none of the three sources yield a non-empty string, the provider throws an exception at construction time, before any HTTP request is made.

​
Programmatic Configuration

You can also configure the provider directly in code using Google::create(). This is useful in tests, multi-tenant applications, or situations where credentials come from a secret manager rather than the process environment: 
use AiSdk\Google;

Google::create([
    'apiKey'  => 'your-gemini-api-key',
    'baseUrl' => 'https://generativelanguage.googleapis.com/v1beta',
]);
The Google::create() call constructs a GoogleProvider by passing your config array to GoogleOptions::fromArray() and stores it as the default provider instance for the current process. Subsequent calls to Google::model() and Google::image() use this instance automatically. All supported keys in the config array:
KeyTypeDescription
apiKeystringExplicit API key — takes highest precedence over env vars
baseUrlstringOverride the base URL for all requests
headersarray<string, string>Extra HTTP headers merged into every request
sdkSdk|nullOptional SDK instance for advanced HTTP configuration

​
Custom Headers

If you need to attach additional HTTP headers to every request — for example, a proxy token, a request-tracing ID, or an internal audit header — pass a headers array to Google::create(): 
use AiSdk\Google;

Google::create([
    'apiKey'  => getenv('GEMINI_API_KEY'),
    'headers' => [
        'x-request-id'  => 'my-trace-id-123',
        'x-internal-env' => 'production',
    ],
]);
Internally, GoogleOptions::authHeaders() calls array_merge(['x-goog-api-key' => $this->apiKey], $this->headers), meaning the API key header is always present and your custom headers are appended after it. If you supply a key that conflicts with x-goog-api-key, your value will override it — so take care not to accidentally clobber authentication.

​
Base URL Override

The provider defaults to https://generativelanguage.googleapis.com/v1beta for all API calls. You can replace this with any compatible endpoint — a local proxy, a corporate gateway, or a test server — using either the environment variable or the config array key.
Both the GOOGLE_GENERATIVE_AI_BASE_URL environment variable and the baseUrl config key are supported. The config key takes precedence over the environment variable. Trailing slashes are stripped automatically from whichever value is used.
use AiSdk\Google;

// Override via config array
Google::create([
    'apiKey'  => getenv('GEMINI_API_KEY'),
    'baseUrl' => 'https://my-gemini-proxy.example.com/v1beta',
]);

# Or set the environment variable
export GOOGLE_GENERATIVE_AI_BASE_URL=https://my-gemini-proxy.example.com/v1beta
Never hardcode API keys directly in source code. If a key is committed to version control it is effectively public, even in private repositories, and must be rotated immediately. Always read credentials from environment variables, a secrets manager, or a vault service in production deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us