만약 통합 배포를 시도하려면 integrated 브랜치를 사용하세요. 또한 Gemini 쿠키는 만료가 빠릅니다.

Gemini Canvas to API Adapter

중국어 문서 | English

Gemini 웹 세션을 OpenAI API, Gemini API 및 Anthropic API와 호환되도록 캡슐화한 도구입니다. 서버 측은 API 인터페이스와 요청 스케줄링을 담당하며, 실제 브라우저 세션은 사용자가 지정된 Gemini 공유 페이지를 수동으로 열어 서버 측과 연결을 설정해야만 요청 처리가 가능합니다.

✨ 기능 특성

• 🔄 API 호환성: OpenAI API, Gemini API 및 Anthropic API 형식을 동시에 지원합니다.
• 🌐 모델 지원: Gemini 3 Flash Preview를 지원하며, 거의 무제한 호출이 가능합니다.
• 🔁 다중 세션 스케줄링: 여러 브라우저 세션을 동시에 연결하여 요청을 순환(polling) 또는 무작위 전략으로 분배할 수 있습니다.
• 🔧 도구 호출 지원: OpenAI, Gemini 및 Anthropic 인터페이스 모두 Tool Calls (Function Calling)를 지원합니다.
• 📊 시각화 콘솔: 서비스 실행 상태 관찰에 편리하도록 상태 페이지, 로그 페이지, 온라인 설정 스위치를 제공합니다.

🚀 빠른 시작

💻 직접 실행 (Windows / macOS / Linux)

1. 레포지토리를 클론하고 의존성을 설치하세요:

git clone https://github.com/iBUHub/CanvasToAPI.git
cd CanvasToAPI
npm install

2. 환경 변수를 설정하세요:

cp .env.example .env

최소한 다음을 설정하는 것이 권장됩니다:

API_KEYS=your-api-key

3. 서비스를 시작하세요:

npm start

4. 콘솔을 여세요:

http://localhost:7861에 접속하여 API_KEYS(또는 설정한 콘솔 계정 비밀번호)로 로그인합니다.

5. 브라우저 세션을 수동으로 설정하세요:

Gemini 세션을 담아야 하는 브라우저에서 다음을 엽니다: https://gemini.google.com/share/0e87cc62be50

공유 링크가 만료된 경우, Gemini 페이지를 직접 열고 Canvas 기능을 활성화한 다음, scripts/client/canvas.html의 내용을 복사하여 새 Canvas를 만드세요.

열린 후 수동으로 다음을 작성하세요:

• Server WS Endpoint: 로컬 배포 시 ws://127.0.0.1:7861/ws를 입력합니다.
• API Key: 요청 시 사용하는 것과 동일한 API_KEYS 중 임의의 key를 입력합니다.
• Browser Identifier: 브라우저 식별자이며, 사용자 정의가 가능합니다. 비워두면 페이지에서 자동으로 일일 식별자를 생성합니다.

Chrome을 브라우저로 사용하는 경우, 먼저 주소창에 chrome://flags/#local-network-access-check를 입력하고 해당 항목을 Disabled로 변경한 다음, ws://127.0.0.1:7861/ws를 통해 로컬 서버에 연결하세요.

작성 완료 후 저장(Save)을 누르고 다시 연결(Connect)을 누르세요. 연결에 성공하면 상태 페이지로 돌아가 브라우저 세션에 온라인 세션이 있는지 확인합니다.

6. API 호출 시작하기:

최소한 하나의 브라우저 세션이 온라인 상태일 때만 서버 측에서 요청을 실제로 전달하고 처리합니다.

⚠ 주의:
이전 버전 README의 npm run setup-auth, auth-N.json, VNC 로그인 및 인증 파일 업로드 등의 절차는 현재 버전에는 적용되지 않습니다.

💡 팁:
서비스가 원격 기기에 배포되어 있고 브라우저 연결이 로컬 서버가 아닌 경우, 브라우저 측에서 wss://를 사용하려면 서버 측에 리버스 프록시(reverse proxy)를 활성화해야 합니다.

🐋 Docker 배포

🚢 단계 1: 컨테이너 배포

🎮️ 방식 1: Docker 명령어

docker run -d \
  --name canvas-to-api \
  -p 7861:7861 \
...

💡 참고: ghcr.io 접속이 느릴 경우, Docker Hub 이미지를 사용할 수 있습니다: ibuhub/canvas-to-api:latest.

매개변수 설명:

• -p 7861:7861: HTTP API 및 콘솔 포트
• -e API_KEYS: 클라이언트가 API와 콘솔에 접근할 때 사용하는 키
• -e TZ=Asia/Shanghai: 로그 및 페이지 표시 시간의 시간대 (선택 사항)

📦 방식 2: Docker Compose

docker-compose.yml 파일을 생성합니다:

name: canvas-to-api
services:
...

🛠️ 방식 3: 소스 코드에서 빌드

Docker 이미지를 직접 빌드하고 싶다면, 다음 명령어를 사용할 수 있습니다:

1. 이미지 빌드:

   복사

docker build -t canvas-to-api .

2. 컨테이너 실행:

```bash
docker run -d \
  --name canvas-to-api \
  -p 7861:7861 \
... 

🔌 단계 2: 브라우저 세션 연결

컨테이너가 시작된 후에도, 다음 페이지를 수동으로 열어 브라우저 세션을 구축해야 합니다: https://gemini.google.com/share/0e87cc62be50

만약 해당 공유 링크가 만료되었다면, Gemini 페이지로 직접 이동하여 Canvas를 열고 scripts/client/canvas.html의 내용을 붙여넣어 새 Canvas를 만드세요.

페이지에서 브라우저 식별자(Browser Identifier), API 키, 그리고 서버 측 WebSocket 주소(Server WS Endpoint, 예: ws://127.0.0.1:7861/ws 또는 wss://your-host/ws)를 수동으로 입력해야 합니다. 이때 API 키는 요청 시 사용한 키와 동일하게 작성해야 합니다. 연결이 성공적으로 구축되면, 상태 페이지에 온라인 브라우저 세션이 표시되며, 이후 API 요청이 전달됩니다.

🌐 단계 3 (선택 사항): Nginx 리버스 프록시 사용

도메인을 통해 서비스에 접근하거나, 리버스 프록시 뒤에서 통합 관리하고 싶다면 Nginx를 사용할 수 있습니다.

[!중요]
브라우저 측에서 로컬이 아닌 서버에 연결해야 하는 경우, 반드시 서버에 HTTPS 리버스 프록시를 활성화하고 Nginx를 통해 wss:// 입구를 제공해야 합니다. 또한 Nginx가 WebSocket 업그레이드 요청을 올바르게 전달하는지 확인해야 하며, 최소한 proxy_http_version 1.1, proxy_set_header Upgrade $http_upgrade 및 `proxy_set_header Connection

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

🌐 프록시 설정

🗒️ 기타 설정

🔌 브라우저 세션 연결

현재 버전에서는 로컬의 auth 파일을 읽지 않으며, setup-auth 초기화 스크립트도 포함하지 않습니다. 올바른 사용 방법은 다음과 같습니다:

1. 서버 측을 시작하고, PORT가 세션을 구축할 수 있는 브라우저에서 접근 가능한지 확인합니다.
2. 콘솔을 열어 현재 브라우저 세션 연결 주소와 연결 상태를 확인합니다.
3. 브라우저에서 https://gemini.google.com/share/0e87cc62be50을 엽니다.
   만약 해당 공유 링크가 만료되었다면, Gemini 페이지로 이동하여 Canvas를 활성화하고 scripts/client/canvas.html의 내용을 사용하여 새로운 Canvas를 생성합니다.
4. 페이지에 브라우저 식별자(Browser Identifier), API Key, 그리고 서버 측 WebSocket 주소(Server WS Endpoint)를 기입합니다.
5. API Key는 API를 요청할 때 사용하는 키와 동일한 것을 작성해야 합니다. Server WS Endpoint는 로컬의 경우 ws://127.0.0.1:7861/ws를 기입할 수 있으며, 콘솔이 https://로 접근하는 원격 서비스인 경우 wss://당신의 도메인 또는 공인 IP/ws를 기입해야 합니다.
   Chrome을 브라우저 측으로 사용하는 경우, 먼저 주소창에 chrome://flags/#local-network-access-check를 입력하여 해당 항목을 Disabled로 변경한 후, 로컬 ws:// 주소를 통해 서버 측에 연결합니다.
6. 상태 페이지가 온라인 세션에 나타난 후에 API 호출을 시작합니다.

🧠 모델 목록 설정

configs/models.json 파일을 편집하여 사용 가능한 모델과 그 설정을 사용자 정의하세요.

💡 팁: 사고(Thinking) 매개변수 지원은 모델 이름 접미사를 통해 설정할 수 있습니다. 모델명 뒤에 -THINKING_LEVEL 또는 (THINKING_LEVEL)을 추가할 수 있으며, 여기서 THINKING_LEVEL은 대소문자를 구분하지 않고 high, medium, low, minimal을 지원합니다. 예시: gemini-3-flash-preview(minimal) 또는 gemini-3-flash-preview-minimal.

스트리밍 모드도 모델 이름 접미사를 통해 덮어쓸 수 있습니다. 모델명 끝에 -real 또는 -fake을 추가할 수 있습니다. 이 접미사는 시스템의 STREAMING_MODE보다 우선순위가 높지만, 스트리밍 요청에서만 유효합니다. 예시: gemini-3-flash-preview-fake. 만약 사고 접미사와 동시에 사용한다면, 참/거짓 스트림 접미사(real/fake)는 반드시 가장 마지막에 위치해야 합니다. 예시: gemini-3-flash-preview-minimal-fake 또는 gemini-3-flash-preview(minimal)-real.

📄 라이선스

본 프로젝트는 iBUHub/AIStudioToAPI를 기반으로 개발되었으며, CC BY-NC 4.0 라이선스를 채택했습니다. 사용, 배포 및 수정 행위 모두 라이선스의 모든 조항을 준수해야 하며, 전체 허가 내용은 LICENSE 파일을 참조하세요.

🤝 기여자

본 프로젝트에 땀과 지혜를 기울인 모든 개발자분들께 감사드립니다.

CanvasToAPI가 도움이 되었다고 생각하시면, 프로젝트에 별점(⭐️)을 눌러주세요!

커뮤니티 지원

AI를 배우고, L(리눅스) 사이트에 오세요.
LinuxDO