AI Studio to OpenAI, Anthropic & Gemini Compatible API

핵심 기능

• 이중 할당 채널: 각 계정은 Playground와 Build 애플리케이션 프록시 두 가지 독립적인 할당량을 갖습니다. UPSTREAM_CHANNELS를 개별적으로 또는 동시에 활성화할 수 있으며, 한 채널에서 제한에 도달하면 동일한 계정이 다른 채널을 계속 사용할 수 있습니다.

• Build 대화 모델: Build 대화 패널의 선택 가능한 각 모델은 <모델>-build (예: gemini-3.8-flash-build)를 제공합니다. 이는 Build 코드 어시스턴트가 시스템 프롬프트와 함께 응답하는 방식으로, 사용량은 Build 대화 할당량에 포함됩니다(무료 요청 또는 Google AI 구독 할당량). ⚠️ 이러한 모델의 각 요청에는 Build 코드 어시스턴트 고유의 시스템 프롬프트 주입이 포함되므로, 답변 스타일, 형식 및 정체성에 영향을 받을 수 있습니다. 사용 목적에 따라 직접 평가해야 합니다.

• 다계정 고부하 처리: Free, Pro, Ultra 및 Plus 권한을 식별하고, 실시간 모델 카탈로그를 기반으로 계정 간 순환 또는 우선 재사용합니다.

• 두 가지 WAA 백엔드: 기본적으로 Camoufox가 공식 WAA(Web Application Automation) 수명 주기를 보유합니다. WAA_BACKEND=go로 설정하면 순수 Go가 공식 proof를 생성하며, 실행 시 브라우저 다운로드나 시작이 필요 없습니다.

• 네 가지 API 프로토콜: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 및 Gemini GenerateContent를 지원합니다. Responses는 /v1/responses/compact와 compaction, compaction_trigger 입력 항목을 통한 컨텍스트 압축 기능을 지원합니다.

• 주요 에이전트 클라이언트: Claude Code, Codex, OpenCode, pi, omp, OpenClaw, Hermes의 파일 읽기/쓰기 도구 호출을 지원하며, Claude Code, Codex, omp의 네이티브 인터넷 검색은 직접 사용할 수 있습니다.

• 네이티브 스트리밍 응답: 본문, 사고 요약, 함수 호출, Google 도구, 미디어 및 사용량(usage)을 실시간으로 출력

• 함수 도구: 네 가지 프로토콜을 지원하는 도구 호출 및 연결, 도구 선택 및 엄격한 매개변수 검증 지원; 합집합 타입 및 개방형 파라미터 정의 지원

• TTS 음성 생성: Gemini TTS 모델의 단일/다중 화자 오디오 생성 지원

• 이미지 생성: Nano Banana 이미지 생성 지원

• 비디오 생성: Veo 비디오 생성 및 이미지-투-비디오 지원; Gemini Omni는 네 가지 생성 인터페이스를 통해 텍스트, 이미지 및 비디오 입력을 받아 텍스트와 MP4 비디오를 출력

• YouTube 입력: 비디오 URL을 붙여넣기만 하면 외부 비디오 첨부 파일로 읽기 가능

• 지능형 모델 전환: AI Studio에서 모델을 실시간으로 발견하고 model 필드를 통해 라우팅

• Google 도구: Search, Image Search, URL Context, Code Execution 및 Maps 지원

• Files 및 Transcribe: 파일 업로드, 조회, 내용 읽기, 삭제 및 오디오 전사(transcription) 지원

• Live 및 Robotics: WebSocket을 통해 텍스트, 오디오, JPEG, 미디어 종료, 도구 호출, 복원 및 중단 지원

• 반지문 감지: Camoufox를 사용하여 공식 WAA 생명주기를 유지하고, 각 계정별 고정 브라우저 지문 및 출구(exit) 제공

• 그래픽 사용자 인터페이스(GUI) 실행기: 웹을 통해 계정 관리, 서비스 시작/중지, 실시간 로그, 모델, 요청, 사용량 통계 및 구성 관리; 인터페이스는 다크 모드와 라이트 모드 두 가지 색상을 제공

• 온라인 업데이트: 관리자 '버전' 페이지에서 최신 배포 버전과 업데이트 설명을 표시하며, Windows, Linux 및 macOS 배포 패키지를 원클릭 다운로드, 검증 및 새 버전으로 재시작 가능

• 모듈식 아키텍처: Go는 프로토콜, 스케줄링, API 및 관리자를 담당하고, Camoufox가 WAA 런타임과 격리 로그인을 담당함

시스템 요구 사항

• Windows Release 실행: Windows 10 이상 버전, aistudio2api.exe 및 start.bat 필요
• Linux Release 실행: linux-amd64.tar.gz 압축 해제 후 ./aistudio2api 실행; Camoufox는 Firefox 계열 런타임이 필요하며, Debian/Ubuntu의 경우 다음 명령을 실행해야 함: sudo apt install libgtk-3-0 libasound2 libnss3 libdbus-glib-1-2 libxtst6 libxrandr2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libxcomposite1 libxdamage1 libxfixes3 xvfb
• 소스 코드 실행: Go 1.26.0+ 및 Node.js 22.13+ 또는 24+와 해당 npm 필요
• 운영 체제: Windows, macOS, Linux
• 메모리: 단일 계정 기준 2GB 이상 사용 가능한 메모리 권장; 각 상주 예열(pre-warmed) 계정당 약 0.6GB 추가 증가
• 네트워크: Google AI Studio 접속을 위한 안정적인 인터넷 연결 필요

설치 단계

방식 1: Windows 원클릭 시작 (권장)

Releases에서 windows-amd64.zip 배포 패키지를 다운로드하여 압축을 풀고 start.bat을 실행합니다. 이 배포 패키지에는 관리 인터페이스가 포함되어 있어 바로 실행할 수 있습니다.

소스 코드로부터 시작하는 경우:

git clone https://github.com/Mag1cFall/AIStudio2API.git
cd AIStudio2API
copy .env.example .env

이후 start.bat을 더블 클릭하여 실행합니다. Windows PowerShell에서도 다음 명령으로 직접 실행할 수 있습니다:

.\start.bat

이미 aistudio2api.exe가 있는 경우 스크립트가 즉시 실행되며; 소스 코드 디렉토리에 실행 파일이 없는 경우, 스크립트가 프론트엔드 종속성을 자동으로 설치하고 프론트엔드와 Go 프로그램을 빌드합니다.

최초 시작 시 현재 플랫폼의 Camoufox를 runtime/camoufox/에 자동 다운로드하며, 이 다운로드는 첫 번째 프록시를 통해 전송됩니다. 시스템 프록시가 설정되지 않은 경우 사용됩니다; 다운로드가 중단된 경우 다음 시작부터 이미 다운로드된 부분부터 재개됩니다. 또한 환경 변수 CAMOUFOX_PATH를 통해 기존 실행 파일을 지정할 수도 있습니다.

방식 2: Linux 및 macOS 소스 코드 빌드

1. 종속성 설치

• Go 1.26.0 이상 버전
• Node.js 22.13+ 또는 24+와 해당 npm 필요

2. 프로젝트 클론

git clone https://github.com/Mag1cFall/AIStudio2API.git
cd AIStudio2API
cp .env.example .env

3. 빌드 및 실행

cd web
npm ci
npm run build
...

Linux와 macOS에서는 최초 실행 시 해당 플랫폼에 맞는 Camoufox가 자동으로 준비됩니다.

방법 3: Docker

mkdir aistudio2api && cd aistudio2api
curl -fsSLO https://raw.githubusercontent.com/Mag1cFall/AIStudio2API/main/docker-compose.yml
mkdir data
...

이미지는 linux/amd64와 linux/arm64를 지원하며, 서비스는 컨테이너 내부에서 0.0.0.0:2048을 수신합니다. data/에는 .env, auth/, 그리고 runtime/이 저장되며, Camoufox 백엔드는 최초 시작 시 Camoufox를 data/runtime/camoufox/에 다운로드합니다. 기존 설치를 마이그레이션 할 경우 이 세 항목을 data/로 복사해야 합니다. 컨테이너는 root 권한으로 실행되므로, 서비스가 data/에 쓰는 파일은 root 소유이며, Linux 호스트에서는 sudo를 사용하여 편집해야 합니다.

• 포트를 외부에 개방할 때는 PROXY_API_KEY를 설정합니다. 컨테이너 외부에서 관리 페이지를 열려면 ADMIN_AUTH_ENABLED=true와 관리 비밀번호가 필요하며, 사용자 이름은 기본적으로 admin입니다.
• 계정 추가: Google에 로그인 가능한 컴퓨터의 auth/<Google 이메일>/ 폴더를 data/auth/로 복사하거나, 관리 페이지의 계정 탭에서 '원격 추가'를 클릭하여 페어링 토큰을 얻은 후, SSH 터널링(ssh -L 2048:127.0.0.1:2048 <서버>)을 거쳐 해당 컴퓨터에서 setup --remote http://127.0.0.1:2048를 실행합니다.
• PROXY와 계정 프록시는 컨테이너 내부에서 접근하며, 프록시가 호스트(host)에서 실행되는 경우 호스트의 로컬 네트워크 주소를 기입하고 프록시가 로컬 네트워크 연결을 수락하도록 허용해야 합니다.
• data/.env를 수정했다면 docker compose restart를 실행합니다. 이미지를 업데이트하려면 docker compose pull && docker compose up -d를 실행하고, 소스 코드 디렉토리에서 docker compose up -d --build를 실행하여 소스 코드로 빌드합니다.

빠른 시작

최초 사용 (인증 필요)

1. 첫 번째 계정 준비:

   Windows의 경우, 로컬 Chrome 계정을 가져올 수 있습니다:

   복사

   start.bat setup
   

   1

   2

   Linux와 macOS는 격리된 Camoufox로 로그인합니다:

   복사

   ./aistudio2api setup --login
   

   1

   2

   로그인 완료 후 AI Studio 페이지에서 Google 이메일을 읽어오고, 계정에 Google Drive 권한을 부여합니다. 계정은 .env 파일의 AISTUDIO_AUTH_STATES가 가리키는 폴더에 저장됩니다. 언어와 시간대는 기본적으로 현재 컴퓨터 설정을 따르며, --locale 또는 --timezone으로 지정할 수도 있습니다.

2. 그래픽 인터페이스 시작:

   • Windows: start.bat 더블클릭
   • Linux 및 macOS: ./aistudio2api 실행
   • 브라우저가 자동으로 http://127.0.0.1:2048을 엽니다.
   • 페이지 초기 상태는 STOPPED이며, 기본적으로 '로그' 페이지가 표시됩니다.

3. 다른 계정 추가:

   • '계정' 페이지를 엽니다.
   • 'Chrome 일괄 가져오기(Chrome batch import)'를 통해 여러 개의 로컬 Chrome 계정을 선택할 수 있습니다.
   • '브라우저 로그인(Browser login)'을 실행하면 독립적인 Camoufox 창이 열리고, 로그인 완료 후 이메일과 Google Drive 권한이 자동으로 인식되어 저장됩니다. Google에서 본인 인증을 요구하는 경우, 해당 창 또는 휴대폰으로 확인해야 합니다.

4. API 시작:

   • '서비스 시작' 버튼을 클릭하여 데이터면(data plane)을 시작합니다.
   • 상태가 순차적으로 LAUNCHING과 RUNNING을 표시하며, LAUNCHING 중에는 '서비스 중지'를 클릭하여 시작을 취소할 수 있습니다.
   • '로그' 페이지에서 계정, 모델 및 요청 상태를 확인합니다.
   • API는 기본적으로 http://127.0.0.1:2048을 수신합니다.

계정 작업은 상태 표시와 함께 진행됩니다:

일상 사용 (이미 인증된 경우)

1. Windows에서 start.bat을 더블 클릭하고, Linux 및 macOS에서는 ./aistudio2api를 실행합니다.
2. "서비스 시작"을 클릭하여 API를 활성화하고, AUTO_START=true로 설정하면 프로그램이 시작될 때 자동으로 서비스가 시작됩니다.
3. "서비스 중지"를 클릭하면 진행 중인 시작 또는 활동 요청이 취소되고 WAA Worker가 종료되며, 관리 페이지와 로그는 계속 사용할 수 있습니다.
4. 다시 "서비스 시작"을 클릭하여 API를 복구할 수 있습니다.

중지 후 재시작하면 최신 .env 파일을 읽어 서비스 구성을 생성하며, 계정 선택 정책과 Worker 용량이 저장된 후 즉시 적용됩니다. 관리 페이지 주소와 PROXY_API_KEY는 관리 프로세스가 재시작된 후에 적용됩니다.

시작 창에서 Ctrl+C를 누르거나 창을 닫으면 전체 관리 프로세스가 종료됩니다. 브라우저 탭을 닫는 것은 관리 프로세스를 중지시키지 않습니다.

빠른 시작

start.bat: 관리 프로세스를 시작하고 웹페이지를 자동으로 엽니다.

start.bat -open-ui=false: 관리 프로세스는 시작하지만 웹페이지는 자동으로 열지 않습니다.

start.bat setup: 로컬 Chrome 계정을 스캔합니다. --email 또는 --profile을 사용하여 특정 Chrome 계정을 선택할 수도 있습니다. 격리된 로그인은 start.bat setup --login을 사용하고, 파일 가져오기는 start.bat setup --storage-state <file>을 사용합니다.

start.bat setup --remote https://<원격 인스턴스>: 원격 인스턴스에 계정을 추가합니다. 먼저 원격 인스턴스의 계정 페이지에서 "원격 추가"를 클릭하여 페어링 토큰을 얻은 다음, Google에 로그인할 수 있는 컴퓨터에서 이 명령어를 실행하고 토큰을 붙여넣습니다. --login 등 다른 매개변수와 조합할 수 있습니다.

API 사용

OpenAI 호환 인터페이스

서비스가 시작된 후에는 OpenAI Chat Completions를 바로 사용할 수 있습니다:

curl http://127.0.0.1:2048/v1/chat/completions \
  -H "Authorization: Bearer 123" \
  -H "Content-Type: application/json" \
...

클라이언트 설정 예시

Cherry Studio의 예시:

1. Cherry Studio 설정 열기
2. OpenAI 호환 제공업체 추가
3. API 기본 주소에 http://127.0.0.1:2048/v1 입력
4. API 키에 .env의 PROXY_API_KEY 입력
5. /v1/models에서 모델을 가져오거나, 수동으로 gemini-3.6-flash, gemini-3.7-flash를 추가합니다.

Claude Code는 Anthropic 인터페이스를 사용하며, 서브 에이전트는 opus, sonnet, haiku 등급으로 모델을 선택하고, 다음 변수들은 이를 AI Studio 모델에 매핑합니다. WebSearch는 Google Search로 실행됩니다:

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:2048"
$env:ANTHROPIC_API_KEY = "<PROXY_API_KEY>"
$env:ANTHROPIC_MODEL = "gemini-3.8-flash"
...

Codex의 Responses 인터페이스를 사용하고, ~/.codex/config.toml에 provider를 추가하며, PROXY_API_KEY를 AISTUDIO2API_KEY 환경 변수에 작성합니다. Codex의 web_search 도구는 Google Search로 실행됩니다:

model = "gemini-3.8-flash"
model_provider = "aistudio"

...

omp의 web_search 도구는 web 역할을 사용하는 모델 검색을 이용합니다. omp의 models.yml에 본 서비스로 연결되는 Gemini provider(apiKey는 PROXY_API_KEY가 저장된 환경 변수 이름)를 추가하고, config.yml에서 web 역할을 해당 모델로 설정합니다:

# models.yml
providers:
  aistudio-gemini:
...

# config.yml
modelRoles:
  web: aistudio-gemini/gemini-3.8-flash

주요 엔드포인트:

생성 요청 내의 인라인 첨부 파일은 임시 Drive 파일로 우선 업로드되며, 요청 종료 시 정리됩니다. 계정에 Drive 권한이 부여되지 않은 경우 인라인 데이터 전송 방식으로 유지됩니다. 이미지, 오디오, 비디오, PDF 등의 입력은 여전히 선택된 모델의 지원을 받아야 합니다. 재사용 가능한 첨부 파일은 Files 인터페이스를 통해 한 번 업로드하고 파일 ID를 재활용할 수 있습니다.

Gemini 첨부 파일과 비디오/이미지 입력은 inlineData / inline_data, fileData / file_data, mimeType / mime_type, 그리고 fileUri / file_uri를 지원합니다. 미디어 Base64 데이터는 표준 및 URL-safe 알파벳, 패딩 유무 형식, 그리고 data:<MIME>;base64, 접두사를 지원합니다. OpenAI 어시스턴트 히스토리의 Markdown 이미지 역시 URL-safe Base64와 CR/LF 줄 바꿈을 지원합니다. 인라인 GIF 및 비디오 폼 제출 시, GIF는 첫 프레임 정지 이미지로 PNG로 변환되며, 로직 캔버스, 프레임 위치, 투명 배경이 유지됩니다.

TTS 음성 생성

TalkifyTTS는 최신 Google Gen AI SDK와 연결하여 http://127.0.0.1:2048/v1beta/interactions를 사용할 수 있으며, 안정 버전 엔트리는 /v1/interactions입니다. 요청은 x-goog-api-key를 사용하며, gemini-3.8-flash-tts와 gemini-3.8-flash-lite-tts를 지원합니다:

from google import genai

client = genai.Client(api_key="123", http_options={"base_url": "http://127.0.0.1:2048"})
...

스트리밍 오디오는 기본적으로 Base64로 인코딩된 24 kHz, 16-bit 리틀 엔디언, 모노 채널 PCM이며, 비스트리밍은 완전한 WAV가 기본값으로 설정되어 interaction.output_audio.data를 통해 읽을 수 있습니다. response_format.mime_type에서 audio/l16 또는 audio/wav를 명시적으로 선택할 수 있습니다. 스타일 및 다중 화자 입력은 Interactions 프로토콜을 참조하십시오.

다중 화자 음성은 Gemini의 generateContent 내 multiSpeakerVoiceConfig를 통해 구성할 수 있습니다.

curl http://127.0.0.1:2048/v1beta/models/gemini-2.5-flash-preview-tts:generateContent \
  -H "x-goog-api-key: 123" \
  -H "Content-Type: application/json" \
...

사용 가능한 음성은 실시간 모델 디렉토리의 capability_options.voices에서 반환됩니다. gemini-3.8-flash-tts와 같이 speech_metadata 기능을 갖춘 모델도 위의 '화자: 대사' 형식을 지원하며, 각 텍스트 part에 대해 speechMetadata.speaker 및 speechMetadata.style을 설정할 수 있고, multiSpeakerVoiceConfig.mode를 사용하여 VERBATIM 또는 CONVERSATIONAL을 선택할 수 있습니다. OpenAI의 instructions는 이러한 모델에서 음성 스타일로 사용됩니다.

이미지 생성 (Nano Banana)

curl http://127.0.0.1:2048/v1/images/generations \
  -H "Authorization: Bearer 123" \
  -H "Content-Type: application/json" \
...

비디오 생성 (Veo)

curl http://127.0.0.1:2048/v1/videos \
  -H "Authorization: Bearer 123" \
  -H "Content-Type: application/json" \
...

생성 작업 후에는 GET /v1/videos/{id}로 상태를 조회하고, GET /v1/videos/{id}/content로 결과를 다운로드합니다.

모델

모델 디렉토리는 AI Studio가 업데이트됨에 따라 업데이트되며, 클라이언트는 /v1/models 또는 /v1beta/models에서 현재 값을 읽습니다. 아래 표는 디렉토리 구조의 예시를 유지하며, 모델 ID, 제한 및 방법은 런타임 결과에 따릅니다:

활성화된 구독이 불충분한 모델(예: Google AI Ultra에만 개방된 모델)도 디렉토리에 나열되며, channels는 포함되지 않습니다. 호출 시 403 오류가 반환되고 필요한 구독 정보가 명시됩니다. output_continuation 기능을 포함하는 모델(예: Gemini 4 Argon)은 공식 웹사이트와 마찬가지로 input_token_limit의 출력 상한을 받아들이며, 32768 토큰 초과 시 라운드별 자동 연속 쓰기가 이루어지고, 각 라운드의 출력이 하나의 응답으로 병합됩니다. 모델명에는 사고(思考) 접미사(suffix)가 붙을 수 있습니다. 예를 들어 gemini-4-argon(low)와 같이 괄호 안은 none, minimal, low, medium, high, xhigh, max, auto 또는 사고 예산 토큰 수를 나타냅니다. 이 접미사는 요청 본문의 사고 매개변수보다 우선합니다. 클라이언트가 하드코딩한 모델명은 MODEL_MAPPING을 사용하여 디렉토리의 모델로 매핑할 수 있습니다. 예를 들어 MODEL_MAPPING=claude-haiku-5-5:gemini-3.8-flash와 같이 사용하며, 별칭(alias)은 대상 모델의 필드에 나열됩니다.

프로젝트 아키텍처

AIStudio2API/
├── cmd/aistudio2api/        # 얇은 진입점 (Thin Entry)
├── internal/app/            # 명령, 관리 리스너, 생성 서비스 생명 주기 및 스케줄링
...

설정 설명

환경 변수 설정

환경 구성 파일을 복사하고 편집합니다:

cp .env.example .env

포트 설정

관리 콘솔은 기본적으로 로컬 루프백 주소를 통해 비밀번호 없이 접근할 수 있습니다. 원격 관리 시 ADMIN_AUTH_ENABLED=true와 관리자 계정 및 비밀번호를 설정하면, 프로그램 재시작 후 독립적인 /login 페이지를 통해 로그인해야 합니다. 로그인 세션 유효 기간은 12시간이며 로그아웃을 지원합니다. 관리자는 동일한 계정 풀, 구성 및 로그를 공유합니다. 공개 API는 독립적인 PROXY_API_KEY를 사용합니다.

리버스 프록시는 HTTPS를 사용하며 원본 Host 헤더를 유지하고 X-Forwarded-Proto: https를 설정합니다. 관리 페이지의 '서비스 설정'에서 로그인 스위치 및 자격 증명을 조정할 수 있으며, 저장 후 프로그램을 재시작해야 적용됩니다.

• 관리 페이지와 API: 기본 포트 2048
• Camoufox: 프로그램이 동적으로 로컬 포트를 할당합니다.

고급 기능

프록시 설정

HTTP, HTTPS 또는 SOCKS5 프록시를 통해 AI Studio에 접근하는 것을 지원하며, 프록시에 인증이 필요한 경우 URL에 계정 및 비밀번호를 기입해야 합니다. 예를 들어 socks5://user:password@host:1080와 같습니다:

1. '서비스 설정'에서 전역 프록시를 설정합니다. 비워두면 시스템 프록시를 사용하며, 먼저 HTTPS_PROXY 환경 변수를 읽고, 설정되지 않은 경우 Windows 시스템 프록시 설정을 읽습니다. 프록시 입력란 아래에 현재 생성 서비스가 실제로 사용하는 출구(exit)가 표시됩니다.
2. 전역 프록시는 여러 개를 기입할 수 있으며, 쉼표로 구분하여 프록시 풀을 구성합니다. 전용 프록시가 없는 계정은 가장 적게 바인딩된 사용 가능한 프록시에 고정적으로 바인딩되며, 이 정보는 계정 상태에 기록되고 재시작 후에도 유지됩니다. 프록시에서 연속 3회 네트워크 오류 또는 주기적 검사 실패 시, 해당 계정은 다른 사용 가능한 프록시로 재바인딩되며, 검사가 복구되면 다시 할당에 참여합니다. '서비스 설정'에는 각 프록시의 상태와 바인딩된 계정 수가 나열되고, 계정 카드에는 각 계정의 출구가 표시됩니다.
3. '계정' 페이지에서 개별 계정을 편집할 때 해당 계정에 전용 프록시를 설정할 수 있습니다.
4. 계정 프록시는 로그인, WAA(Web Automation Agent) 및 비즈니스 요청에 모두 사용됩니다.
5. 계정/비밀번호가 포함된 대리는 프로그램이 로컬 루프백 주소에서 인증 없는 SOCKS5 중계 기능을 제공하여 Camoufox가 사용할 수 있게 합니다. 이 경우 계정/비밀번호는 브라우저 프로필에 기록되지 않습니다. 중계 실행 기간 동안, 로컬의 다른 프로세스도 이를 통해 해당 프록시를 사용할 수 있습니다.

인증 파일 관리

인증 파일은 기본적으로 auth/ 디렉토리에 저장됩니다.