PHPackages                             hosseinhezami/laravel-gemini - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. hosseinhezami/laravel-gemini

ActiveLibrary[API Development](/categories/api)

hosseinhezami/laravel-gemini
============================

A production-ready Laravel package to integrate with the Google Gemini API. Supports text, image, video, audio, long-context, structured output, files, caching, function-calling and understanding capabilities.

1.0.4(4mo ago)14010.8k↓39.8%23[1 PRs](https://github.com/hosseinhezami/laravel-gemini/pulls)1MITPHPPHP ^8.2|^8.3|^8.4|^8.5CI passing

Since Sep 13Pushed 4mo ago5 watchersCompare

[ Source](https://github.com/hosseinhezami/laravel-gemini)[ Packagist](https://packagist.org/packages/hosseinhezami/laravel-gemini)[ RSS](/packages/hosseinhezami-laravel-gemini/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (2)Versions (6)Used By (1)

Laravel Gemini
==============

[](#laravel-gemini)

A production-ready Laravel package to integrate with the Google Gemini API. Supports text, image, video, audio, long-context, structured output, files, caching, function-calling and understanding capabilities.

[![Version](https://camo.githubusercontent.com/9baa85fb2ef6e6483e38361631fbcd8e1cad172cfbf978165d561e0fae678dac/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686f737365696e68657a616d692f6c61726176656c2d67656d696e692e737667)](https://packagist.org/packages/hosseinhezami/laravel-gemini)[![Downloads](https://camo.githubusercontent.com/8456c5f30a51e886f53d2325f38814f9fe3e9a1c4b9ff5145667c640f9bd2ccb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f686f737365696e68657a616d692f6c61726176656c2d67656d696e692e737667)](https://packagist.org/packages/hosseinhezami/laravel-gemini)[![Star](https://camo.githubusercontent.com/700a407d3edab83b3f80b713a02b1b3a690831fa8eeb25168c1c200baca19be6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f686f737365696e68657a616d692f6c61726176656c2d67656d696e692e737667)](https://packagist.org/packages/hosseinhezami/laravel-gemini)[![License](https://camo.githubusercontent.com/54d568e29fb8f6297facb5596a04bd527a84c4f8a7a6c68c1bc43349d629eb47/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686f737365696e68657a616d692f6c61726176656c2d67656d696e692e737667)](https://packagist.org/packages/hosseinhezami/laravel-gemini)[![Laravel Compatible](https://camo.githubusercontent.com/30ed7e63c5c0756f6adcba531b17f675688ccf82890a93438dcb9cc706d2e0c6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532422d627269676874677265656e2e737667)](https://hosseinhezami.github.io/laravel-gemini)

Features
--------

[](#features)

- 🤖 Text generation with context and history
- 🖼️ Image generation and understanding
- 🎥 Video generation and analysis
- 🔊 Audio synthesis and transcription
- 📄 Document processing and understanding
- 🔍 Embeddings generation
- 📊 File management capabilities
- ⚡ Real-time streaming responses
- 🛡️ Configurable safety settings
- 🗄️ Caching for pre-processed content

Installation
------------

[](#installation)

```
composer require hosseinhezami/laravel-gemini
```

Publish the configuration file:

```
php artisan vendor:publish --tag=gemini-config
```

Add your Gemini API key to your `.env` file:

```
GEMINI_API_KEY=your_gemini_api_key_here
```

Configuration (detailed)
------------------------

[](#configuration-detailed)

Configuration lives in `config/gemini.php`. Below are the most important keys and recommended defaults:

KeyDescriptionDefault`api_key`Your Gemini API key.`env('GEMINI_API_KEY')``base_uri`Base API endpoint.`https://generativelanguage.googleapis.com/v1beta/``default_provider`Which provider config to use by default.`gemini``timeout`Request timeout in seconds.`30``retry_policy.max_retries`Retry attempts for failed requests.`30``retry_policy.retry_delay`Delay between retries in ms.`1000``logging`Log requests/responses (useful for debugging).`false``stream.chunk_size`Stream buffer chunk size.`1024``stream.timeout`Stream timeout (ms).`1000``caching.default_ttl`Default TTL for cache expiration (e.g., '3600s').`'3600s'``caching.default_page_size`Default page size for listing caches.`50`### Providers / models / methods

[](#providers--models--methods)

The `providers` array lets you map capability types to models and HTTP methods the provider uses:

ProviderCapabilityConfig keyDefault modelDefault method`gemini`text`providers.gemini.models.text``gemini-2.5-flash-lite``generateContent``gemini`image`providers.gemini.models.image``gemini-2.5-flash-image-preview``generateContent` or `predict``gemini`video`providers.gemini.models.video``veo-3.0-fast-generate-001``predictLongRunning``gemini`audio`providers.gemini.models.audio``gemini-2.5-flash-preview-tts``generateContent``gemini`embeddings`providers.gemini.models.embedding``gemini-embedding-001`n/a (embeddings endpoint)**Speech config** (`providers.gemini.default_speech_config`) example:

```
'default_speech_config' => [
    'voiceName' => 'Kore',
    // 'speakerVoices' => [
    //     ['speaker' => 'Joe', 'voiceName' => 'Kore'],
    //     ['speaker' => 'Jane', 'voiceName' => 'Puck'],
    // ],
],
```

Dynamic API Key Configuration
-----------------------------

[](#dynamic-api-key-configuration)

By default, Laravel Gemini reads the API key from your `.env` file (`GEMINI_API_KEY`).

However, you can now **set the API key dynamically at runtime** using the new `setApiKey()` method.
This is useful when you want to switch between multiple keys (e.g. per-user or per-request).

**Example:**

```
use HosseinHezami\LaravelGemini\Facades\Gemini;

// Dynamically set API key (takes priority over .env)
Gemini::setApiKey('my-custom-api-key');

// Use Gemini as usual
$response = Gemini::text()
    ->prompt('Hello Gemini!')
    ->generate();

echo $response->content();
```

If `setApiKey()` is not called, the package will automatically use the default key from `.env`.

**ApiKey priority order:**

1. Manually set key via `Gemini::setApiKey()`
2. Config value (`config/gemini.php`)
3. `.env` variable (`GEMINI_API_KEY`)

---

Builder APIs — full method reference
------------------------------------

[](#builder-apis--full-method-reference)

This package exposes a set of builder-style facades: `Gemini::text()`, `Gemini::image()`, `Gemini::video()`, `Gemini::audio()`, `Gemini::embeddings()`, `Gemini::files()` and `Gemini::caches()`.

Below is a concise reference of commonly available chainable methods and what they do. Method availability depends on the builder.

### Common response helpers (Response object)

[](#common-response-helpers-response-object)

When you call `->generate()` (or a polling save on long-running jobs) you typically get a response object with these helpers:

- `content()` — main textual output (string).
- `model()` — model name used.
- `usage()` — usage / billing info returned by the provider.
- `requestId()` — provider request id.
- `save($path)` — convenience method to download and persist a result to disk (media).

---

### Gemini::

[](#gemini)

```
use HosseinHezami\LaravelGemini\Facades\Gemini;
```

### TextBuilder (`Gemini::text()`)

[](#textbuilder-geminitext)

Use for: chat-like generation, long-context text, structured output, and multimodal understanding (text responses after uploading files).

Common methods:

MethodArgsDescription`model(string)`model idChoose model to use.`prompt(string/array)`user prompt or partsMain prompt(s).`system(string)`system instructionSystem-level instruction.`history(array)`chat historyConversation history array (role/parts structure).`structuredSchema(array)`JSON SchemaAsk model to produce structured JSON (schema validation).`temperature(float)`0.0-1.0Sampling temperature.`maxTokens(int)`token limitMax tokens for generation.`safetySettings(array)`arraySafety thresholds from config.`method(string)`provider methodOverride provider method name (e.g., `generateContent`).`upload(string $type, string $path)`(type, local-file-path)Attach a file (image/document/audio/video) to the request.`cache(array $tools = [], array $toolConfig = [], string $displayName = null, string $ttl = null, string $expireTime = null)`optional paramsCreate a cache from current builder params and return cache name.`getCache(string $name)`cache nameGet details of a cached content.`cachedContent(string $name)`cache nameUse a cached content for generation.`stream(callable)`callbackStream chunks (SSE / server events).`generate()`—Execute request and return a Response object.**Notes on `history` structure**
History entries follow a `role` + `parts` format:

```
[
    ['role' => 'user', 'parts' => [['text' => 'User message']]],
    ['role' => 'model', 'parts' => [['text' => 'Assistant reply']]]
]
```

**Text**

```
$response = Gemini::text()
    ->model('gemini-2.5-flash')
    ->system('You are a helpful assistant.')
    ->prompt('Write a conversation between human and Ai')
    ->history([
        ['role' => 'user', 'parts' => [['text' => 'Hello AI']]],
        ['role' => 'model', 'parts' => [['text' => 'Hello human!']]]
    ])
    ->temperature( 0.7)
    ->maxTokens(1024)
    ->generate();

echo $response->content();
```

**Streaming Responses**

```
return response()->stream(function () use ($request) {
    Gemini::text()
        ->model('gemini-2.5-flash')
        ->prompt('Tell a long story about artificial intelligence.')
        ->stream(function ($chunk) {
            $text = $chunk['text'] ?? '';
            if (!empty(trim($text))) {
                echo "data: " . json_encode(['text' => $text]) . "\n\n";
                ob_flush();
                flush();
            }
        });
}, 200, [
    'Content-Type' => 'text/event-stream',
    'Cache-Control' => 'no-cache',
    'Connection' => 'keep-alive',
    'X-Accel-Buffering' => 'no',
]);
```

**Document Understanding**

```
$response = Gemini::text()
    ->upload('document', $filePath) // image, video, audio, document
    ->prompt('Extract the key points from this document.')
    ->generate();

echo $response->content();
```

**Structured output**

```
$response = Gemini::text()
    ->model('gemini-2.5-flash')
    ->structuredSchema([
    'type' => 'object',
    'properties' => [
        'name' => ['type' => 'string'],
        'age'  => ['type' => 'integer']
    ],
    'required' => ['name']
    ])
    ->prompt('Return a JSON object with name and age.')
    ->generate();

$json = $response->content(); // Parsable JSON matching the schema
```

---

### ImageBuilder (`Gemini::image()`)

[](#imagebuilder-geminiimage)

Use for image generation.

MethodArgsDescription`model(string)`model idModel for image generation.`prompt(string)`prompt textImage description.`method(string)`e.g. `predict`Provider method (predict / generateContent).`cache(array $tools = [], array $toolConfig = [], string $displayName = null, string $ttl = null, string $expireTime = null)`optional paramsCreate a cache from current builder params and return cache name.`getCache(string $name)`cache nameGet details of a cached content.`cachedContent(string $name)`cache nameUse a cached content for generation.`generate()`—Run generation.`save($path)`local pathSave image bytes to disk.**Image**

```
$response = Gemini::image()
    ->model('gemini-2.5-flash-image-preview')
    ->method('generateContent')
    ->prompt('A futuristic city skyline at sunset.')
    ->generate();

$response->save('image.png');
```

---

### VideoBuilder (`Gemini::video()`)

[](#videobuilder-geminivideo)

Use for short or long-running video generation.

MethodArgsDescription`model(string)`model idVideo model.`prompt(string)`promptDescribe the video.`cache(array $tools = [], array $toolConfig = [], string $displayName = null, string $ttl = null, string $expireTime = null)`optional paramsCreate a cache from current builder params and return cache name.`getCache(string $name)`cache nameGet details of a cached content.`cachedContent(string $name)`cache nameUse a cached content for generation.`generate()`—Initiates video creation (may be long-running).`save($path)`local pathPolls provider and saves final video file.**Note:** long-running video generation typically uses `predictLongRunning` or similar. The package abstracts polling & saving.

---

### AudioBuilder (`Gemini::audio()`)

[](#audiobuilder-geminiaudio)

Use for TTS generation.

MethodArgsDescription`model(string)`model idTTS model.`prompt(string)`text-to-speakAudio file description`voiceName(string)`voice idSelect a voice (e.g. `Kore`).`speakerVoices(array)`speakers arraySpeakers (e.g. \[\['speaker' => 'Joe', 'voiceName' => 'Kore'\], \['speaker' => 'Jane', 'voiceName' => 'Puck'\]\]).`cache(array $tools = [], array $toolConfig = [], string $displayName = null, string $ttl = null, string $expireTime = null)`optional paramsCreate a cache from current builder params and return cache name.`getCache(string $name)`cache nameGet details of a cached content.`cachedContent(string $name)`cache nameUse a cached content for generation.`generate()`—Generate audio bytes.`save($path)`local pathSave generated audio (wav/mp3).---

### Embeddings (`Gemini::embeddings()`)

[](#embeddings-geminiembeddings)

Accepts a payload array. Typical shape:

```
$embeddings = Gemini::embeddings([
    'model' => 'gemini-embedding-001',
    'content' => ['parts' => [['text' => 'Text to embed']]],
]);

/* embedding_config */
// https://ai.google.dev/gemini-api/docs/embeddings
// 'embedding_config': {
//     'embedding_config': {
//         'task_type': 'SEMANTIC_SIMILARITY', // SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, CODE_RETRIEVAL_QUERY, QUESTION_ANSWERING, FACT_VERIFICATION
//         'embedding_dimensionality': 768 // 128, 256, 512, 768, 1536, 2048
//     }
// }
```

Return value is the raw embeddings structure (provider-specific). Use these vectors for semantic search, similarity, clustering, etc.

---

### Files API (`Gemini::files()`)

[](#files-api-geminifiles)

High level file manager for uploads used by the "understanding" endpoints.

MethodArgsDescription`upload(string $type, string $localPath)``type` in `[document,image,video,audio]`Upload a local file and return a provider `uri` or `file id`.`list()`—Return a list of uploaded files (metadata).`get(string $id)`file idGet file metadata (name, uri, state, mimeType, displayName).`delete(string $id)`file idDelete a previously uploaded file.**Files**

```
// Upload a file
$uri = Gemini::files()->upload('document', $pathToFile);

// List all files
$files = Gemini::files()->list();

// Get file details
$fileInfo = Gemini::files()->get($file_id);

// Delete a file
$success = Gemini::files()->delete($file_id);
```

**Supported file types & MIME**

CategoryExtensionMIME typeimagepngimage/pngimagejpegimage/jpegimagejpgimage/jpegimagewebpimage/webpimageheicimage/heicimageheifimage/heifvideomp4video/mp4videompegvideo/mpegvideomovvideo/movvideoavivideo/avivideoflvvideo/x-flvvideompgvideo/mpgvideowebmvideo/webmvideowmvvideo/wmvvideo3gppvideo/3gppaudiowavaudio/wavaudiomp3audio/mp3audioaiffaudio/aiffaudioaacaudio/aacaudiooggaudio/oggaudioflacaudio/flacdocumentpdfapplication/pdfdocumenttxttext/plaindocumentmdtext/markdown---

### Caching API (`Gemini::caches()`)

[](#caching-api-geminicaches)

High-level cache manager for pre-processing and storing content (prompts, system instructions, history, files) to reuse in generation requests, reducing latency and costs. Caches are model-specific and temporary.

MethodArgsDescription`create(string $model, array $contents, ?string $systemInstruction = null, array $tools = [], array $toolConfig = [], ?string $displayName = null, ?string $ttl = null, ?string $expireTime = null)`required/optional paramsCreate a cached content and return CacheResponse.`list(?int $pageSize = null, ?string $pageToken = null)`optional paramsList cached contents (supports pagination).`get(string $name)`cache nameGet details of a cached content.`update(string $name, ?string $ttl = null, ?string $expireTime = null)`cache name and expirationUpdate cache expiration (TTL or expireTime).`delete(string $name)`cache nameDelete a cached content.**Caching**

```
// Create a cache
$cache = Gemini::caches()->create(
    model: 'gemini-2.5-flash',
    contents: [['role' => 'user', 'parts' => [['text' => 'Sample content']]]],
    systemInstruction: 'You are a helpful assistant.',
    tools: [], // Optional
    toolConfig: [], // Optional
    displayName: 'My Cache', // Optional
    ttl: '600s' // Optional TTL (e.g., '300s') or expireTime: '2024-12-31T23:59:59Z'
);
$cacheName = $cache->name(); // e.g., 'cachedContents/abc123'

// List all caches
$caches = Gemini::caches()->list(pageSize: 50, pageToken: 'nextPageToken');

// Get cache details
$cacheInfo = Gemini::caches()->get($cacheName);

// Update cache expiration
$updatedCache = Gemini::caches()->update(
    name: $cacheName,
    ttl: '1200s' // Or expireTime: '2024-12-31T23:59:59Z'
);

// Delete a cache
$success = Gemini::caches()->delete($cacheName);
```

**CacheResponse Methods**

- `name()`: Returns the cache name (e.g., 'cachedContents/abc123')
- `displayName()`: Returns the Display Name (e.g., 'Default Cache')
- `model()`: Returns the model used
- `expireTime()`: Returns expiration
- `usageMetadata()`: Returns usage metadata
- `toArray()`: Full response as array

**Caching in Generation Builders**

Caching is also integrated into text, image, video, and audio builders for seamless use:

```
// Create cache from builder params
$cacheName = Gemini::text()
    ->model('gemini-2.5-flash')
    ->prompt('Sample prompt')
    ->system('System instruction')
    ->history([['role' => 'user', 'parts' => [['text' => 'History item']]]]) // optional
    ->cache(
        tools: [], // optional
        toolConfig: [], // optional
        displayName: 'My Cache', // optional
        ttl: '600s' // optional, or expireTime
    );

// Get cache details from builder
$cacheInfo = Gemini::text()->getCache($cacheName);

// Use cached content in generation
$response = Gemini::text()
    ->prompt('Summarize this.')
    ->cachedContent($cacheName)
    ->generate();
```

For more details, refer to the [Gemini API Caching Documentation](https://ai.google.dev/api/caching).

---

Streaming (Server-Sent Events)
------------------------------

[](#streaming-server-sent-events)

The `stream` route uses `Content-Type: text/event-stream`. Connect from a browser or SSE client and consume `data: ` messages per chunk.

---

### Streaming behaviour

[](#streaming-behaviour)

- Implemented using SSE (Server-Sent Events). The stream yields chunks where each chunk is typically `['text' => '...']`.
- Client should reconnect behaviorally for resilience and handle partial chunks.
- Use response headers:
    - `Content-Type: text/event-stream`
    - `Cache-Control: no-cache`
    - `Connection: keep-alive`
    - `X-Accel-Buffering: no`

---

Tips, error handling & best practices
-----------------------------------------

[](#tips-error-handling--best-practices)

- Respect provider limits — pick appropriate `maxTokens` and `temperature`.
- For large media (video) prefer long-running `predictLongRunning` models and rely on `save()` to poll and download final asset.
- Use `safetySettings` from config for content filtering. You can override per-request.
- When uploading user-supplied files, validate MIME type and size before calling `Gemini::files()->upload`.
- For caching, use TTL wisely to avoid expired caches; always check expiration in responses.

---

Artisan Commands
----------------

[](#artisan-commands)

The package includes helpful Artisan commands:

CommandDescription`php artisan gemini:models`List available models.---

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance74

Regular maintenance activity

Popularity43

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~24 days

Total

5

Last Release

148d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/38b7c34a3bb546140c926613060af92984bc184c8731e1cf9aaea704ca88a685?d=identicon)[hosseinhezami](/maintainers/hosseinhezami)

---

Top Contributors

[![hosseinhezami](https://avatars.githubusercontent.com/u/8210576?v=4)](https://github.com/hosseinhezami "hosseinhezami (7 commits)")[![kkobold](https://avatars.githubusercontent.com/u/1929003?v=4)](https://github.com/kkobold "kkobold (1 commits)")

---

Tags

aiapigeminilaravelpackagephpapilaravelgoogleaiGemini

### Embed Badge

![Health badge](/badges/hosseinhezami-laravel-gemini/health.svg)

```
[![Health](https://phpackages.com/badges/hosseinhezami-laravel-gemini/health.svg)](https://phpackages.com/packages/hosseinhezami-laravel-gemini)
```

###  Alternatives

[gemini-api-php/laravel

Gemini API client for Laravel

8915.7k](/packages/gemini-api-php-laravel)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[gemini-api-php/client

API client for Google's Gemini API

216221.4k5](/packages/gemini-api-php-client)[mbarwick83/shorty

Google Url Shortener API Package for Laravel 5.1

31204.9k](/packages/mbarwick83-shorty)[dragon-code/laravel-json-response

Automatically always return a response in JSON format

1118.6k1](/packages/dragon-code-laravel-json-response)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)