xehopnet/geminiapi repository overview

⁠KCTAPI - Gemini AI API

Một REST API đơn giản để sử dụng Google Gemini AI (chat và sinh ảnh) dựa trên cookie authentication. API được containerized với Docker để dễ dàng triển khai.

⁠📋 Mục lục

• Bảng chuyển đổi lệnh theo OS⁠
• Cài đặt Docker⁠
• Export Cookie từ Google AI Studio⁠
• Chạy Container với Docker⁠
• Sử dụng API⁠
• Các Endpoint⁠
• Xử lý sự cố⁠

⁠🖥️ Bảng chuyển đổi lệnh theo OS

📌 Lưu ý đặc biệt cho Synology NAS:

Nếu bạn dùng Synology NAS, có một số điểm cần chú ý:

1. SSH: Cần bật SSH trên DSM (Control Panel > Terminal & SNMP > Enable SSH service)
2. Docker: Cần cài Container Manager (hoặc Docker package) từ Synology Package Center
3. Permissions: Đảm bảo user có quyền truy cập volume và thư mục docker
4. Port: Kiểm tra firewall để port 5006 không bị chặn
5. Path: Thường dùng /volume1 hoặc /volume2 tùy vào hệ thống

Bảng so sánh nhanh các lệnh và biến môi trường:

Ví dụ đường dẫn thư mục user:

• Linux: /home/username (ví dụ: /home/john)
• macOS: /Users/username (ví dụ: /Users/jane)
• Windows: C:\Users\username (ví dụ: C:\Users\mike)
• Synology NAS: /volume1/username (ví dụ: /volume1/admin)

Ví dụ đường dẫn project:

Giả sử bạn tạo thư mục bananaapi và kctapi bên trong:

• Linux: /home/john/bananaapi/kctapi/har_and_cookies
• macOS: /Users/jane/bananaapi/kctapi/har_and_cookies
• Windows: C:\Users\mike\bananaapi\kctapi\har_and_cookies
• Synology NAS: /volume1/docker/bananaapi/kctapi/har_and_cookies

⁠🐳 Cài đặt Docker

⁠1. Pull Docker Image

Pull image từ Docker Hub:

Docker Hub: https://hub.docker.com/r/xehopnet/geminiapi⁠

docker pull xehopnet/geminiapi:1.0.1

Hoặc dùng tag latest:

docker pull xehopnet/geminiapi:latest

⁠2. Tạo thư mục cho cookies

Tạo thư mục để lưu trữ cookies trên máy host.

Linux / macOS:

mkdir -p $(pwd)/har_and_cookies

Giải thích: $(pwd)/ là gì?

• pwd là lệnh "print working directory" - hiển thị thư mục hiện tại
• $(pwd) lấy kết quả của lệnh pwd
• $(pwd)/har_and_cookies tạo đường dẫn tuyệt đối đến thư mục har_and_cookies trong thư mục hiện tại

Ví dụ cụ thể theo hệ điều hành:

• Linux (ví dụ Ubuntu): Nếu bạn đang ở /home/username/bananaapi

  • $(pwd)/har_and_cookies = /home/username/bananaapi/har_and_cookies

• macOS: Nếu bạn đang ở /Users/username/bananaapi

  • $(pwd)/har_and_cookies = /Users/username/bananaapi/har_and_cookies

• Synology NAS: Nếu bạn đang ở /volume1/docker/bananaapi

  • $(pwd)/har_and_cookies = /volume1/docker/bananaapi/har_and_cookies

• Windows (PowerShell): Nếu bạn đang ở C:\Users\username\bananaapi

  • Không dùng $(pwd) được, phải dùng:

mkdir -p ".\har_and_cookies"

Windows (CMD):

mkdir har_and_cookies

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path ".\har_and_cookies"

Synology NAS:

# Tạo thư mục trên Synology
mkdir -p /volume1/docker/bananaapi/kctapi/har_and_cookies

⁠🍪 Export Cookie từ Google AI Studio

⁠Bước 1: Cài đặt Extension J2TEAM Cookies

1. Mở Google Chrome và truy cập Chrome Web Store - J2TEAM Cookies⁠
2. Nhấn nút "Add to Chrome" để cài đặt extension
3. Extension đã được cài đặt thành công

⁠Bước 2: Đăng nhập Google AI Studio

1. Truy cập trang Google AI Studio⁠
2. Đăng nhập với tài khoản Google của bạn
3. Đảm bảo bạn có thể truy cập đầy đủ các tính năng của Google AI Studio

⁠Bước 3: Export Cookies

1. Sau khi đăng nhập, nhấp vào icon J2TEAM Cookies trên thanh công cụ Chrome (thường ở góc trên bên phải)
2. Trong cửa sổ extension:
   • Chọn tab "Export"
   • Đảm bảo domain đang được chọn là aistudio.google.com hoặc .google.com
   • Nhấn nút "Export" để tải xuống file cookies
3. File cookies sẽ được tải xuống dưới dạng JSON

⁠Bước 4: Đặt Cookies vào thư mục

1. Đổi tên file cookies vừa tải xuống thành tên dễ nhớ (ví dụ: aistudio_cookies.json)
2. Copy file này vào thư mục har_and_cookies trên máy host:

Linux / macOS:

cp ~/Downloads/cookies.json $(pwd)/har_and_cookies/aistudio_cookies.json

Giải thích ~:

• ~ là ký tự đại diện cho thư mục home của user
• Linux: ~ = /home/username
• macOS: ~ = /Users/username
• Synology NAS: ~ = /volume1/homes/username
• Windows: Không dùng ~, phải dùng đường dẫn đầy đủ

Windows (CMD):

copy "C:\Users\username\Downloads\cookies.json" ".\har_and_cookies\aistudio_cookies.json"

Windows (PowerShell):

Copy-Item "$env:USERPROFILE\Downloads\cookies.json" -Destination ".\har_and_cookies\aistudio_cookies.json"

Linux ví dụ:

# Nếu username là "john" và đang ở /home/john/bananaapi
cp /home/john/Downloads/cookies.json /home/john/bananaapi/har_and_cookies/aistudio_cookies.json

macOS ví dụ:

# Nếu username là "jane" và đang ở /Users/jane/bananaapi
cp /Users/jane/Downloads/cookies.json /Users/jane/bananaapi/har_and_cookies/aistudio_cookies.json

Synology NAS ví dụ:

# Nếu tải cookies về máy local rồi upload lên NAS, hoặc dùng SCP
# Ví dụ: Copy từ máy local lên Synology (chạy trên máy local)
scp ~/Downloads/cookies.json [email protected]:/volume1/docker/bananaapi/kctapi/har_and_cookies/aistudio_cookies.json

# Hoặc nếu có File Station, upload file trực tiếp qua web interface
# Sau đó di chuyển file đến /volume1/docker/bananaapi/kctapi/har_and_cookies/

Lưu ý quan trọng:

• Bạn có thể thêm nhiều file cookies JSON vào thư mục này
• API sẽ tự động luân phiên sử dụng các cookies khi có nhiều file
• Tên file cookies không bắt buộc phải có định dạng cụ thể
• Với Synology NAS, bạn có thể upload cookies qua web File Station hoặc SCP

⁠🚀 Chạy Container với Docker

⁠Chạy cơ bản

Linux / macOS:

docker run -d \
  --name gemini-api \
  -p 5006:5006 \
  -v $(pwd)/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Windows (PowerShell):

docker run -d `
  --name gemini-api `
  -p 5006:5006 `
  -v "${PWD}\har_and_cookies:/app/kctapi/har_and_cookies" `
  xehopnet/geminiapi:1.0.1

Windows (CMD):

docker run -d --name gemini-api -p 5006:5006 -v "%CD%\har_and_cookies:/app/kctapi/har_and_cookies" xehopnet/geminiapi:1.0.1

Synology NAS (SSH Terminal):

docker run -d \
  --name gemini-api \
  -p 5006:5006 \
  -v /volume1/docker/bananaapi/kctapi/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Hoặc dùng Docker GUI trên Synology DSM:

1. Mở Container Manager (hoặc Docker trong DSM)
2. Chọn Container > Add > Add with Docker run
3. Nhập lệnh:

docker run -d --name gemini-api -p 5006:5006 -v /volume1/docker/bananaapi/kctapi/har_and_cookies:/app/kctapi/har_and_cookies xehopnet/geminiapi:1.0.1

1. Hoặc dùng Create với giao diện GUI:
   • Image: xehopnet/geminiapi:1.0.1
   • Container name: gemini-api
   • Enable auto-restart: ✓
   • Network: Bridge
   • Port settings:
     • Host port: 5006 → Container port: 5006
   • Volume settings:
     • /volume1/docker/bananaapi/kctapi/har_and_cookies → /app/kctapi/har_and_cookies

⁠Chạy với cấu hình tùy chỉnh

Linux / macOS:

docker run -d \
  --name gemini-api \
  -p 5006:5006 \
  -v $(pwd)/har_and_cookies:/app/kctapi/har_and_cookies \
  -e AUTH_TOKEN=your-secure-token \
  xehopnet/geminiapi:1.0.1

Windows (PowerShell):

docker run -d `
  --name gemini-api `
  -p 5006:5006 `
  -v "${PWD}\har_and_cookies:/app/kctapi/har_and_cookies" `
  -e AUTH_TOKEN=your-secure-token `
  xehopnet/geminiapi:1.0.1

Synology NAS (SSH Terminal):

docker run -d \
  --name gemini-api \
  -p 5006:5006 \
  -v /volume1/docker/bananaapi/kctapi/har_and_cookies:/app/kctapi/har_and_cookies \
  -e AUTH_TOKEN=your-secure-token \
  xehopnet/geminiapi:1.0.1

⁠Giải thích các tham số:

• -d: Chạy container ở chế độ detached (nền)
• --name gemini-api: Đặt tên container là gemini-api
• -p 5006:5006: Map port 5006 của container ra port 5006 của host
• -v $(pwd)/har_and_cookies:/app/kctapi/har_and_cookies: Mount thư mục cookies từ host vào container
• xehopnet/geminiapi:1.0.1: Tên image Docker

⁠Kiểm tra container đang chạy

docker ps
docker logs gemini-api

⁠📡 Sử dụng API

API chạy tại: http://localhost:5006

⁠1. Kiểm tra health

curl http://localhost:5006/health

⁠2. Chat Completion (tương thích OpenAI)

curl -X POST http://localhost:5006/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Xin chào, bạn là ai?"}
    ]
  }'

⁠3. Tạo ảnh (Text-to-Image)

curl -X POST http://localhost:5006/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "một thành phố tương lai lúc hoàng hôn",
    "n": 1
  }'

⁠4. Tạo ảnh từ ảnh tham chiếu (Image-to-Image)

curl -X POST http://localhost:5006/v1/images/generations \
  -F "model=gemini-2.5-flash-image" \
  -F "prompt=Phong cách như ảnh tham chiếu" \
  -F "images=@/path/to/your/image.png"

⁠🔌 Các Endpoint

⁠GET /health

Kiểm tra trạng thái API

Response:

{
  "status": "healthy"
}

⁠POST /v1/chat/completions

Chat completion tương thích với OpenAI format

Request Body:

{
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "user", "content": "Prompt của bạn"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

⁠POST /v1/images/generations

Tạo ảnh từ text hoặc từ ảnh tham chiếu

Text-to-Image (JSON):

{
  "model": "gemini-2.5-flash-image",
  "prompt": "Mô tả ảnh bạn muốn tạo",
  "n": 1,
  "size": "1024x1024"
}

Image-to-Image (Multipart):

model: gemini-2.5-flash-image
prompt: Mô tả
images: [file1.png, file2.png]
n: 1

⁠Lưu ảnh từ response

Response trả về ảnh dạng base64:

{
  "created": 1730000000,
  "data": [
    {"b64_json": "iVBORw0KGgoAAAANS..."}
  ]
}

Lưu ảnh trên Linux/macOS:

curl -s http://localhost:5006/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash-image","prompt":"test"}' | \
python3 -c "import sys, json, base64; data=json.load(sys.stdin); open('output.png','wb').write(base64.b64decode(data['data'][0]['b64_json'])); print('Saved output.png')"

⁠⚙️ Xử lý sự cố

⁠Container không khởi động

# Xem logs
docker logs gemini-api

# Kiểm tra container đã stop
docker ps -a

# Restart container
docker restart gemini-api

⁠Cookies hết hạn

1. Kiểm tra logs để xem lỗi:

docker logs gemini-api | grep -i "cookie"

1. Export cookies mới từ Google AI Studio (theo hướng dẫn ở trên)

2. Copy file cookies mới vào thư mục har_and_cookies

3. Restart container:

docker restart gemini-api

⁠Port đã được sử dụng

Nếu port 5006 đã bị chiếm, thay đổi port mapping:

Linux / macOS:

docker run -d \
  --name gemini-api \
  -p 8888:5006 \
  -v $(pwd)/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Windows (PowerShell):

docker run -d `
  --name gemini-api `
  -p 8888:5006 `
  -v "${PWD}\har_and_cookies:/app/kctapi/har_and_cookies" `
  xehopnet/geminiapi:1.0.1

Synology NAS (SSH Terminal):

docker run -d \
  --name gemini-api \
  -p 8888:5006 \
  -v /volume1/docker/bananaapi/kctapi/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Sau đó truy cập API tại: http://localhost:8888 (hoặc http://<synology-ip>:8888)

⁠Xóa container cũ

Linux / macOS:

# Stop và xóa container
docker stop gemini-api
docker rm gemini-api

# Hoặc chạy lại với --rm để tự động xóa khi stop
docker run --rm \
  --name gemini-api \
  -p 5006:5006 \
  -v $(pwd)/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Windows (PowerShell):

# Stop và xóa container
docker stop gemini-api
docker rm gemini-api

# Hoặc chạy lại với --rm để tự động xóa khi stop
docker run --rm `
  --name gemini-api `
  -p 5006:5006 `
  -v "${PWD}\har_and_cookies:/app/kctapi/har_and_cookies" `
  xehopnet/geminiapi:1.0.1

Synology NAS (SSH Terminal):

# Stop và xóa container
docker stop gemini-api
docker rm gemini-api

# Hoặc chạy lại với --rm để tự động xóa khi stop
docker run --rm \
  --name gemini-api \
  -p 5006:5006 \
  -v /volume1/docker/bananaapi/kctapi/har_and_cookies:/app/kctapi/har_and_cookies \
  xehopnet/geminiapi:1.0.1

Hoặc dùng Docker GUI trên Synology DSM:

1. Mở Container Manager > chọn container gemini-api
2. Click Action > Stop để dừng container
3. Click Action > Delete để xóa container

⁠🔒 Bảo mật

• Mặc định, API không yêu cầu authentication token
• Để bảo mật, bạn nên chạy container trong môi trường nội bộ hoặc sử dụng reverse proxy (nginx, traefik) với authentication
• Không chia sẻ file cookies của bạn với người khác

⁠📝 Ghi chú

• API sử dụng cookie-based authentication với Google Gemini
• Cookies sẽ tự động được làm mới nếu có nhiều file cookies trong thư mục
• Thư mục cookies được mount từ host để có thể cập nhật dễ dàng mà không cần rebuild image
• Container sẽ tự động restart nếu crash (với --restart always)

⁠🔗 Liên kết hữu ích

• J2TEAM Cookies Extension⁠
• Google AI Studio⁠
• Docker Documentation⁠

⁠📄 License

MIT License