Gemini API 키 발급과 GEMINI_API_KEY 환경 변수 설정

계정 유형별 발급 조건

Gemini API를 프로젝트에 사용하려면 Google AI Studio에서 인증 키를 발급받아 시스템 환경 변수로 등록해야 합니다. 소스코드에 API 키를 직접 작성하면 저장소를 공유할 때 키가 노출되므로, 환경 변수를 참조하는 방식을 사용해야 합니다.

키 발급 절차와 권한 조건은 계정 유형에 따라 다릅니다. 개인용 Google 계정과 조직용 Google Workspace 계정의 발급 조건을 비교한 표입니다.

개인 계정인 경우에는 Google AI Studio 웹사이트에 접속해 키를 생성합니다. 조직 계정에서 AI Studio가 열리지 않는 경우에는 관리자가 AI Studio를 꺼 둔 것이므로 관리자에게 활성화를 요청해야 합니다.

GEMINI_API_KEY 등록 명령과 Python 호출 코드

환경 변수 이름은 GEMINI_API_KEY를 사용합니다. 소스코드에서 이 변수를 불러오면 인증 정보를 코드에 노출하지 않고 모델을 호출할 수 있습니다.

Windows 명령 프롬프트용 환경 변수 등록 명령과 Python 연동 코드 예시입니다.

setx GEMINI_API_KEY "YOUR_GEMINI_API_KEY_HERE"

import os
from google import genai

client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY"))
response = client.models.generate_content(model="gemini-3.8-flash", contents="Hello World")
print(response.text)

명령을 실행할 때는 YOUR_GEMINI_API_KEY_HERE 부분을 실제 발급받은 키 문자열로 바꿔 입력합니다. 코드를 실행한 뒤 터미널에 응답 텍스트가 출력되는지 확인합니다.

키 발급과 Windows 환경 변수 등록 절차

키 발급은 Google AI Studio 화면에서, 변수 등록은 Windows 시스템 설정 메뉴에서 진행합니다.

1. 브라우저를 열고 Google AI Studio 웹사이트에 접속하여 Google 계정으로 로그인합니다.
2. 좌측 메뉴 상단의 Get API key 버튼을 클릭하고 Create API key 항목을 선택합니다.
3. 화면에 표시된 API 키 문자열을 복사한 후 보안 메모장에 임시로 저장합니다.
4. Windows 검색창에 시스템 환경 변수 편집을 입력하여 실행한 뒤 환경 변수(N) 버튼을 클릭합니다.
5. 사용자 변수 항목에서 새로 만들기(N)를 누르고 변수 이름에 GEMINI_API_KEY, 변수 값에 복사한 키를 입력한 후 확인을 누릅니다.

등록을 마친 뒤에는 실행 중이던 명령 프롬프트나 개발 에디터를 종료하고 다시 열어야 변경된 환경 변수가 적용됩니다.

Git 저장소 보안 설정

발급받은 API 키는 Git 저장소나 외부 웹서버에 업로드되지 않도록 관리해야 합니다. 키가 공개 저장소에 유출되면 제3자가 사용량을 소비해 계정 한도가 초과될 수 있습니다.

프로젝트 루트 폴더에 .gitignore 파일을 만들고 파일 안에 .env 문자열을 추가합니다. 환경 변수를 .env 파일로 별도 관리하는 경우에는 이 파일이 버전 관리 대상에서 제외되도록 설정합니다.

소스코드에는 API 키 문자열을 주석이나 문자열 상수로 남기지 않습니다. 팀 프로젝트에서는 키 자체를 공유하지 않고, 구성원이 각자 개별 환경 변수를 등록해야 합니다.

인증 오류 원인과 조치

키를 등록한 뒤 소스코드 실행 중 오류가 발생하면 터미널에 표시된 오류 메시지로 원인을 확인합니다.

API_KEY_INVALID 오류가 발생하는 경우에는 변수 값에 공백이나 오타가 포함되었는지 확인합니다. 변수 이름을 잘못 입력한 경우에는 os.environ.get("GEMINI_API_KEY") 호출 부분의 문자열을 대소문자까지 동일하게 수정합니다.

403 PERMISSION_DENIED가 출력되는 경우는 키의 권한이나 프로젝트 접근 문제입니다. AI Studio에서 키가 속한 프로젝트를 확인하고 필요하면 키를 새로 만듭니다. 키는 프로젝트 단위로 동작하며, 노출이 의심되면 즉시 재발급해야 합니다.

등록이 완료된 환경에서는 터미널에서 echo %GEMINI_API_KEY% 명령을 실행했을 때 설정한 키 문자열이 화면에 출력됩니다.