Gemini PHP

https://github.com/google-gemini-php/client
Admin
A community-maintained PHP API client for interacting with the Gemini AI API, supporting various...
Tokens:149,732
Snippets:1,063
Trust Score:6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dev dependencies with composer install

Source: https://github.com/google-gemini-php/client/blob/main/CONTRIBUTING.md

Run this command after cloning your fork to install the project's development dependencies. It is the first setup step before linting or testing.

```bash
composer install
```

--------------------------------

### startChat usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/generative-model.md

Example of starting a chat with initial history and sending a message. Uses the 'gemini-2.0-flash' model with a tool and Content::parse for history entries.

```php
use Gemini\Data\Content;
use Gemini\Enums\Role;

$chat = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withTool($tool)
    ->startChat(history: [
        Content::parse(part: 'The stories you write should be one line. Is that clear?'),
        Content::parse(part: 'Yes.', role: Role::MODEL),
    ]);

$response = $chat->sendMessage('Create a story…');
```

--------------------------------

### Content usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-content.md

Example of creating Content instances using the parse method with different roles.

```php
use Gemini\Data\Content;
use Gemini\Enums\Role;

$content = Content::parse('The stories you write should be one line. Is that clear?');
$modelTurn = Content::parse('Yes, I understand.', role: Role::MODEL);
```

--------------------------------

### Upload example with polling

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/files.md

Example of uploading a video file and polling until it is ready, handling failure states.

```php
use Gemini\Enums\FileState;
use Gemini\Enums\MimeType;

$files = $client->files();
$meta = $files->upload(filename: 'video.mp4', mimeType: MimeType::VIDEO_MP4, displayName: 'Video');

do {
    sleep(2);
    $meta = $files->metadataGet($meta->uri);
} while (! $meta->state->complete()); // FileState::complete() — see types.md

if ($meta->state == FileState::Failed) {
    throw new RuntimeException('Upload failed: '.json_encode($meta->toArray()));
}
echo $meta->uri;
```

--------------------------------

### FileSearch usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-tools.md

Example of creating a Tool with a FileSearch instance, specifying file search store names and a metadata filter.

```php
use Gemini\Data\FileSearch;
use Gemini\Data\Tool;

$tool = new Tool(fileSearch: new FileSearch(
    fileSearchStoreNames: ['files/my-document-store'],
    metadataFilter: 'author = "Robert Graves"',
));
```

--------------------------------

### Multi-turn chat with startChat and sendMessage

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Multi-turn conversation example: start a chat with history using Content::parse and Role::MODEL, then send messages and print the text responses. Shows how to build freeform conversations across multiple turns.

```php
use Gemini\Data\Content;
use Gemini\Enums\Role;

$chat = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->startChat(history: [
        Content::parse(part: 'The stories you write about what I have to say should be one line. Is that clear?'),
        Content::parse(part: 'Yes, I understand. The stories I write about your input should be one line long.', role: Role::MODEL)
    ]);

$response = $chat->sendMessage('Create a story set in a quiet village in 1600s France');
echo $response->text(); // Amidst rolling hills and winding cobblestone streets, the tranquil village of Beausoleil whispered tales of love, intrigue, and the magic of everyday life in 17th century France.

$response = $chat->sendMessage('Rewrite the same story in 1600s England');
echo $response->text(); // In the heart of England's lush countryside, amidst emerald fields and thatched-roof cottages, the village of Willowbrook unfolded a tapestry of love, mystery, and the enchantment of ordinary days in the 17th century.
```

--------------------------------

### GenerateContentResponse usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/responses.md

Example of generating content and accessing the text, checking prompt feedback, and printing JSON.

```php
$result = $client->generativeModel('gemini-2.0-flash')->generateContent('Hello');

echo $result->text();

if ($result->promptFeedback?->blockReason !== null) {
    // prompt was blocked
}

print_r($result->json(associative: true));
```

--------------------------------

### Delete file example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/files.md

Example of deleting a file using its name or URI.

```php
$client->files()->delete('files/abc123');
// or: $client->files()->delete($file->uri);
```

--------------------------------

### Basic generateContent example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/generative-model.md

Sends a simple text prompt 'Hello' to the gemini-2.0-flash model and prints the response text.

```php
$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');
echo $result->text();
```

--------------------------------

### Install Gemini PHP client with Composer

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Installs the Gemini PHP client via Composer. Requires PHP 8.1 or higher. Ensure the php-http/discovery plugin is allowed or install a PSR-18 client manually.

```bash
composer require google-gemini-php/client
```

--------------------------------

### Install Guzzle HTTP client

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Installs Guzzle as a PSR-18 HTTP client if your project does not already have one integrated.

```bash
composer require guzzlehttp/guzzle
```

--------------------------------

### streamGenerateContent usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/generative-model.md

Example of streaming a response from the 'gemini-2.0-flash' model. Iterates over the StreamResponse and prints each response text.

```php
$stream = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->streamGenerateContent('Write long a story about a magic backpack.');

foreach ($stream as $response) {
    echo $response->text();
}
```

--------------------------------

### Usage example with GenerationConfig

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-generation-config.md

Shows how to instantiate GenerationConfig with common parameters and pass it to a generative model. Uses ResponseMimeType::APPLICATION_JSON for structured output.

```php
use Gemini\Data\GenerationConfig;
use Gemini\Enums\ResponseMimeType;

$generationConfig = new GenerationConfig(
    stopSequences: ['Title'],
    maxOutputTokens: 800,
    temperature: 1,
    topP: 0.8,
    topK: 10,
    responseMimeType: ResponseMimeType::APPLICATION_JSON,
);
$client->generativeModel('gemini-2.0-flash')->withGenerationConfig($generationConfig)->generateContent('…');
```

--------------------------------

### Create cached content example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/cached-contents.md

Example of creating cached content using the CachedContents create method with a model, system instruction, parts, TTL, and display name. Outputs the cached content name.

```php
use Gemini\Data\Content;

$cached = $client->cachedContents()->create(
    model: 'gemini-2.0-flash',
    systemInstruction: Content::parse('You are an expert PHP developer.'),
    parts: ['This is a large codebase…', 'File 1 contents…'],
    ttl: '3600s',
    displayName: 'PHP Codebase Cache',
);
echo $cached->cachedContent->name;
```

--------------------------------

### Using GoogleSearch with Tool

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-tools.md

Example of using the GoogleSearch tool with the Gemini client to generate content. Creates a Tool with googleSearch and passes it to the model.

```php
use Gemini\Data\GoogleSearch;
use Gemini\Data\Tool;

$response = $client->generativeModel('gemini-2.0-flash')
    ->withTool(new Tool(googleSearch: GoogleSearch::from()))
    ->generateContent('Who won the Euro 2024?');
```

--------------------------------

### batchEmbedContents usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/embedding-model.md

Example of calling batchEmbedContents with two string inputs and iterating over the resulting embeddings to print their values.

```php
$response = $client
    ->embeddingModel('text-embedding-004')
    ->batchEmbedContents('Bu bir testtir', 'Deneme123');

foreach ($response->embeddings as $embedding) {
    print_r($embedding->values);
}
```

--------------------------------

### Using GoogleMaps with ToolConfig

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-tools.md

Example of using the GoogleMaps tool with a ToolConfig containing RetrievalConfig. Creates a tool and tool config, then generates content with the model.

```php
use Gemini\Data\GoogleMaps;
use Gemini\Data\RetrievalConfig;
use Gemini\Data\Tool;
use Gemini\Data\ToolConfig;

$tool = new Tool(googleMaps: new GoogleMaps(enableWidget: true));
$toolConfig = new ToolConfig(retrievalConfig: new RetrievalConfig(latitude: 40.758896, longitude: -73.985130));

$client->generativeModel('gemini-2.0-flash')
    ->withTool($tool)
    ->withToolConfig($toolConfig)
    ->generateContent('Find coffee shops near me');
```

--------------------------------

### get store method

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Retrieves a file search store by its full resource name (e.g., fileSearchStores/my-search-store). Sends GET {name}. Returns FileSearchStoreResponse.

```php
public function get(string $name): FileSearchStoreResponse
```

--------------------------------

### List models with pagination

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/models.md

Example of listing models with pagination. It retrieves the first page with a page size of 3, iterates over the models, and if a nextPageToken is present, fetches the next page.

```php
$response = $client->models()->list(pageSize: 3);

foreach ($response->models as $model) {
    echo "{$model->name} ({$model->displayName})\n";
}

if ($response->nextPageToken) {
    $nextPage = $client->models()->list(pageSize: 3, nextPageToken: $response->nextPageToken);
}
```

--------------------------------

### GET files

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Lists files.

```APIDOC
## GET files

### Description
Lists files.

### Method
GET

### Endpoint
`files`

### Parameters
#### Query Parameters
- **pageSize** (int) - Optional - The maximum number of files to return. API default is 10, max is 100.
- **nextPageToken** (string) - Optional - A token to retrieve the next page of results.

### Response
#### Success Response (200)
- **files** (array) - List of file metadata objects.
- **nextPageToken** (string) - Optional - Token for the next page.

#### Response Example
```json
{
  "files": [
    {
      "name": "files/abc123",
      "displayName": "myfile.txt",
      "mimeType": "text/plain",
      "sizeBytes": "12345",
      "createTime": "2023-01-01T00:00:00Z",
      "updateTime": "2023-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "..."
}
```
```

--------------------------------

### Basic two-turn conversation with startChat and sendMessage

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/chat-session.md

Shows how to start a chat and send two messages in sequence. Each sendMessage appends to history and returns a response whose text is echoed.

```php
$chat = $client->generativeModel(model: 'gemini-2.0-flash')->startChat();

$response = $chat->sendMessage('Create a story set in a quiet village in 1600s France');
echo $response->text();

$response = $chat->sendMessage('Rewrite the same story in 1600s England');
echo $response->text();
```

--------------------------------

### GET models

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Lists available models and their metadata.

```APIDOC
## GET models

### Description
Lists available models and their metadata.

### Method
GET

### Endpoint
`models`

### Parameters
#### Query Parameters
- **pageSize** (int) - Optional - The maximum number of models to return.
- **nextPageToken** (string) - Optional - A token to retrieve the next page of results.

### Response
#### Success Response (200)
- **models** (array) - List of model objects with fields: name, version, displayName, description, inputTokenLimit, outputTokenLimit, supportedGenerationMethods, baseModelId (optional), temperature (optional), maxTemperature (optional), topP (optional), topK (optional).
- **nextPageToken** (string) - Optional - Token for the next page.

#### Response Example
```json
{
  "models": [
    {
      "name": "models/gemini-2.5-pro-preview-05-06",
      "version": "1.0",
      "displayName": "Gemini 2.5 Pro Preview",
      "description": "...",
      "inputTokenLimit": 1000000,
      "outputTokenLimit": 8192,
      "supportedGenerationMethods": ["generateContent"]
    }
  ],
  "nextPageToken": "..."
}
```
```

--------------------------------

### Text-and-video input with UploadedFile

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Text-and-video input example: process video content by providing an UploadedFile with a file URI and MIME type VIDEO_MP4. The fileUri accepts just the name or the full URI.

```php
use Gemini\Data\UploadedFile;
use Gemini\Enums\MimeType;

$result = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->generateContent([
        'What is this video?',
        new UploadedFile(
            fileUri: '123-456', // accepts just the name or the full URI
            mimeType: MimeType::VIDEO_MP4
        )
    ]);

$result->text(); //  The video shows...
```

--------------------------------

### Using generativeModel() to generate content

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/client.md

Example usage of the generativeModel() method. It creates a client with an API key, selects the 'gemini-2.0-flash' model, generates content from the prompt 'Hello', and prints the resulting text.

```php
use Gemini;

$client = Gemini::client($apiKey);
$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');
echo $result->text();
```

--------------------------------

### Retrieve a model and access its properties

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/models.md

Example of retrieving a model and accessing its input token limit.

```php
$response = $client->models()->retrieve('models/gemini-2.5-pro-preview-05-06');
echo $response->model->inputTokenLimit;
```

--------------------------------

### Text-only input with generateContent

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Text-only input example: generate a response from the model given an input message. Uses the gemini-2.0-flash model and prints the text response.

```php
use Gemini;

$yourApiKey = getenv('YOUR_API_KEY');
$client = Gemini::client($yourApiKey);

$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');

$result->text(); // Hello! How can I assist you today?
```

--------------------------------

### Reading grounding metadata from response

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-response-objects.md

Example from the README showing how to read grounding metadata from a response. It iterates over web search queries and grounding chunks, printing each query and source title/URI.

```php
$groundingMetadata = $response->candidates[0]->groundingMetadata;
if ($groundingMetadata !== null) {
    foreach ($groundingMetadata->webSearchQueries ?? [] as $query) {
        echo "Search query: {$query}\n";
    }
    foreach ($groundingMetadata->groundingChunks ?? [] as $chunk) {
        if ($chunk->web !== null) {
            echo "Source: {$chunk->web->title} - {$chunk->web->uri}\n";
        }
    }
}
```

--------------------------------

### Quick start: Initialize client and generate content

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/index.md

Shows the basic usage of the Gemini client: obtain an API key from environment, create a client, and generate content with the 'gemini-2.0-flash' model. The result's text() method returns the model's response.

```php
use Gemini;

$yourApiKey = getenv('YOUR_API_KEY');
$client = Gemini::client($yourApiKey);

$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');
$result->text(); // Hello! How can I assist you today?
```

--------------------------------

### Using ClientFake with GenerateContentResponse::fakeStream

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/testing.md

Example of using ClientFake with a fake streamed response. Creates a fake client, calls streamGenerateContent, and retrieves the first response from the iterator.

```php
use Gemini\Testing\ClientFake;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

$client = new ClientFake([GenerateContentResponse::fakeStream()]);
$result = $client->generativeModel('gemini-2.0-flash')->streamGenerateContent('Hello');

$response = $result->getIterator()->current();
```

--------------------------------

### Streaming a chat message

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/chat-session.md

Example usage of streamSendMessage. It starts a chat session, sends a message, and iterates over the streamed responses, printing each response's text.

```php
$chat = $client->generativeModel(model: 'gemini-2.0-flash')->startChat();

$stream = $chat->streamSendMessage('Hello');
foreach ($stream as $response) {
    echo $response->text();
}
```

--------------------------------

### PrebuiltVoiceConfig constructor

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-generation-config.md

Constructor for PrebuiltVoiceConfig, requiring a voiceName string.

```php
public function __construct(
    public readonly string $voiceName,
) {}
```

--------------------------------

### GET fileSearchStores/{storeName}/fileSearchDocuments/{documentName}

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Gets a specific file search document by name.

```APIDOC
## Get File Search Document

### Description
Gets a specific file search document by name.

### Method
GET

### Endpoint
`fileSearchStores/{storeName}/fileSearchDocuments/{documentName}`

### Parameters
#### Path Parameters
- **storeName** (string) - Required - The name of the file search store, e.g., `fileSearchStores/my-search-store`.
- **documentName** (string) - Required - The name of the document, e.g., `fileSearchDocuments/my-document`.

### Request Example
```php
$fileSearchDocument = $client->fileSearchStores()->getDocument('fileSearchStores/my-search-store/fileSearchDocuments/my-document');
```

### Response
#### Success Response (200)
- **name** (string) - The name of the document.
- **displayName** (string) - The display name of the document.

#### Response Example
```php
echo "Name: {$fileSearchDocument->name}\n";
echo "Display Name: {$fileSearchDocument->displayName}\n";
```
```

--------------------------------

### create store method

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Creates a file search store. Sends POST fileSearchStores with body {displayName?}. Returns FileSearchStoreResponse.

```php
public function create(?string $displayName = null): FileSearchStoreResponse
```

--------------------------------

### embedContent usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/embedding-model.md

Example of calling embedContent on the embedding model and printing the resulting embedding values.

```php
$response = $client->embeddingModel('text-embedding-004')->embedContent('Write a story about a magic backpack.');
print_r($response->embedding->values);
```

--------------------------------

### Setting system instructions with Content::parse

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Set system instructions to steer model behavior, such as defining a role or response style. The example uses Content::parse to provide a pirate-style instruction and then generates content that follows that style.

```php
use Gemini\Data\Content;

$response = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withSystemInstruction(
        Content::parse('You are a helpful assistant that always responds in the style of a pirate. Use nautical terms and pirate slang in all your responses.')
    )
    ->generateContent('Tell me about PHP programming');

echo $response->text();
// Ahoy there, matey! Let me tell ye about this fine treasure called PHP programming...
```

--------------------------------

### Using ClientFake with a fake response

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/testing.md

Shows how to instantiate ClientFake with a fake GenerateContentResponse and call generateContent, echoing the result text.

```php
use Gemini\Testing\ClientFake;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

$client = new ClientFake([
    GenerateContentResponse::fake([
        'candidates' => [
            ['content' => ['parts' => [['text' => 'success']]]],
        ],
    ]),
]);

$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('test');
echo $result->text(); // 'success'
```

--------------------------------

### Get document by resource name

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Retrieves a single document by its full resource name, e.g., fileSearchStores/my-search-store/fileSearchDocuments/my-document. Sends GET {name} and returns a DocumentResponse.

```php
public function getDocument(string $name): DocumentResponse
```

--------------------------------

### Basic usage of Gemini::client

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/client.md

Shows basic usage of the Gemini façade: create a client with an API key, generate content with a model, and access the response text. The comment shows the expected output.

```php
use Gemini;

$client = Gemini::client($yourApiKey);
$result = $client->generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');
$result->text(); // Hello! How can I assist you today?
```

--------------------------------

### Grounding with File Search using FileSearch tool

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Ground the model with File Search to retrieve information from indexed files. Specify the file search store names and an optional metadata filter to narrow the search, then generate content based on the retrieved documents.

```php
use Gemini\Data\FileSearch;
use Gemini\Data\Tool;

$tool = new Tool(
    fileSearch: new FileSearch(
        fileSearchStoreNames: ['files/my-document-store'],
        metadataFilter: 'author = "Robert Graves"'
    )
);

$response = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withTool($tool)
    ->generateContent('Summarize the document about Greek myths by Robert Graves');

echo $response->text();
// (Model output summarizing the document)
```

--------------------------------

### Schema constructor with all parameters

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-generation-config.md

Defines the Schema class constructor with all its parameters. Use this to create a Schema instance for structured output. Note that maxItems, minItems, minProperties, maxProperties, minLength, and maxLength are declared as strings in the source.

```php
public function __construct(
    public readonly DataType $type,
    public readonly ?DataFormat $format = null,
    public readonly ?string $description = null,
    public readonly ?bool $nullable = null,
    public readonly ?array $enum = null,
    public readonly ?string $maxItems = null,
    public readonly ?string $minItems = null,
    public readonly ?array $properties = null,
    public readonly ?array $required = null,
    public readonly ?array $propertyOrdering = null,
    public readonly ?Schema $items = null,
    public readonly ?string $title = null,
    public readonly ?string $minProperties = null,
    public readonly ?string $maxProperties = null,
    public readonly ?string $minLength = null,
    public readonly ?string $maxLength = null,
    public readonly ?string $pattern = null,
    public readonly int|float|string|bool|array|null $example = null,
    public readonly ?array $anyOf = null,
    public readonly int|float|string|bool|array|null $default = null,
    public readonly ?float $minimum = null,
    public readonly ?float $maximum = null,
) {}
```

--------------------------------

### countTokens usage example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/generative-model.md

Shows how to call countTokens on a generative model instance and echo the totalTokens property. The example uses model 'gemini-2.0-flash' and outputs 9 for the given prompt.

```php
$response = $client->generativeModel(model: 'gemini-2.0-flash')->countTokens('Write a story about a magic backpack.');
echo $response->totalTokens; // 9
```

--------------------------------

### embedContent error handling example

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/embedding-model.md

Example of handling errors when calling embedContent with additional parameters like taskType, title, and outputDimensionality. Catches ErrorException and prints the error status.

```php
use Gemini\Exceptions\ErrorException;

try {
    $response = $client
        ->embeddingModel('text-embedding-004')
        ->embedContent('Hello', taskType: \Gemini\Enums\TaskType::RETRIEVAL_QUERY, title: 'My doc', outputDimensionality: 128);
} catch (ErrorException $e) {
    echo $e->getErrorStatus();
}
```

--------------------------------

### Client files() method

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/client.md

Returns a Files resource for upload, list, metadata, and delete operations on media files. See the Files documentation for more details.

```php
/**
 * Resource to manage media file uploads to be reused across multiple requests and prompts.
 *
 * @link https://ai.google.dev/api/files
 */
public function files(): FilesContract
```

--------------------------------

### create(BackedEnum|string $model, ?Content $systemInstruction = null, array $tools = [], ?ToolConfig $toolConfig = null, ?string $ttl = null, ?string $displayName = null, string|Blob|array|Content|UploadedFile ...$parts): MetadataResponse

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/cached-contents.md

Creates a new cached content resource with the specified model and content parts. Returns a MetadataResponse containing the created cached content metadata.

```APIDOC
## POST /cachedContents

### Description
Creates a new cached content resource.

### Method
POST

### Endpoint
/cachedContents

### Parameters
#### Request Body
- **model** (BackedEnum|string) - Required - The model to use for caching.
- **systemInstruction** (Content|null) - Optional - System instruction for the cached content.
- **tools** (array) - Optional - List of tools to include.
- **toolConfig** (ToolConfig|null) - Optional - Configuration for tool usage.
- **ttl** (string|null) - Optional - Time-to-live for the cached content.
- **displayName** (string|null) - Optional - Display name for the cached content.
- **parts** (string|Blob|array|Content|UploadedFile) - Required - Content parts to cache.

### Response
#### Success Response (200)
- **MetadataResponse** - The created cached content metadata.

### Response Example
{
  "name": "cachedContents/abc123",
  "model": "gemini-2.0-flash",
  "displayName": "My Cached Content"
}
```

--------------------------------

### withQueryParam method signature

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/factory.md

Fluent method to add a query parameter appended to every GET request URL. Note the declared parameter type is string, while the property PHPDoc is array<string, string|int>. Only GET requests receive them.

```php
public function withQueryParam(string $name, string $value): self
```

--------------------------------

### Read API key from environment variable and create Gemini client

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/configuration.md

Shows the README pattern for reading an API key from an environment variable and creating a Gemini client. The library itself does not read environment variables; the key must be exported by your own application.

```php
$yourApiKey = getenv('YOUR_API_KEY');
$client = Gemini::client($yourApiKey);
```

--------------------------------

### GET {model}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Retrieves metadata for a specific model.

```APIDOC
## GET {model}

### Description
Retrieves metadata for a specific model.

### Method
GET

### Endpoint
`{model}`

### Parameters
#### Path Parameters
- **model** (string) - Required - The normalized model name (e.g., `models/gemini-2.5-pro-preview-05-06`).

### Response
#### Success Response (200)
- **model** (object) - A single model object with fields: name, version, displayName, description, inputTokenLimit, outputTokenLimit, supportedGenerationMethods, baseModelId (optional), temperature (optional), maxTemperature (optional), topP (optional), topK (optional).

#### Response Example
```json
{
  "name": "models/gemini-2.5-pro-preview-05-06",
  "version": "1.0",
  "displayName": "Gemini 2.5 Pro Preview",
  "description": "...",
  "inputTokenLimit": 1000000,
  "outputTokenLimit": 8192,
  "supportedGenerationMethods": ["generateContent"]
}
```
```

--------------------------------

### GET /fileSearchStores/documents/{name}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Retrieves a document by its name.

```APIDOC
## [GET] /fileSearchStores/documents/{name}

### Description
Retrieves a document by its name.

### Method
GET

### Endpoint
/fileSearchStores/documents/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the document to retrieve.

### Response
#### Success Response (200)
- **name** (string) - The name of the document.

#### Response Example
```json
{
  "name": "stores/123/documents/456"
}
```
```

--------------------------------

### GET /fileSearchStores

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Lists file search stores.

```APIDOC
## [GET] /fileSearchStores

### Description
Lists file search stores.

### Method
GET

### Endpoint
/fileSearchStores

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - The maximum number of stores to return.
- **nextPageToken** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **stores** (array) - List of stores.
- **nextPageToken** (string) - Token for the next page.

#### Response Example
```json
{
  "stores": [
    {
      "name": "stores/123"
    }
  ],
  "nextPageToken": "token"
}
```
```

--------------------------------

### withSystemInstruction(Content $systemInstruction): self

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/generative-model.md

Sets the system instruction content for the model.

```APIDOC
## withSystemInstruction(Content $systemInstruction): self

### Description
Sets `$this->systemInstruction` (see [`Content`](data-content.md)).

### Method
N/A (fluent configuration method)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **systemInstruction** (Content) - Required - The system instruction content.

### Request Example
```php
$client->withSystemInstruction(new Content(...));
```

### Response
#### Success Response (200)
- **$this** (self) - The client instance for chaining.

#### Response Example
```php
$client = $client->withSystemInstruction(new Content(...));
```
```

--------------------------------

### GET {name}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Retrieves a specific cached content by its name.

```APIDOC
## GET {name}

### Description
Retrieves a specific cached content by its name.

### Method
GET

### Endpoint
{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the cached content.

### Response
#### Success Response (200)
- **CachedContents\MetadataResponse** - The metadata of the cached content.

#### Response Example
{
  "name": "cachedContents/abc123",
  "model": "models/gemini-1.5-pro",
  "displayName": "My Cache",
  "createTime": "2024-01-01T00:00:00Z",
  "updateTime": "2024-01-01T00:00:00Z"
}
```

--------------------------------

### GET cachedContents

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Lists cached contents with optional pagination.

```APIDOC
## GET cachedContents

### Description
Lists cached contents with optional pagination.

### Method
GET

### Endpoint
cachedContents

### Parameters
#### Query Parameters
- **pageSize** (int) - Optional - Maximum number of items to return.
- **pageToken** (string) - Optional - Token for pagination.

### Response
#### Success Response (200)
- **CachedContents\ListResponse** - A list of cached contents.

#### Response Example
{
  "cachedContents": [
    {
      "name": "cachedContents/abc123",
      "model": "models/gemini-1.5-pro"
    }
  ],
  "nextPageToken": "token"
}
```

--------------------------------

### Client models() method

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/client.md

Returns a Models resource for listing and retrieving model metadata. No parameters are required.

```php
public function models(): Models
```

--------------------------------

### GET files/{name}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/endpoints.md

Retrieves metadata for a specific file.

```APIDOC
## GET files/{name}

### Description
Retrieves metadata for a specific file.

### Method
GET

### Endpoint
`files/{name}`

### Parameters
#### Path Parameters
- **name** (string) - Required - The file name. Can be a bare name, `files/{name}`, or a full HTTPS URI (used verbatim if it starts with `http`).

### Response
#### Success Response (200)
- **file** (object) - File metadata object.

#### Response Example
```json
{
  "name": "files/abc123",
  "displayName": "myfile.txt",
  "mimeType": "text/plain",
  "sizeBytes": "12345",
  "createTime": "2023-01-01T00:00:00Z",
  "updateTime": "2023-01-01T00:00:00Z"
}
```
```

--------------------------------

### Grounding with Google Maps using GoogleMaps tool and RetrievalConfig

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Enable grounding with Google Maps by creating a GoogleMaps tool with enableWidget set to true and configuring a ToolConfig with latitude and longitude for location-based queries. The model can then answer questions about nearby points of interest.

```php
use Gemini\Data\GoogleMaps;
use Gemini\Data\RetrievalConfig;
use Gemini\Data\Tool;
use Gemini\Data\ToolConfig;

$tool = new Tool(
    googleMaps: new GoogleMaps(enableWidget: true)
);

$toolConfig = new ToolConfig(
    retrievalConfig: new RetrievalConfig(
        latitude: 40.758896,
        longitude: -73.985130
    )
);

$response = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withTool($tool)
    ->withToolConfig($toolConfig)
    ->generateContent('Find coffee shops near me');

echo $response->text();
// (Model output referencing coffee shops)
```

--------------------------------

### PrebuiltVoiceConfig

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-generation-config.md

Configuration for a prebuilt voice, identified by a voice name.

```APIDOC
## PrebuiltVoiceConfig

### Description
Configuration for a prebuilt voice, identified by a voice name.

### Constructor
```php
public function __construct(
    public readonly string $voiceName,
) {}
```

### Parameters
- **voiceName** (string) - Required - The name of the prebuilt voice.
```

--------------------------------

### GET /models/{modelName}

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Retrieve details about a specific Gemini model.

```APIDOC
## Get Model

### Description
Get information about a model, such as version, display name, input token limit, etc.

### Method
GET

### Endpoint
/models/{modelName}

### Parameters
#### Path Parameters
- **modelName** (string) - Required - The resource name of the model to retrieve, in the format 'models/{model}'.

### Request Example
```php
$response = $client->models()->retrieve('models/gemini-2.5-pro-preview-05-06');
```

### Response
#### Success Response (200)
- **model** (Model object) - The requested model information.

#### Response Example
```php
$response->model;
//Gemini\Data\Model Object
//(
//    [name] => models/gemini-2.5-pro-preview-05-06
//    [version] => 2.5-preview-05-06
//    [displayName] => Gemini 2.5 Pro Preview 05-06
//    [description] => Preview release (May 6th, 2025) of Gemini 2.5 Pro
//    ...
//)
```
```

--------------------------------

### GET /fileSearchStores/{name}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Retrieves a file search store by its name.

```APIDOC
## [GET] /fileSearchStores/{name}

### Description
Retrieves a file search store by its name.

### Method
GET

### Endpoint
/fileSearchStores/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the store to retrieve.

### Response
#### Success Response (200)
- **name** (string) - The name of the store.

#### Response Example
```json
{
  "name": "stores/123"
}
```
```

--------------------------------

### startChat(array $history = []): ChatSession

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/chat-session.md

Creates a new ChatSession with the given history, sharing the same underlying GenerativeModel.

```APIDOC
## startChat(array $history = []): ChatSession

### Description
Returns a **new** `ChatSession` (`new self(model: $this->model, history: $history)`) sharing the same underlying `GenerativeModel`, with an independent history.

### Method
startChat

### Parameters
#### Optional Parameters
- **$history** (array<Content>) - Optional - Initial chat history.

### Return Type
ChatSession (or ChatSessionContract per the interface)

### Example
```php
$chat = $client->generativeModel(model: 'gemini-2.0-flash')->startChat();
```
```

--------------------------------

### GET {name}

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Retrieves a specific document by its full resource name.

```APIDOC
## [GET] {name}

### Description
Retrieves a specific document by its full resource name.

### Method
GET

### Endpoint
`{name}`

### Parameters
#### Path Parameters
- **name** (string) - Required - Full document resource name, e.g., `fileSearchStores/my-search-store/fileSearchDocuments/my-document`.

### Response
#### Success Response (200)
- **DocumentResponse** - The document details.
```

--------------------------------

### Grounding with Google Search using GoogleSearch tool

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Use the GoogleSearch tool with Gemini 2.0 and later models to enable real-time web grounding. The response includes grounding metadata with web search queries, grounding chunks (web sources), and grounding supports that link text segments to sources.

```php
use Gemini\Data\GoogleSearch;
use Gemini\Data\Tool;

$response = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withTool(new Tool(googleSearch: GoogleSearch::from()))
    ->generateContent('Who won the Euro 2024?');

echo $response->text();
// Spain won Euro 2024, defeating England 2-1 in the final.

// Access grounding metadata to see sources
$groundingMetadata = $response->candidates[0]->groundingMetadata;
if ($groundingMetadata !== null) {
    // Get the search queries that were executed
    foreach ($groundingMetadata->webSearchQueries ?? [] as $query) {
        echo "Search query: {$query}\n";
    }
    
    // Get the web sources
    foreach ($groundingMetadata->groundingChunks ?? [] as $chunk) {
        if ($chunk->web !== null) {
            echo "Source: {$chunk->web->title} - {$chunk->web->uri}\n";
        }
    }
    
    // Get grounding supports (links text segments to sources)
    foreach ($groundingMetadata->groundingSupports ?? [] as $support) {
        if ($support->segment !== null) {
            echo "Text segment: {$support->segment->text}\n";
            echo "Supported by chunks: " . implode(', ', $support->groundingChunkIndices ?? []) . "\n";
        }
    }
}
```

--------------------------------

### Tool constructor with optional parameters

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-tools.md

Constructor for the Tool value object, accepting optional parameters for function declarations, Google Search retrieval, code execution, Google Search, URL context, Google Maps, and file search. All parameters default to null.

```php
public function __construct(
    public ?array $functionDeclarations = null,
    public ?GoogleSearchRetrieval $googleSearchRetrieval = null,
    public ?CodeExecution $codeExecution = null,
    public ?GoogleSearch $googleSearch = null,
    public ?UrlContext $urlContext = null,
    public ?GoogleMaps $googleMaps = null,
    public ?FileSearch $fileSearch = null,
) {}
```

--------------------------------

### GET fileSearchStores

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Lists File Search stores with optional pagination.

```APIDOC
## GET fileSearchStores

### Description
Lists File Search stores with optional pagination.

### Method
GET

### Endpoint
fileSearchStores

### Parameters
#### Query Parameters
- **pageSize** (int|null) - Optional - Max stores per page. Defaults to 10, max 20.
- **nextPageToken** (string|null) - Optional - Pagination token.

### Response
#### Success Response (200)
- **fileSearchStores** (array<FileSearchStoreResponse>) - List of stores.
- **nextPageToken** (string|null) - Token for the next page.

#### Response Example
{
  "fileSearchStores": [
    {
      "name": "fileSearchStores/store1"
    }
  ],
  "nextPageToken": "token123"
}
```

--------------------------------

### Interval

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-tools.md

Represents a time interval with optional start and end times.

```APIDOC
## Interval

### Description
Represents a time interval with optional start and end times.

### Constructor
```php
public function __construct(
    public readonly ?string $startTime,
    public readonly ?string $endTime,
) {}
```

### Parameters
- **startTime** (?string) - Optional - The start time of the interval.
- **endTime** (?string) - Optional - The end time of the interval.

### toArray()
Returns `\stdClass` when both `startTime` and `endTime` are null, otherwise returns an array with the set values.

```

--------------------------------

### Configure a custom Gemini client with Gemini::factory()

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Configure a separate Gemini client with a custom base URL, HTTP headers, query parameters, a custom HTTP client (Guzzle), and a custom stream handler. Defaults are noted in comments: base URL is https://generativelanguage.googleapis.com/v1beta/ and the HTTP client is discovered via PSR-18.

```php
use Gemini;

$yourApiKey = getenv('YOUR_API_KEY');

$client = Gemini::factory()
    ->withApiKey($yourApiKey)
    ->withBaseUrl('https://generativelanguage.example.com/v1beta') // default: https://generativelanguage.googleapis.com/v1beta/
    ->withHttpHeader('X-My-Header', 'foo')
    ->withQueryParam('my-param', 'bar')
    ->withHttpClient($guzzleClient = new \GuzzleHttp\Client(['timeout' => 30]))  // default: HTTP client found using PSR-18 HTTP Client Discovery
    ->withStreamHandler(fn(RequestInterface $request): ResponseInterface => $guzzleClient->send($request, [
        'stream' => true // Allows to provide a custom stream handler for the http client.
    ]))
    ->make();
```

--------------------------------

### Reading Grounding Metadata

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/data-response-objects.md

Example of reading grounding metadata from a response candidate.

```APIDOC
## Reading Grounding Metadata

### Description
Example of reading grounding metadata from a response candidate.

### Code Example
```php
$groundingMetadata = $response->candidates[0]->groundingMetadata;
if ($groundingMetadata !== null) {
    foreach ($groundingMetadata->webSearchQueries ?? [] as $query) {
        echo "Search query: {$query}\n";
    }
    foreach ($groundingMetadata->groundingChunks ?? [] as $chunk) {
        if ($chunk->web !== null) {
            echo "Source: {$chunk->web->title} - {$chunk->web->uri}\n";
        }
    }
}
```
```

--------------------------------

### GET /fileSearchStores/{storeName}/documents

Source: https://github.com/google-gemini-php/client/blob/main/_autodocs/api-reference/file-search-stores.md

Lists documents in a file search store.

```APIDOC
## [GET] /fileSearchStores/{storeName}/documents

### Description
Lists documents in a file search store.

### Method
GET

### Endpoint
/fileSearchStores/{storeName}/documents

### Parameters
#### Path Parameters
- **storeName** (string) - Required - The name of the store.

#### Query Parameters
- **pageSize** (integer) - Optional - The maximum number of documents to return.
- **nextPageToken** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **documents** (array) - List of documents.
- **nextPageToken** (string) - Token for the next page.

#### Response Example
```json
{
  "documents": [
    {
      "name": "stores/123/documents/456"
    }
  ],
  "nextPageToken": "token"
}
```
```

--------------------------------

### Combining system instructions with GenerationConfig for JSON output

Source: https://github.com/google-gemini-php/client/blob/main/README.md

Combine system instructions with generation config to force JSON output. Set the response MIME type to APPLICATION_JSON and use a system instruction that asks for valid JSON objects, then print the parsed JSON response.

```php
use Gemini\Data\Content;
use Gemini\Data\GenerationConfig;
use Gemini\Enums\ResponseMimeType;

$response = $client
    ->generativeModel(model: 'gemini-2.0-flash')
    ->withSystemInstruction(
        Content::parse('You are a JSON API. Always respond with valid JSON objects. Be concise.')
    )
    ->withGenerationConfig(
        new GenerationConfig(responseMimeType: ResponseMimeType::APPLICATION_JSON)
    )
    ->generateContent('Give me information about the Eiffel Tower');

print_r($response->json());
```
Tokens:
Raw