Download the PHP package hosseinhezami/laravel-gemini without Composer

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.

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

Publish the configuration file:

Add your Gemini API key to your .env file:

Configuration (detailed)

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

Providers / models / methods

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

Speech config (providers.gemini.default_speech_config) example:

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:

`

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

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)

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::

TextBuilder (Gemini::text())

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

Common methods:

Notes on history structure
History entries follow a role + parts format:

Text

Streaming Responses

Document Understanding

Structured output

ImageBuilder (Gemini::image())

Use for image generation.

Image

VideoBuilder (Gemini::video())

Use for short or long-running video generation.

Note: long-running video generation typically uses predictLongRunning or similar. The package abstracts polling & saving.

AudioBuilder (Gemini::audio())

Use for TTS generation.

Embeddings (Gemini::embeddings())

Accepts a payload array. Typical shape:

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

Files API (Gemini::files())

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

Files

Supported file types & MIME

Caching API (Gemini::caches())

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.

Caching

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:

For more details, refer to the Gemini API Caching Documentation.

Streaming (Server-Sent Events)

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

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

• 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

The package includes helpful Artisan commands:

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.