Gemini API 사용법: Windows PowerShell에서 Python으로 첫 응답 받기

Gemini API는 AI Studio에서 키를 만들고, PowerShell에 키를 넣은 뒤 google-genai SDK로 호출한다. Free Tier 프로젝트의 키면 Gemini 3.8 Flash를 무료로 쓸 수 있다(모델별 한도 있음). 현재는 제한 없는 standard 키가 거부된다. 기존 키는 제한 설정과 키 종류를 확인한다. 키 발급은 Gemini API 키 발급 방법에 있다.

1. 키와 무료 여부 확인

AI Studio의 API Keys에서 Create API key를 누르고 프로젝트를 골라 키를 만든다. 기존 Google Cloud 프로젝트가 목록에 없으면 Dashboard → Projects → Import projects로 가져온다. 생성 권한이 없다고 나오면 해당 프로젝트의 IAM 권한을 확인한다.

5월 28일부터 AI Studio에서 새로 만드는 키는 서비스 계정에 연결된 authorization key다. 9월 29일 공식 문서는 제한 없는 standard 키는 거부하지만, 명시적으로 제한을 설정한 standard 키는 계속 작동한다고 안내한다. 생성일만으로 교체가 필수라고 판단하지 말고 API Keys에서 키 종류와 제한 상태를 확인한다. 코드에 전달하는 방식은 같다. (API 키 안내)

키가 속한 프로젝트가 Free Tier면 무료로 시작한다. Set up billing은 유료 전환이므로 첫 실습에서는 누르지 않는다. (가격표) 무료 할당량으로 보낸 입력과 응답은 Google이 서비스 개선에 쓰고 사람이 검토할 수도 있다. 실습에는 고객 명단이나 사내 문서 대신 가상의 자료를 쓴다. (추가 약관)

2. Python과 SDK 준비

PowerShell에서 python --version으로 Python 설치를 확인한다. 명령을 찾지 못하거나 Microsoft Store가 열리면 python.org에서 설치하고 창을 새로 연다. py --version만 된다면 아래의 python을 py로 바꾼다.

mkdir gemini-first-call
cd gemini-first-call
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U google-genai
.\.venv\Scripts\python.exe -c "from google import genai; print('SDK 준비 완료')"

SDK 준비 완료가 나오면 설치가 끝났다. 설치와 실행 모두 같은 .venv의 Python을 직접 지정하므로 다른 Python에 설치하는 실수가 없고, 가상 환경 활성화를 위한 실행 정책 변경도 필요 없다.

3. 키를 현재 창에만 넣기

아래 네 줄을 실행하고, 입력창에 AI Studio에서 복사한 키를 붙여 넣는다. 화면에는 가려진 문자만 보이고 명령 기록에도 키가 남지 않는다.

$geminiKey = Read-Host "Gemini API key" -AsSecureString
$env:GEMINI_API_KEY = [System.Net.NetworkCredential]::new("", $geminiKey).Password
Remove-Variable geminiKey
if ($env:GEMINI_API_KEY) { "키 입력 완료" }

새 PowerShell 창을 열면 다시 넣어야 한다. 다음 단계도 이 창에서 실행한다.

4. 코드 저장하고 실행

notepad .\first_gemini.py로 파일을 열고 아래 코드를 붙여 UTF-8로 저장한다. 저장 창의 파일 형식을 모든 파일로 골라 .py.txt가 되지 않게 한다.

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="회의 메모에서 시간과 준비물만 두 줄로 뽑아줘. 없는 내용은 추가하지 마. 회의 메모: 금요일 오전 10시에 회의한다. 지난달 판매 보고서를 준비한다.",
)
print("상태:", interaction.status)
print(interaction.output_text)

키를 api_key로 직접 넘기는 이유가 있다. genai.Client()처럼 비워 두면 SDK가 환경 변수를 찾는데, GOOGLE_API_KEY와 GEMINI_API_KEY가 둘 다 있으면 GOOGLE_API_KEY가 우선한다. 다른 용도로 넣어 둔 키가 쓰이는 일을 막는다.

.\.venv\Scripts\python.exe -m py_compile .\first_gemini.py
.\.venv\Scripts\python.exe .\first_gemini.py

첫 줄은 문법만 검사하고 요청을 보내지 않는다. 두 번째 줄에서 실제 요청이 나가 사용량에 잡힌다.

예상 출력 형식은 다음과 같다. 실제 문구는 달라질 수 있다.

상태: completed
시간: 금요일 오전 10시
준비물: 지난달 판매 보고서

completed는 생성이 끝났다는 뜻이고, 답이 맞는지는 따로 본다. 금요일 오전 10시와 지난달 판매 보고서가 모두 있고 없는 날짜·담당자가 붙지 않았으면 성공이다. 상태가 failed나 in_progress면 출력이 비어도 인증 오류로 단정하지 말고 오류 정보를 본다. 사용량은 AI Studio의 Dashboard → Usage에서 확인한다. (시작 안내)

오류가 나면

메시지	조치
No module named 'google'	2단계 설치를 다시 하고, 같은 .venv의 Python으로 실행
can't open file	Get-ChildItem .\first_gemini*로 위치와 .py.txt 여부 확인
KeyError: 'GEMINI_API_KEY'	키를 넣은 그 PowerShell 창에서 실행
AttributeError(interactions)	SDK를 최신으로 올리고, 파일 이름이 google.py·genai.py가 아닌지 확인
400 API_KEY_INVALID	틀린 키다. 다시 복사한다
401	키 누락·잘못된 값·만료 등 인증 오류다. 전달한 키와 키 제한 상태를 확인
403	요청한 리소스에 대한 키 권한과 프로젝트 접근 권한을 확인
404 model_not_found	모델 ID가 gemini-3.8-flash인지 확인
429	한도 초과다. 아래 설명 참고
503	잠시 뒤 다시 시도하고, 반복되면 서비스 상태 확인

공식 Interactions 오류표는 키 누락·잘못된 값·만료를 401 인증 오류로 설명한다. 다른 오류 코드가 오면 숫자만으로 원인을 정하지 말고 응답의 code와 message를 함께 확인한다. (오류 표)

429는 키를 새로 만들어도 풀리지 않는다. 한도는 키가 아니라 프로젝트에 걸린다. 사용 한도 화면에서 모델별 분당 요청(RPM)·분당 토큰(TPM)·일일 요청(RPD)을 본다. 분당 한도면 다른 작업을 멈추고 간격을 두어 다시 보낸다. 일일 한도는 태평양 시간 자정, 즉 한국 시간 오후 4~5시에 초기화된다. 재시도 횟수와 대기 시간에 상한을 두고 무한 반복하지 않는다. (한도 안내)

첫 호출 뒤

input의 지시와 자료만 바꿔 할 일 추출, 짧은 문장 분류처럼 결과를 직접 대조할 수 있는 작업부터 늘린다. 기존 OpenAI SDK 코드를 옮길 때는 OpenAI 호환 경로가 따로 있다.

실습을 마치면 Remove-Item Env:GEMINI_API_KEY로 현재 창의 키를 지운다. 발급한 키 자체는 남으니, 노출됐다면 API Keys 화면에서 폐기하고 새로 만든다.

터미널에서 코드를 고치는 도구가 필요하면 Antigravity 사용법을 본다.