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 PHP AI SDK’s portable interface covers the parameters that are common across all providers — temperature, max tokens, top-p, structured output, and so on. Google’s Gemini API exposes many additional knobs that have no equivalent in the portable layer. The providerOptions() method gives you a direct escape hatch: you can pass any Gemini-native parameter alongside your portable request and it will be forwarded to the API without the SDK interpreting it.

​
The raw Key

Calling ->providerOptions('google', ['raw' => [...]]) on any Generate request injects a shallow merge on top of the assembled request body immediately before the HTTP call is made. Inside GoogleRequestBuilder::build(), the merge is performed with PHP’s native array_replace(): 
$raw = $request->providerOptionsFor($providerName)['raw'] ?? null;
if (is_array($raw)) {
    $body = array_replace($body, $raw);
}
array_replace() performs a shallow replacement: top-level keys in $raw overwrite the corresponding top-level keys in the request body. This means passing 'generation_config' => [...] inside raw replaces the entire generation_config object that the SDK built from your portable options. If you only want to tweak one field inside generation_config, include all the other fields you need as well, or use the sub-key examples shown below.

​
Basic Example

The following snippet overrides the temperature to 0.2 and disables request storage, both using raw passthrough: 
use AiSdk\Generate;
use AiSdk\Google;

$result = Generate::text('Hello')
    ->model(Google::model('gemini-3.5-flash'))
    ->providerOptions('google', [
        'raw' => [
            'generation_config' => ['temperature' => 0.2],
            'store' => false,
        ],
    ])
    ->run();

echo $result->text;

​
Common Use Cases

​
Override Temperature and Top-P

Use generation_config to tune sampling parameters beyond what the portable API exposes: 
->providerOptions('google', [
    'raw' => [
        'generation_config' => [
            'temperature' => 0.4,
            'top_p'       => 0.9,
            'top_k'       => 40,
        ],
    ],
])

​
Set Safety Settings

Adjust Gemini’s content-filtering thresholds per harm category: 
->providerOptions('google', [
    'raw' => [
        'safety_settings' => [
            [
                'category'  => 'HARM_CATEGORY_HATE_SPEECH',
                'threshold' => 'BLOCK_ONLY_HIGH',
            ],
            [
                'category'  => 'HARM_CATEGORY_DANGEROUS_CONTENT',
                'threshold' => 'BLOCK_MEDIUM_AND_ABOVE',
            ],
        ],
    ],
])

​
Disable Request Storage

Pass store: false to opt out of Google’s request-storage feature: 
->providerOptions('google', [
    'raw' => [
        'store' => false,
    ],
])

​
Set candidate_count

The portable SDK always requests a single candidate. If you need multiple response candidates from a single call — a feature not exposed in the portable interface — you can request them via raw passthrough: 
->providerOptions('google', [
    'raw' => [
        'candidate_count' => 3,
    ],
])
The SDK’s response parser is designed around a single candidate. When you request multiple candidates via candidate_count, you will need to handle the additional candidates in the raw HTTP response yourself; the parsed $result->text will reflect only the first candidate.

​
Image Generation Raw Passthrough

For image requests, the equivalent passthrough lives in GoogleImageRequestBuilder::build(). The key difference is that image requests use array_replace_recursive() instead of the shallow array_replace() used for text: 
$raw = $request->providerOptionsFor($providerName)['raw'] ?? null;
if (is_array($raw)) {
    $body = array_replace_recursive($body, $raw);
}
Because the merge is recursive, you can override individual nested fields inside generation_config — such as image_config — without losing sibling keys the SDK set. For example, to force a specific image configuration key alongside the SDK-managed response_modalities: 
use AiSdk\Generate;
use AiSdk\Google;

$result = Generate::image()
    ->model(Google::image('gemini-3.1-flash-image'))
    ->prompt('A clean app icon for a PHP AI SDK')
    ->providerOptions('google', [
        'raw' => [
            'generation_config' => [
                'image_config' => [
                    'guidance_scale' => 7,
                ],
            ],
        ],
    ])
    ->run();

$result->output->save(__DIR__ . '/icon.png');
With a recursive merge, the response_modalities key that the SDK placed inside generation_config is preserved; only the image_config sub-key is replaced.

​
Conflict Resolution

The raw array always wins when its keys collide with keys the SDK has already set — whether the merge is shallow (text) or recursive (image).
When a key in the raw array matches a key that the SDK already set in the request body, the raw value always wins. This applies equally to top-level keys (for text requests) and nested keys (for image requests). If you pass 'generation_config' via raw in a text request, the entire SDK-built generation_config — including max_output_tokens and temperature from portable options — is discarded and replaced by your raw value.

​
Tuning with generation_config

Gemini groups all sampling and output-control parameters under a single generation_config object in the request body. When using raw passthrough to tune any of these values, nest them inside that key rather than placing them at the top level of raw.
All of Gemini’s model-tuning parameters — temperature, top_p, top_k, max_output_tokens, candidate_count, stop_sequences, presence_penalty, frequency_penalty, and thinking_level — are nested under the generation_config key in the Gemini API’s request body. When using raw passthrough to tune these values, always group them inside 'generation_config' => [...] rather than placing them at the top level of the raw array.

Build docs developers (and LLMs) love

Get started for freeTalk to us