100회 제한에 걸린 Gemini API, 신규 프로젝트 생성으로 돌파하기
Gemini API 대량 작업 중 발생하는 429 RESOURCE_EXHAUSTED (일일 할당량 초과) 오류를 즉각적으로 해결하기 위한 새로운 프로젝트 생성 가이드입니다. Google Cloud의 API 할당량은 사용자 계정이 아닌 '개별 프로젝트'를 기준으로 철저하게 독립 부여됩니다. 특정 모델의 일일 호출 한도가 100회로 고정되어 상향이 불가능한 상태이더라도, 새로운 프로젝트를 생성하면 기존 작업 내역과 완전히 분리된 100회의 신규 한도를 즉시 확보하여 중단된 작업을 이어갈 수 있습니다.
1. 할당량 분리 및 우회 시스템의 핵심 원리 이해
Google Cloud 환경에서 API 호출 권한과 청구 기준은 철저하게 프로젝트(Project) 단위로 격리되어 작동합니다. 하나의 Google 계정 내에 A, B, C 세 개의 프로젝트가 존재할 경우, 각 프로젝트는 완전히 독립적인 할당량(Quota) 테이블을 가집니다.
과금 사고나 시스템 과부하를 방지하기 위해 Google은 유료 결제(Tier 1) 상태에서도 특정 최신 모델에 대해 하드 리미트(Hard Limit)를 설정합니다. 사용자가 UI를 통해 수동으로 한도 상향 요청을 제출할 수 있으나, 시스템 상한선에 도달하여 입력란 자체에 경고가 발생하며 상향이 거부되는 구간이 존재합니다. 이때 기존 프로젝트의 제한이 풀리거나 초기화되는 자정(태평양 표준시 기준)까지 기다릴 수 없는 긴급한 상황이라면, 100회의 기본 한도를 가진 깡통 프로젝트를 새로 생성하여 남은 작업을 처리하는 것이 가장 신속하고 확실한 엔지니어링 접근법입니다. 새 프로젝트는 기존 프로젝트와 리소스를 공유하지 않으므로 기존 스크립트의 실행 상태나 데이터에 어떠한 악영향도 미치지 않습니다.
2. Google Cloud 신규 프로젝트 생성 및 초기 구성
새로운 할당량을 담을 빈 공간을 만드는 과정입니다. 프로젝트 생성 즉시 시스템 백단에서 API 사용을 위한 기본 인프라가 배포됩니다.
- Google Cloud Console 접속 및 인증 웹 브라우저를 열고 [https://console.cloud.google.com/](https://console.cloud.google.com/)에 접속합니다. 기존에 작업하던 계정과 동일한 Google 계정으로 로그인되어 있는지 우측 상단의 프로필 아이콘을 통해 확인합니다.
- 새 프로젝트 만들기 페이지 진입 상단 글로벌 네비게이션 바(검색창 좌측)에 위치한 현재 프로젝트 이름(드롭다운 형태)을 클릭합니다. 나타나는 모달 창 우측 상단의 [새 프로젝트(New Project)] 버튼을 클릭하거나, [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate) 주소로 직접 이동합니다.
- 프로젝트 명명 및 위치 지정
- 프로젝트 이름: 기존 프로젝트와 혼동되지 않도록 직관적인 이름을 지정합니다. 기존 이름에 일련번호나 목적을 추가하는 방식(예: Youtube-Bible4US-Part2 또는 Voice-Generate-Temp)이 유지보수에 유리합니다.
- 프로젝트 ID: 이름 입력 시 자동으로 영문과 숫자가 조합된 고유 ID가 생성됩니다. 이 ID는 전 세계적으로 고유해야 하므로 자동 생성된 값을 그대로 유지합니다.
- 위치(조직): 개인 개발자 환경에서는 '조직 없음(No organization)'으로 두면 됩니다.
- 생성 완료 대기 [만들기] 버튼을 클릭하면 우측 상단 알림 아이콘(종 모양)에 진행 상태(스피너)가 표시됩니다. 약 10초~30초 후 '프로젝트 생성 완료' 알림이 나타나면, 해당 알림에서 [프로젝트 선택]을 누르거나 상단 드롭다운을 통해 방금 만든 새 프로젝트로 작업 환경을 전환합니다.
3. Tier 1 결제 계정 매핑 및 권한 활성화
API를 호출하기 위해서는 생성된 빈 프로젝트에 결제 수단이 연결되어 있어야 합니다. 결제가 연결되지 않으면 무료 등급(Free Tier) 환경조차 활성화되지 않거나 매우 제한적인 접근만 허용됩니다.
- 결제(Billing) 관리 메뉴 이동 새 프로젝트가 선택된 상태에서 좌측 상단의 햄버거 메뉴(☰)를 클릭하고 [결제(Billing)] 항목을 선택합니다.
- 결제 계정 연결 실행 신규 프로젝트이므로 "이 프로젝트에는 결제 계정이 없습니다"라는 안내 문구가 나타납니다. 화면 중앙의 [결제 계정 연결(Link a billing account)] 버튼을 클릭합니다.
- 기존 Tier 1 계정 선택 활성화된 결제 계정 목록을 보여주는 드롭다운 메뉴가 나타납니다. 기존에 유료 한도를 위해 세팅해 두었던 My Billing Account (Tier 1 · 선불) (또는 이와 유사한 이름의 활성 결제 계정)를 선택하고 [계정 설정(Set Account)]을 클릭합니다.
- 결제 연결 및 API 활성화 검증 화면이 새로고침되며 결제 개요 대시보드가 나타나면 정상적으로 연결된 것입니다. 하나의 결제 계정을 여러 프로젝트에 연결하더라도 별도의 기본 수수료가 발생하지 않으며, 실제 API를 호출하여 발생한 트래픽(토큰 사용량)만큼만 합산되어 청구됩니다.
4. Google AI Studio 환경 전환 및 신규 API 키 발급
할당량이 확보된 새 프로젝트와 결제 연결이 끝났으므로, 이제 파이썬 스크립트나 애플리케이션에서 해당 프로젝트에 접근할 수 있는 통행증(API Key)을 발급받아야 합니다.
- AI Studio 포털 접속 개발자 전용 포털인 [https://aistudio.google.com/](https://aistudio.google.com/)으로 이동합니다. 우측 상단 프로필을 확인하여 Google Cloud Console과 동일한 계정인지 재차 확인합니다.
- API 키 관리자 진입 화면 좌측 상단의 햄버거 메뉴(☰)를 클릭하여 사이드 패널을 열고, 열쇠 아이콘이 그려진 [Get API key] 메뉴로 진입합니다.
- 새 키 생성 프로세스 시작 화면 중앙 또는 상단의 [Create API key] 파란색 버튼을 클릭합니다.
- 신규 프로젝트 지정 및 생성
- 프로젝트 선택 모달 창이 나타나면 검색창을 클릭합니다.
- 스크롤을 내리거나 검색하여 방금 2단계에서 생성했던 새로운 프로젝트 이름(예: Youtube-Bible4US-Part2)을 찾아 선택합니다.
- [Create API key in existing project] 버튼을 클릭합니다.
- 안전한 복사 및 보관 화면에 생성된 긴 영문/숫자 조합의 API 키가 출력됩니다. 복사 아이콘을 눌러 클립보드에 저장합니다. 이 키는 유료 계정과 연결되어 있으므로 절대 GitHub 공개 저장소나 외부에 노출되지 않도록 주의해야 합니다.
5. 로컬 개발 환경 적용 및 캐시 초기화
새로운 API 키를 코드에 단순히 붙여넣는 것만으로는 기존에 실행 중이던 프로세스가 변경 사항을 인식하지 못해 동일한 오류를 뱉어낼 수 있습니다. 확실한 환경 변수 초기화가 필요합니다.
- 환경 변수(.env) 또는 하드코딩 수정 작업 중인 프로젝트 폴더를 열고 API 키가 저장된 위치로 이동합니다.
- .env 파일을 사용하는 경우: GEMINI_API_KEY="기존_키" 부분을 찾아 방금 복사한 새로운 API 키로 교체하고 파일을 반드시 저장(Ctrl+S / Cmd+S)합니다.
- 파이썬 스크립트 내부에 직접 변수로 선언한 경우: 스크립트 상단의 키 선언부를 새 키로 교체 후 저장합니다.
- 프로세스 완전 종료 및 터미널 재시작 실행 중인 기존 스크립트가 있다면 Ctrl+C를 눌러 완전히 강제 종료합니다. 코드 에디터(VS Code, PyCharm 등) 내부의 통합 터미널을 사용 중이라면 닫기(휴지통 아이콘)를 눌러 터미널 세션을 완전히 소멸시킵니다. 메모리에 캐싱된 이전 API 키 정보를 완벽하게 지우기 위함입니다.
- 타겟 지점(39번 슬라이드) 재개 설정 스크립트 코드 내에서 슬라이드를 순회하는 반복문(for loop)의 시작점을 1이 아닌 39로 명시적으로 수정하거나, 이미 생성된 음성 파일(1~38번)이 있는 경우 파일 존재 여부를 체크하여 건너뛰는(skip) 로직이 정상적으로 작동하는지 확인합니다.
- 작업 재실행 및 로깅 확인 새 터미널을 열고 스크립트를 재실행합니다. 콘솔에 출력되는 로그를 모니터링하여 429 RESOURCE_EXHAUSTED 에러 없이 39번 슬라이드부터 정상적으로 음성(wav) 파일이 디렉토리에 저장되는지 실시간으로 검증합니다.
6. 빈번한 문제 해결(Troubleshooting) 및 시스템 최적화
새 프로젝트 기반의 우회 방식을 적용할 때 개발자들이 자주 직면하는 문제와 해결 가이드입니다.
- AI Studio 목록에 새 프로젝트가 나타나지 않는 현상 Google Cloud 시스템 간의 데이터 동기화 지연으로 인해 발생합니다. 새 프로젝트를 생성하고 결제를 연결한 후 즉시 AI Studio로 넘어가면 간혹 목록 렌더링이 누락됩니다. 이 경우 브라우저 탭을 완전히 새로고침(F5)하거나 1~2분 정도 대기한 후 검색창에 프로젝트 이름을 직접 타이핑해 보면 나타납니다.
- 코드를 수정했는데도 계속 100회 한도 에러가 발생하는 현상 99% 확률로 로컬 개발 환경의 환경 변수 고정 문제이거나, 코드 내 서로 다른 모듈에서 이전 API 키를 중복 호출하고 있는 경우입니다. OS 수준에서 시스템 환경 변수를 확인하고, 프로젝트 내 모든 .py 파일을 전역 검색(Search in Files)하여 과거 키 문자열이 남아있는 곳이 없는지 색인해야 합니다.
- 작업 완료 후 리소스 정리 지침 급한 불을 끄기 위해 생성한 '임시 프로젝트'는 작업이 완전히 종료된 후 방치하면 보안 취약점이 될 수 있습니다. 모든 슬라이드 생성이 완벽하게 끝났다면, Google Cloud Console의 [IAM 및 관리] > [설정] 메뉴로 이동하여 [프로젝트 종료(Shut Down)]를 실행하는 것이 안전합니다. 프로젝트를 종료하면 발급되었던 API 키도 즉시 무효화되어 불필요한 과금 리스크를 원천 차단할 수 있습니다.
