@saru2/gemini-image-generator

Reusable "ImageGenerator" React component extracted from the Saru2 Gemini image playground. The component stays client-side only and posts prompts plus optional image uploads to your API.

Installation

npm install @saru2/gemini-image-generator
# or
pnpm add @saru2/gemini-image-generator

Usage

"use client";

import { ImageGenerator } from "@saru2/gemini-image-generator";

export default function Playground() {
  return (
    <ImageGenerator
      endpoint="/api/generate-image"
      onResultChange={(result) => {
        if (result.type === "error") {
          console.error("Generation failed", result.message);
        }
      }}
    />
  );
}

The component ships with Tailwind-powered styles used by the Saru2 playground. You can pass a custom className to the root container or fork the component if you need a different look.

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | endpoint | string | "/api/generate-image" | REST endpoint that accepts the JSON payload documented below. | | requestHeaders | HeadersInit \| (ctx) => HeadersInit | undefined | Optional headers (static or dynamic) merged with Content-Type: application/json. Useful for auth tokens. | | fetchImplementation | typeof fetch | global fetch | Provide a custom fetch implementation if needed (e.g. wrapped fetch with interceptors). | | className | string | undefined | Appends extra classes to the outer <section>. | | onResultChange | (result: Result) => void | undefined | Observe every state change (idle, loading, error, image, text). | | initialPrompt | string | "" | Prefill the textarea. | | defaultAspect | "1:1" \| "16:9" \| "9:16" \| "4:3" \| "3:4" | "1:1" | Initial aspect ratio.

Request body format

{
  "prompt": "Final prompt string",
  "imageBase64": "base64 string (optional, legacy single-image field)",
  "mimeType": "image/png",
  "images": [
    {
      "mimeType": "image/png",
      "dataBase64": "..."
    }
  ]
}

If the user selects a non-square aspect ratio without uploads, the component attaches a blank PNG canvas to images[0] to hint orientation.

Building locally

# from packages/image-generator
npm install
npm run build

The build emits ESM, CJS, and type declarations under dist/. Update the name field in package.json to match your npm scope before publishing.

Publishing

npm login
npm publish --access public

Remember to bump the version for every release and keep your API handler compatible with the payload above.