Amm1rr/WebAI-to-API

무엇인가요

WebAI‑to‑API 는 당신의 머신(또는 Docker 컨테이너) 내부에서 실행되는 소규모 자체 호스팅 서비스로, Google Gemini 모델로의 요청을 전달합니다. 일반적으로 사용하는 /v1/chat/completions OpenAI 스타일의 엔드포인트를 제공하므로, OpenAI와 통신하는 모든 클라이언트가 이를 대상으로 지정할 수 있습니다.

핵심 기능

스트리밍(SSE) 지원이 있는 OpenAI 호환 채팅 엔드포인트(/v1/chat/completions)
제공자 기반 아키텍처 — 현재 공식 WebAPI 또는 Playwright 기반 브라우저 런타임을 통해 Gemini와 통신할 수 있는 Gemini 제공자를 포함
클라이언트가 전체 대화 기록을 관리하는 상태 없는 "Hermes" 모드 (서버 측 SQLite 스냅샷 없음)
건강 상태(/health) 및 준비 상태(/ready) 프로브, 실행 중 진단(/v1/runtime/status)
상태, 인증, 모델 탐지 및 플레이그라운드를 제공하는 간단한 웹 대시보드(/ui)
Docker 우선 배포; Poetry로 직접 실행도 가능
내장된 호출자 인증 없음 — 로컬호스트 또는 자체 방화벽 뒤를 가정

빠른 시작 (Linux/macOS)

# 1. 복제 및 설치
git clone https://github.com/Amm1rr/WebAI-to-API.git
cd WebAI-to-API
./install.sh   # 종속성, Poetry, Playwright Chromium 설치, 설정 파일 생성

# 2. Gemini에 인증 (브라우저 로그인 또는 쿠키 캐시)
poetry run python verify_login.py

# 3. 서버 실행
poetry run python src/run.py

API는 http://localhost:6969 에서, 대시보드는 http://localhost:6969/ui 에서 접근 가능합니다.

Docker 배포

git pull
APP_UID=$(id -u) APP_GID=$(id -g) docker compose up -d --build

Docker 이미지는 동일한 엔드포인트를 노출하며 동일한 인증 도구를 포함합니다.

요청 보내기

curl -X POST http://localhost:6969/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gemini-3-flash",
        "messages": [{"role": "user", "content": "Hello!"}]
      }'

응답은 OpenAI 채팅 스키마를 따르며, Server-Sent Events를 통해 스트리밍이 가능합니다.

제공자 및 모델 라우팅

gemini-3-flash — 설정된 Gemini 백엔드(webapi 또는 playwright)를 사용
playwright/gemini-3-flash — Playwright 기반 브라우저 런타임을 강제로 사용
엔드포인트 /v1/models 는 실시간 모델 카탈로그를 반환합니다. 예: gemini-3-flash 및 playwright/gemini-3-flash

설정 기본

설정은 config.conf (INI 형식)에 있습니다. 주요 섹션:

[Gemini]
backend = webapi          # 또는 "playwright"
default_model = gemini-3-flash
extended_thinking = false

프록시, 로깅, 추가 제공자 옵션도 구성 가능; 환경 변수는 .env에서 읽습니다.

보안 주의사항

이 서비스는 API 키를 강제하지 않습니다. 외부에 노출할 경우 localhost에 제한하거나, 인증을 추가하는 리버스 프록시 뒤에 배치하세요.

문서 및 도움말

설치, 설정, 업데이트 가이드는 docs/에 있습니다
서버 실행 후 Swagger UI(/docs)를 통해 인터랙티브 API 문서 사용 가능
대시보드(/ui)는 실행 상태, 인증 상태를 보여주며, 호출 테스트도 가능

라이선스

MIT — 자유롭게 사용, 수정, 재배포 가능합니다.