PHPackages                             noxsi/laravel-gemininano - 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. [Utility & Helpers](/categories/utility)
4. /
5. noxsi/laravel-gemininano

ActiveLibrary[Utility & Helpers](/categories/utility)

noxsi/laravel-gemininano
========================

A Repo / SDK for Gemini Nano

v0.1.0(5mo ago)32MITPHPPHP ^8.4.0CI passing

Since Dec 9Pushed 5mo agoCompare

[ Source](https://github.com/noxsii/laravel-gemininano)[ Packagist](https://packagist.org/packages/noxsi/laravel-gemininano)[ RSS](/packages/noxsi-laravel-gemininano/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (12)Versions (2)Used By (0)

GeminiNano Laravel ⚡
====================

[](#gemininano-laravel-)

**GeminiNano Laravel** is an elegant Laravel SDK for generating images with **Google Gemini** (e.g. `gemini-2.5-flash-image`).
It wraps the official Gemini REST API in a clean, resource-based, Laravel-friendly API and can automatically:

- return **Base64 image data**, or
- **store images on your Laravel filesystem** and return a public URL – all controlled via config.

> Under the hood it calls: `POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent`with a text prompt and extracts the inline base64 image data.

---

✨ Features
----------

[](#-features)

- **Modern architecture** – clean `Client::factory()->make()` API
- **Resource-based** – separate `images()` resource for image generation
- **Laravel integration** – service provider + facade out of the box
- **Config-driven storage**
    - store images via Laravel’s filesystem and return URLs
    - or return raw Base64 directly (for APIs, tests, etc.)
- **Type-safe responses** with dedicated response classes
- **Framework-first DX** – built for Laravel 10/11/12 and PHP 8.2+

---

📦 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require noxsi/laravel-gemininano
```

> For local development using a path repository, point your Laravel app’s `composer.json` to your package directory and then run the command above.

---

⚙️ Configuration
----------------

[](#️-configuration)

Publish the config file:

```
php artisan vendor:publish --provider="Noxsi\GeminiNano\GeminiNanoServiceProvider" --tag="config"
```

This will create `config/gemininano.php`.

### .env

[](#env)

Add your Gemini API configuration:

```
GEMINI_NANO_URL=https://generativelanguage.googleapis.com
GEMINI_NANO_KEY=your-gemini-api-key
GEMINI_NANO_MODEL=gemini-2.5-flash-image
GEMINI_NANO_TIMEOUT=60

# Image handling
GEMINI_NANO_STORE=true          # true = store in filesystem, false = return base64
GEMINI_NANO_DISK=public         # Laravel filesystem disk
GEMINI_NANO_PATH=gemininano     # directory inside the disk
```

### Config file overview

[](#config-file-overview)

```
return [
    'base_url' => env('GEMINI_NANO_URL', 'https://generativelanguage.googleapis.com'),
    'api_key'  => env('GEMINI_NANO_KEY'),
    'model'    => env('GEMINI_NANO_MODEL', 'gemini-2.5-flash-image'),
    'timeout'  => (int) env('GEMINI_NANO_TIMEOUT', 60),

    'store' => (bool) env('GEMINI_NANO_STORE', true),
    'disk'  => env('GEMINI_NANO_DISK', 'public'),
    'path'  => env('GEMINI_NANO_PATH', 'gemininano'),
];
```

---

🚀 Usage
-------

[](#-usage)

You can use the package either via the **client** or the **facade**.

### 1. Basic usage with the Facade

[](#1-basic-usage-with-the-facade)

```
use Noxsi\GeminiNano\Facades\GeminiNano; // Facade alias

// Generate an image from a text prompt
$response = GeminiNano::images()->generate(
    'Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme'
);

// Depending on config:
// - GEMINI_NANO_STORE=true  -> result() returns a URL (stored via filesystem)
// - GEMINI_NANO_STORE=false -> result() returns a base64 string
$result = $response->result();

return response()->json([
    'image' => $result,
]);
```

### 2. Using the Client directly (DI-friendly)

[](#2-using-the-client-directly-di-friendly)

```
use Noxsi\GeminiNano\Client;

class BananaController
{
    public function __construct(
        private Client $gemini,
    ) {}

    public function __invoke()
    {
        $response = $this->gemini
            ->images()
            ->generate('A futuristic nano banana in a Gemini-themed lab');

        return [
            'image' => $response->result(),
        ];
    }
}
```

---

🧠 How the image pipeline works
------------------------------

[](#-how-the-image-pipeline-works)

When you call:

```
$response = GeminiNano::images()->generate('Your prompt here');
```

the package:

1. Builds a request body compatible with the official Gemini API:

    ```
    {
      "contents": [
        {
          "parts": [
            { "text": "Your prompt here" }
          ]
        }
      ]
    }
    ```
2. Sends a `POST` request to:

    ```
    https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent

    ```

    with headers:

    - `x-goog-api-key: `
    - `Content-Type: application/json`
3. Extracts the base64-encoded image data from the response:

    - `candidates[0].content.parts[*].inlineData.data`
    - (also supports snake\_case `inline_data.data` for safety)
4. Wraps everything in a `GenerateResponse` object.
5. When you call `->result()`:

    - If `config('gemininano.store') === true`
        → the package decodes the base64 string, stores it as a `.png` via `Storage::disk(...)`, and returns the public URL.
    - If `config('gemininano.store') === false`
        → it simply returns the raw base64 string.

You can always access the raw data:

```
$base64 = $response->base64();   // raw base64 image data
$raw    = $response->raw();      // full decoded Gemini JSON response
```

---

🎛 Advanced usage
----------------

[](#-advanced-usage)

### Passing extra options to Gemini

[](#passing-extra-options-to-gemini)

You can pass additional options like `generationConfig`, `safetySettings`, etc. They are merged into the root payload:

```
$options = [
    'generationConfig' => [
        'temperature' => 0.7,
    ],
    'safetySettings' => [
        // ...
    ],
];

$response = GeminiNano::images()->generate(
    'A neon-lit banana robot in a Gemini-branded bar',
    options: $options,
);

$image = $response->result();
```

### Using an input image (multimodal / inline\_data)

[](#using-an-input-image-multimodal--inline_data)

You can optionally send an input image along with your text prompt.
Internally this builds a payload like:

```
{
  "contents": [
    {
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        },
        {
          "text": "Caption this image."
        }
      ]
    }
  ]
}
```

Example:

```
use Noxsi\GeminiNano\Facades\GeminiNano;

$imagePath = storage_path('app/public/example.jpg');

$response = GeminiNano::images()->generate(
    prompt: 'Caption this image.',
    imagePath: $imagePath,
    imageMimeType: 'image/jpeg', // optional, will be auto-detected if null
);

$result = $response->result(); // URL or base64 depending on config
```

> Note: `imagePath` must point to a readable image file. The package will base64-encode the file and send it as `inline_data` to the Gemini API.

### Returning base64 for an API endpoint

[](#returning-base64-for-an-api-endpoint)

For API scenarios where you don’t want to store anything:

```
GEMINI_NANO_STORE=false
```

Then in your controller:

```
$response = GeminiNano::images()->generate('Minimalist banana icon, flat design');

return response()->json([
    'image_base64' => $response->result(), // now base64
]);
```

---

🧪 Testing
---------

[](#-testing)

If you are testing **within your Laravel app** that uses the package, you can mock the HTTP layer as usual:

```
use Illuminate\Support\Facades\Http;
use Noxsi\GeminiNano\Facades\GeminiNano;

test('it generates an image via gemini nano', function () {
    Http::fake([
        'https://generativelanguage.googleapis.com/*' => Http::response([
            'candidates' => [
                [
                    'content' => [
                        'parts' => [
                            [
                                'inlineData' => [
                                    'data' => base64_encode('dummy-image-binary'),
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ], 200),
    ]);

    $response = GeminiNano::images()->generate('Test prompt');

    expect($response->base64())->toBe(base64_encode('dummy-image-binary'));
});
```

If you’re testing **the package itself**, you can use Pest; the package is designed to run in a standard Laravel test environment.

---

🧱 Requirements
--------------

[](#-requirements)

- PHP **8.2+**
- Laravel **10.x, 11.x, 12.x**
- `ext-mbstring`
- `ext-json`
- A valid Google Gemini API key

---

🔧 Local development (using a path repository)
---------------------------------------------

[](#-local-development-using-a-path-repository)

If you’re developing this package locally, you can hook it into a test Laravel application via a path repository:

In your Laravel app’s `composer.json`:

```
"repositories": [
{
"type": "path",
"url": "../laravel-gemininano",
"options": {
"symlink": true
}
}
]
```

Then:

```
composer require noxsi/laravel-gemininano:*@dev
```

Any changes you make in the package directory will be reflected in your Laravel app (after `composer dump-autoload` when adding/removing classes).

---

📜 Changelog
-----------

[](#-changelog)

All notable changes to this package will be documented in the `CHANGELOG.md` file.

---

🤝 Contributing
--------------

[](#-contributing)

Pull requests are welcome!

If you plan something bigger (new resources, breaking changes, etc.), open an issue first to discuss your idea.

Steps:

1. Fork the repo
2. Create your feature branch: `git checkout -b feature/my-awesome-feature`
3. Run tests & formatter: `composer test` / `composer lint`
4. Commit your changes and open a PR

---

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance73

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

155d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bd1dc3ab8d589df062df5d0d51eac6f5e586ded4f9a0fdfbbda038ca2bd04217?d=identicon)[noxsii](/maintainers/noxsii)

---

Top Contributors

[![noxsii](https://avatars.githubusercontent.com/u/53399498?v=4)](https://github.com/noxsii "noxsii (6 commits)")

---

Tags

phplaravelimage-generatorGeminigemini-nano

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/noxsi-laravel-gemininano/health.svg)

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

###  Alternatives

[yajra/laravel-datatables-oracle

jQuery DataTables API for Laravel

4.9k33.8M339](/packages/yajra-laravel-datatables-oracle)[monicahq/laravel-cloudflare

Add Cloudflare ip addresses to trusted proxies for Laravel.

3372.7M4](/packages/monicahq-laravel-cloudflare)[laragear/preload

Effortlessly make a Preload script for your Laravel application.

119363.5k](/packages/laragear-preload)[kra8/laravel-snowflake

Snowflake for Laravel and Lumen.

188402.3k6](/packages/kra8-laravel-snowflake)[erlandmuchasaj/laravel-gzip

Gzip your responses.

40129.3k2](/packages/erlandmuchasaj-laravel-gzip)[tehwave/laravel-achievements

Simple, elegant Achievements the Laravel way

7012.8k](/packages/tehwave-laravel-achievements)

PHPackages © 2026

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