🔓 Free Gemini API

Unleash the Full Power of Google Gemini 3.5 Flash, Imagen 3, and Gemini Video — Completely Free

No API Keys. No Token Costs. No Complex Setup. Zero Watermarks.

A high-performance Go reverse-proxy API server wrapping the consumer Gemini portal (gemini.google.com). Access text generation, multi-turn chat, image creation (Imagen 3), video creation (Gemini Video), video-to-video styling, and music generation through a simple unified REST interface.

Architectural Benefits • Key Features • Quick Start • API Endpoints • SDK Integration • Architecture

🚀 Architectural Benefits

This project is engineered to solve the real-world operational challenges of web-scraping and reverse-proxying consumer endpoints, delivering production-grade reliability:

🎨 In-Place Reverse Alpha-Blending Watermark Remover

Google adds visual watermarks to the bottom-right corner of all generated images and videos. The Go API server includes a highly optimized, fully automated native Go implementation (gemini/watermark.go) that executes in-process immediately upon download.

The Mathematics: It reverses the blending equation: $$\text{watermarked} = \alpha \times \text{logo} + (1 - \alpha) \times \text{original}$$ $${\text{original}} = \frac{\text{watermarked} - \alpha \times \text{logo}}{1 - \alpha}$$
Layout Adaptability: Dynamically identifies coordinates and dimensions based on the file aspect ratio (Portrait 720x1280 maps to a 48px watermark; standard landscape/large scales dynamically map to a 96px watermark), yielding perfectly clean, professional-grade media outputs without black borders or distortion.
Zero Dependencies: Completely native—runs without requiring Python 3, numpy, or opencv-python!

🔄 403 Forbidden Auto-Redirect Bypasser

Downloading media from Google's content servers (googleusercontent.com) directly often results in 403 Forbidden errors. This client implements a custom redirect follow loop:

The Pipeline: It disables Go's default automatic HTTP redirect handler, manually intercepts HTTP 302/307 locations, and dynamically injects the user's active session cookies on every redirect hop (e.g. cross-domain transfers to lh3.usercontent and fife.usercontent), guaranteeing 100% download success.

🔌 Zero-Spam Chrome Extension WebSocket Bridge

Keeping cookies updated across server restarts is solved via our lightweight Chrome Extension (/extension):

One-Shot Sync: Utilizing a persistent WebSocket connection, the extension instantly syncs active cookies on startup or when the browser detects a change, completely avoiding heavy periodic background alarm polls and preserving laptop battery.

🔍 Parser-Level Deduplication & Rapid Refusal Detection

Deduplication: The JSON response parser identifies and filters out duplicate image/video references returned by the Gemini consumer API, saving bandwidth and disk space.
Refusal Detection: Recognizes generation limit responses early (e.g., “I can't create more videos for you today...”), immediately terminating the long-polling routine and returning structured JSON failures instead of hanging for minutes.

🔥 Comparison

Feature	Standard Cloud API	Free Gemini API
Pricing	Pay per token / image / video	100% Free
API Key Required	Yes	No (Uses Cookie Session)
Video Generation	Highly restricted (Expensive)	Gemini Video Enabled (Standard Daily Quota)
Image Generation	Cost per image	Imagen 3 Enabled (Unlimited - Uses Gemini 3.5)
Watermark Removal	None (Or paid edit)	Automatic In-Place Clean
Setup Overhead	Complex SDK configurations	Single REST API / Docker Container

✨ Key Features

AI Chat: Multi-turn conversational memory with Server-Sent Events (SSE) streaming support (OpenAI-compatible data: [DONE] format).
Imagen 3 Image Gen: Generate stunning visuals from text prompts, perform image-to-image editing (e.g., altering clothing, backgrounds, or assets), or upload up to 10 images simultaneously for multi-image analysis.
Gemini Video Gen: Generate text-to-video clips, image-to-video reference animations, or perform complex video-to-video visual edits (e.g., turning a beach video loop into a Studio Ghibli hand-drawn anime style).
Music Generation: Produce vocal and instrumental tracks on-demand, returned as local static URL references.
Automated Session Hot-Reload: Hot-reloads session settings and tokens on cookie sync updates, allowing uninterrupted server operation.

🏁 Quick Start

Step 1: Install Chrome Cookie Bridge Extension

Open Google Chrome and go to chrome://extensions/.
Enable Developer mode (top-right toggle).
Click Load unpacked (top-left) and select the extension folder located in this repository.
Log into gemini.google.com on this browser instance.
The extension will automatically detect your active session and sync your cookies to the Go backend WebSocket server (default port 9222).

Step 2: Run the Server

Choose your preferred deployment method below:

Option A: Pre-built Binary (Recommended & Easiest)

Download the latest release binary matching your operating system from the GitHub Releases.
Make the binary executable and launch it:
- macOS / Linux:
```
chmod +x free-gemini-api-mac-arm64
./free-gemini-api-mac-arm64
```
- Windows: Double-click on free-gemini-api-win-x64.exe or run it from CMD/PowerShell.

Option B: From Source (For Local Dev)

Ensure you have Go 1.21+ installed on your system. Watermark removal and all endpoints run natively without any Python requirements!

# Run the Go server
go run .

Option C: Docker Setup

Run the pre-built Docker container:

docker run -d --name free-gemini-api \
  -e WS_PORT=9222 \
  -e PORT=8000 \
  -p 8000:8000 \
  -p 9222:9222 \
  akashyadav758/free-gemini-api:latest

-e WS_PORT=9222
-e PORT=8000
-p 8000:8000
-p 9222:9222
akashyadav758/free-gemini-api:latest


---

### Step 3: Environment Variables (`.env`)
Create a `.env` file in the root of the project to customize connection configurations:
```env
WS_PORT=8001            # WebSocket cookie bridge port (configured in extension)
PORT=8000               # Port on which this Go API server runs

📡 API Endpoints

1. `POST /chat` — Unified Interface

Handles text conversations, streaming, image generation, multi-image analysis, and video processing.

parameters

Field	Type	Description
`prompt`	`string`	Required. The instruction or text query.
`user_id`	`string`	Optional. Isolated session identity.
`new_chat`	`bool`	Optional. Clear conversational history context.
`stream`	`bool`	Optional. Stream responses back via SSE.
`image`	`file(s)`	Optional. Multi-part form image upload (supports up to 10 files).

End-Point Integrations & Examples

A. Text Generation (Standard JSON)

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain quantum computing in three clear bullet points.",
    "user_id": "test_user_1",
    "new_chat": true
  }'

B. Streaming Text Chat (Server-Sent Events)

curl -N -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a short creative story about a developer and an AI assistant.",
    "user_id": "test_user_1",
    "stream": true
  }'

C. Imagen 3 Image Generation (Text → Image)

Prompt the system to generate pictures, which are automatically downloaded, cleaned of watermarks, and saved locally:

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Generate a beautiful landscape image of a sunset over snow-covered mountains, highly detailed.",
    "user_id": "test_user_1",
    "new_chat": true
  }'

D. Image Editing & Variations (Image + Text Prompt)

Upload an existing image and tell the AI to edit it in place:

curl -X POST http://localhost:8000/chat \
  -F "prompt=Change the background of this image to a busy neon cyberpunk street" \
  -F "image=@/path/to/my_photo.png" \
  -F "user_id=test_user_1" \
  -F "new_chat=true"

E. Gemini Video Generation (Image → Video / Text → Video)

Provide an image reference and animate it, or generate fresh video segments from text:

curl -X POST http://localhost:8000/chat \
  -F "prompt=Animate this scene: make the ocean waves crash dynamically on the shore with smooth cinematic motions" \
  -F "image=@/path/to/beach_scene.png" \
  -F "user_id=test_user_1" \
  -F "new_chat=true"

F. Video-to-Video Visual Styling (Video File Input)

Upload a video and completely rewrite its artistic style:

curl -X POST http://localhost:8000/chat \
  -F "prompt=Edit this video: Convert the entire visual style of this video into a beautiful Studio Ghibli hand-drawn anime style." \
  -F "image=@/path/to/original_video.mp4;type=video/mp4" \
  -F "user_id=test_user_1" \
  -F "new_chat=true"

2. `POST /music` — Song & Audio Track Generation

Generates audio tracks from description prompts.

curl -X POST http://localhost:8000/music \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A relaxing lofi chillhop beat with smooth piano and rain sounds",
    "user_id": "test_user_1",
    "new_chat": true
  }'

Response Structure (JSON Example)

{
  "text": "I have successfully generated your media loop based on the prompt...",
  "conversation_id": "c_3eeb67f56f0c82f2",
  "response_id": "r_5fd71304b0a2190b",
  "choice_id": "rc_82705406bcc3a2f7",
  "images": [
    "http://localhost:8000/static/img_r_5fd71304b0a2190b_0.png"
  ],
  "videos": [
    "http://localhost:8000/static/vid_r_5fd71304b0a2190b_0.mp4"
  ],
  "music": [],
  "elapsed": 43.56
}

(All generated files served dynamically from /static/* have already undergone in-place watermark removal).

🐍 SDK Integration

Python Example

A production-ready script utilizing Python's requests library to interface with the REST server:

import requests
import json

BASE_URL = "http://localhost:8000"

def generate_text(prompt: str, user_id: str = "py_user"):
    url = f"{BASE_URL}/chat"
    payload = {
        "prompt": prompt,
        "user_id": user_id,
        "new_chat": True
    }
    headers = {"Content-Type": "application/json"}
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

def edit_image_to_video(prompt: str, image_path: str, user_id: str = "py_user"):
    url = f"{BASE_URL}/chat"
    files = {
        "image": (image_path, open(image_path, "rb"), "image/png")
    }
    data = {
        "prompt": prompt,
        "user_id": user_id,
        "new_chat": "true"
    }
    
    response = requests.post(url, files=files, data=data)
    return response.json()

if __name__ == "__main__":
    # Generate simple text
    print("Sending text prompt...")
    text_res = generate_text("Explain machine learning in one sentence.")
    print("Response:", text_res["text"])
    
    # Generate / Edit Image-to-Video
    # print(edit_image_to_video("Animate a flying eagle in the clouds", "eagle.png"))

Node.js Example (Streaming Support)

An asynchronous ES6 script displaying streaming chunks using standard node-fetch:

const BASE_URL = "http://localhost:8000";

async function streamStory(prompt) {
  const response = await fetch(`${BASE_URL}/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: prompt,
      stream: true,
      user_id: "node_user",
      new_chat: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder("utf-8");

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    // Print SSE stream lines
    console.log(chunk);
  }
}

streamStory("Write a short futuristic sci-fi paragraph.");

🏗️ Architecture

                                 ┌────────────────────────┐
                                 │      REST Client       │
                                 │  (Python, Node, cURL)  │
                                 └───────────┬────────────┘
                                             │
                                             │ HTTP REST / SSE (Port 8000)
                                             ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ Go API Gateway (Fiber v3 Server)                                                        │
│                                                                                         │
│  ┌────────────────┐     ┌──────────────────┐     ┌────────────────┐     ┌────────────┐  │
│  │ Unified Chat   │     │ Streaming Engine │     │ Media Down-    │     │ In-Place   │  │
│  │ Endpoints      │     │ (Server-Sent     │     │ loader & Cookie│     │ Watermark  │  │
│  │ (POST /chat)   │     │ Events)          │     │ Injector       │     │ Processor  │  │
│  └───────┬────────┘     └────────┬─────────┘     └────────┬───────┘     └──────┬─────┘  │
└──────────┼───────────────────────┼────────────────────────┼────────────────────┼────────┘
           │                       │                        │                    │
           │ JSON RPC payload      │ Chunk Streams          │ Follows manual     │ Executes
           │                       │                        │ redirects          │ watermark.go
           ▼                       ▼                        ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ Google Gemini Web API Backend                                                           │
│ (consumer.rpc.StreamGenerate / hNvQHb video poller / Imagen 3 Engine)                   │
└─────────────────────────────────────────────────────────▲───────────────────────────────┘
                                                          │
                                                          │ Live Cookie Synchronization
                                                          │ (WebSocket Bridge Port 9222)
                                                 ┌────────┴────────┐
                                                 │ Chrome Extension│
                                                 │ Cookie Bridge   │
                                                 └─────────────────┘

Directory Structure

├── main.go               # Fiber HTTP engine startup, Universal REST routers
├── .env                  # Port and WebSocket bridge configs
├── cookies.json          # Live cookie storage, written dynamically via extension
├── gemini/
│   ├── client.go         # Session initialization, API calls, redirect tracking
│   ├── models.go         # API schemas and structures
│   ├── monitor.go        # WebSocket bridge and cookies listener
│   └── watermark.go      # Native Go reverse alpha-blending watermark remover
└── extension/
    ├── manifest.json     # Chrome browser extension manifest definitions
    ├── background.js     # WebSocket connection to Go backend, cookie event handlers
    ├── popup.html        # Interactive developer status panel UI
    └── popup.js          # Local settings controller

⚠️ Limits & Notes

Video Quota limits: Gemini Video generation is limited to standard consumer daily accounts (~3-5 videos daily). The system returns an immediate refusal object with videos: null once limits are triggered.
WebSocket Cookie Sync: Ensure you load the extension located under /extension in your browser to automatically stream and sync active cookies to the backend Go server on port 9222.

⭐ Star this repository if this project helps you! ⭐

Disclaimer: This is an unofficial proxy wrapper built for educational and personal research projects. Adhere to Google Terms of Service.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
extension		extension
gemini		gemini
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

🔓 Free Gemini API

Unleash the Full Power of Google Gemini 3.5 Flash, Imagen 3, and Gemini Video — Completely Free

🚀 Architectural Benefits

🎨 In-Place Reverse Alpha-Blending Watermark Remover

🔄 403 Forbidden Auto-Redirect Bypasser

🔌 Zero-Spam Chrome Extension WebSocket Bridge

🔍 Parser-Level Deduplication & Rapid Refusal Detection

🔥 Comparison

✨ Key Features

🏁 Quick Start

Step 1: Install Chrome Cookie Bridge Extension

Step 2: Run the Server

Option A: Pre-built Binary (Recommended & Easiest)

Option B: From Source (For Local Dev)

Option C: Docker Setup

📡 API Endpoints

1. POST /chat — Unified Interface

parameters

End-Point Integrations & Examples

A. Text Generation (Standard JSON)

B. Streaming Text Chat (Server-Sent Events)

C. Imagen 3 Image Generation (Text → Image)

D. Image Editing & Variations (Image + Text Prompt)

E. Gemini Video Generation (Image → Video / Text → Video)

F. Video-to-Video Visual Styling (Video File Input)

2. POST /music — Song & Audio Track Generation

Response Structure (JSON Example)

🐍 SDK Integration

Python Example

Node.js Example (Streaming Support)

🏗️ Architecture

Directory Structure

⚠️ Limits & Notes

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `POST /chat` — Unified Interface

2. `POST /music` — Song & Audio Track Generation

Packages