muaco Tech Note

Geminiai.google.dev

Gemini API 무료로 시작하기API 키 발급, 첫 호출, 무료 한도까지

Google AI Studio에서 Gemini API 키를 받아 첫 응답을 받아 보고, 무료 한도와 한도를 넘었을 때 생기는 일까지 확인합니다.

안녕하세요, muaco입니다.

이 글로 해 볼 수 있는 일

이 글을 따라 하면 돈을 내지 않고 Gemini API에서 첫 답을 받아 볼 수 있습니다. 구글이 정해 둔 무료 한도 안에서 쓰기 때문입니다. 한도가 얼마인지, 넘으면 어떻게 되는지도 함께 확인합니다.

식당에서는 정해진 주문서에 적어 내면 주방이 음식을 내줍니다. 프로그램끼리도 이런 주문 창구가 있습니다. 이 창구를 API라고 부릅니다.

키 발급, 브라우저 체험, 터미널 호출, 한도 확인 순서로 갑니다. 이 글은 2026년 11월 1일에 읽은 공식 문서가 기준입니다. 모델 이름은 자주 바뀌니 막히면 빠른 시작 문서의 예제부터 다시 보세요.

시작 전에 준비할 계정과 도구

  • 구글 계정: 평소 쓰는 Gmail 계정이면 됩니다. 이 계정으로 Google AI Studio(구글이 만든 Gemini 체험·관리 사이트)에 들어갑니다.
  • 이용 가능 지역: 한국은 공식 이용 가능 지역 목록에 들어 있습니다.
  • 결제 수단: 필요 없습니다. 무료 등급은 결제를 연결하지 않은 프로젝트에 붙는 등급입니다.
  • 터미널: 글자로 명령을 쳐서 컴퓨터를 부리는 창입니다. macOS는 기본으로 들어 있는 '터미널' 앱을 씁니다. Windows는 명령 프롬프트나 PowerShell을 씁니다.
  • Python(Windows만): Windows에서 호출할 때 씁니다. 없다면 python.org 공식 다운로드 페이지에서 Python install manager를 받아 설치하세요(Microsoft Store에도 있습니다). 설치 뒤 터미널에 python --version을 쳐서 버전 번호가 나오면 됩니다. 필요한 최소 버전은 Gemini 문서에 나와 있지 않습니다.

회사 기밀은 넣지 마세요. 가격 문서에 따르면 무료 등급에서 보낸 내용은 대부분의 모델에서 구글 제품 개선에 쓰입니다. 유료 등급은 대부분의 모델에서 쓰지 않습니다.

따라 하기: 키 발급부터 한도 확인까지

1. API 키 받기

따라 하기
  1. Google AI Studio의 API 키 화면을 열고 구글 계정으로 로그인하세요. 키 목록 화면이 뜨면 제대로 들어왔습니다.
  2. 이용약관에 동의합니다. 처음 쓰는 계정이면 프로젝트(키와 사용량, 결제를 한데 넣는 서랍) 하나와 키 하나가 저절로 생깁니다.
  3. 목록에 키가 없으면 Create API key를 눌러 만드세요. 예전부터 Google Cloud를 써 온 계정은 먼저 Dashboard의 Projects에서 Import projects로 기존 프로젝트를 가져와야 합니다.
  4. 키 값을 복사해 두고 비밀번호처럼 다루세요. 메신저나 공유 문서, 코드 저장소에 붙이면 남이 내 이름으로 요청을 보낼 수 있습니다.

2. 브라우저에서 먼저 써 보기

따라 하기
  1. aistudio.google.com에 들어가세요. 새 대화가 열린 Playground(모델에게 바로 질문해 보는 연습장) 화면이 기본으로 나옵니다.
  2. Type something... 칸에 질문을 쓰고 Run을 누르세요. 답 밑에 답한 모델 이름이 붙어 나오면 성공입니다.
  3. 답이 마음에 들면 Get code를 누르고 언어를 고릅니다. 방금 한 대화를 API로 보내는 코드가 나오니, 화면에서 한 일과 API 호출이 같은 일이라는 점을 눈으로 확인하게 됩니다.

가격 문서에는 AI Studio 사용이 이용 가능한 모든 지역에서 무료라고 적혀 있습니다. 설치가 부담스럽다면 여기까지만 해도 Gemini를 써 볼 수 있습니다.

3. 터미널에서 첫 호출 보내기

macOS나 Linux라면 첫 번째 목록을, Windows라면 두 번째 목록을 따라 하세요. 문서가 환경 변수 설정을 두 경우로 나눠 안내하기 때문입니다.

따라 하기
  1. 터미널을 열고 아래 줄의 YOUR_API_KEY 자리에 복사한 키를 넣어 실행하세요. 키를 코드에 적지 않으려고 터미널에 메모처럼 맡겨 두는 단계로, 이 메모를 환경 변수라고 부릅니다. 이 메모는 지금 연 터미널 창에서만 유지됩니다. 
    export GEMINI_API_KEY="YOUR_API_KEY"
  2. 아래 명령을 붙여 넣고 Enter를 누르세요. gemini-3.8-flash 모델에게 AI가 어떻게 동작하는지 몇 마디로 설명해 달라고 묻는 요청입니다. 
    curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "gemini-3.8-flash", "input": "Explain how AI works in a few words"}'
  3. 중괄호가 잔뜩 든 글자 덩어리가 돌아오는지 보세요. 그 안의 status 값이 completed면 성공이고, 답 문장은 model_output 단계에 들어 있습니다.

Windows에서는 Python으로 같은 요청을 보냅니다. 문서가 Windows용으로는 화면에서 환경 변수를 등록하는 방법을 안내하고, Python 라이브러리는 그 값을 알아서 읽습니다.

따라 하기
  1. 시작 메뉴에서 "환경 변수"를 검색해 시스템 속성의 환경 변수 화면을 여세요. 사용자 변수 아래 새로 만들기를 눌러 이름은 GEMINI_API_KEY, 값은 복사한 키로 넣고 확인을 누릅니다.
  2. 터미널(명령 프롬프트나 PowerShell)을 새로 열고 라이브러리를 설치하세요. 창을 새로 열어야 방금 등록한 키를 읽습니다. pip이 명령이 아니라는 줄이 나오면 아래 '막히기 쉬운 곳'의 pip 항목을 보세요. 
    pip install -U google-genai
  3. 같은 창에서 작업 폴더를 만들고 그 안으로 옮겨 가세요. 터미널은 사용자 폴더(C:\Users\내 이름)에서 열리는데, 메모장의 저장 창은 보통 '문서' 폴더에서 열립니다. 둘이 어긋나면 실행할 때 파일을 찾지 못하니 폴더부터 맞춥니다. 
    mkdir gemini
cd gemini
  4. 아래 명령으로 메모장을 여세요. 새 파일을 만들지 묻는 창이 뜨면 예를 누릅니다. 이렇게 열면 파일이 지금 터미널이 있는 gemini 폴더에 first.py라는 이름으로 생깁니다. 
    notepad first.py
  5. 메모장에 아래 코드를 붙여 넣고 Ctrl+S로 저장한 뒤 메모장을 닫으세요. 
    from google import genai

    client = genai.Client()
    

    interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Explain how AI works in a few words"
)
print(interaction.output_text)

  6. 터미널로 돌아와 dir을 치고 목록에 first.py가 있는지 보세요. first.py.txt로 보이면 확장자가 잘못 붙은 상태이니 ren first.py.txt first.py로 이름을 고칩니다.
  7. python first.py로 실행하세요. 영어 답 한두 문장이 찍히면 성공입니다.

문서에 실린 예시 답은 데이터에서 패턴을 배워 새 데이터를 예측하거나 판단한다는 한 문장입니다. 부를 때마다 답이 조금씩 달라지니 똑같지 않아도 괜찮습니다.

4. 무료 한도 확인하기

무료 한도는 세 가지 자로 잽니다. 1분 요청 수(RPM), 1분 입력 토큰 수(TPM), 하루 요청 수(RPD)입니다. 토큰은 AI가 글을 읽을 때 잘게 써는 조각이라고 보면 됩니다.

따라 하기
  1. AI Studio의 Rate Limit 화면을 여세요. 한도 문서에는 무료 등급의 모델별 숫자가 없고, 내 프로젝트에 걸린 한도는 이 화면에서 보라고 안내합니다.
  2. 쓰고 있는 모델의 RPM, TPM, RPD를 적어 두세요. 셋 중 하나만 넘어도 요청이 막힙니다.
  3. Dashboard > Usage에서 지금까지 쓴 양을 확인합니다. 한도까지 얼마나 남았는지 가늠하는 단계입니다.
  4. 하루 한도가 다시 차는 시각을 기억해 두세요. 미국 태평양 시간 자정이고, 한국 시간으로는 오후 4시(미국 서머타임 기간)나 오후 5시입니다.
  5. 무료로만 쓸 생각이면 Set up billing은 누르지 마세요. 결제를 연결하면 그 프로젝트는 유료 등급이 됩니다. 신규 사용자는 선불(Prepay)이 기본이라 최소 5달러를 먼저 넣고, 자격이 되는 계정에는 후불(Postpay)도 선택지로 나옵니다. 결제 연결을 끊으면 무료 등급으로 돌아갑니다.

그럼 한도를 넘으면 어떻게 됩니까? 문서는 한도 중 하나라도 넘으면 한도 오류가 돌아온다고 설명합니다.

결제 문서에는 유료 키를 연결하지 않는 한 AI Studio 사용은 무료라고 적혀 있습니다. 그래서 결제를 연결하지 않은 프로젝트라면 한도를 넘어도 요청만 막히고 요금은 붙지 않으리라 봅니다. 한도 초과와 요금을 직접 잇는 문장은 문서에 없어, 이 대목은 필자의 추론입니다.

한 가지 더. 문서는 정해 둔 한도도 보장값이 아니라고 적어 둡니다. 미리보기(preview) 모델일수록 한도가 더 빡빡합니다.

막히기 쉬운 곳

429 오류가 돌아옵니다

  • 보이는 것: HTTP 429 오류가 돌아옵니다. 서버가 요청이 너무 많다며 돌려보낼 때 붙이는 응답 번호입니다. 오류 이름에는 rate_limit_exceeded, too_many_requests, quota_exceeded 중 하나가 보입니다.
  • 왜 그런지: 앞의 세 한도 중 하나를 넘었습니다. 오류 문서에 따르면 rate_limit_exceeded는 분당 또는 초당 요청·토큰 한도를 넘었다는 뜻입니다. too_many_requests는 짧은 시간에 요청이 몰렸을 때, quota_exceeded는 하루 한도를 넘었을 때 나옵니다. 한도는 키가 아니라 프로젝트 단위로 셉니다.
  • 어떻게 하는지: 같은 프로젝트에서 키를 새로 만들어도 풀리지 않습니다. rate_limit_exceeded나 too_many_requests라면 잠시 기다렸다가 간격을 점점 늘려 다시 보내고, quota_exceeded라면 초기화 시각을 기다리세요.

pip이 명령이 아니라고 나옵니다

  • 보이는 것: Windows에서 pip install을 치면 "'pip'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다"라는 줄이 나옵니다.
  • 왜 그런지: Python이 아직 없거나, 설치는 됐어도 pip 실행 파일을 터미널이 찾지 못하는 상태입니다.
  • 어떻게 하는지: 먼저 python --version으로 Python이 있는지 확인하세요. 버전이 나오면 Python 공식 문서가 권하는 대로 python -m pip install -U google-genai로 설치합니다. 버전이 안 나오면 준비물 항목의 다운로드 페이지에서 Python부터 설치하세요.

터미널을 다시 열었더니 인증 오류가 납니다

  • 보이는 것: macOS나 Linux에서 어제 되던 curl 명령이 새 터미널 창에서는 인증 오류로 실패합니다.
  • 왜 그런지: export로 맡긴 키는 그 창을 닫으면 사라집니다.
  • 어떻게 하는지: 매번 치기 싫다면 API 키 문서 안내대로 touch ~/.zshrc && open ~/.zshrc로 설정 파일을 열고, 맨 끝에 같은 export 줄을 붙여 저장하세요. 그다음 source ~/.zshrc를 한 번 실행합니다. bash를 쓴다면 파일 이름만 ~/.bashrc로 바꾸면 됩니다.

문서 첫 화면 예제를 붙였더니 실패합니다

  • 보이는 것: Gemini API 문서 첫 화면의 예제를 그대로 실행했는데 답 대신 오류가 옵니다.
  • 왜 그런지: 첫 화면 예제의 모델은 gemini-4-argon이고, 가격 문서에 이 모델은 무료 등급에서 쓸 수 없다고 나옵니다. Gemini 3.1 Pro Preview와 이미지·영상 모델도 같습니다. 이때 어떤 오류 코드가 오는지는 문서에 나와 있지 않습니다.
  • 어떻게 하는지: 코드의 model 값을 gemini-3.8-flash로 바꾸세요. AI Studio의 Get code로 받은 코드도 model 값부터 확인합니다.

403 오류가 나거나 키에 Blocked 표시가 붙습니다

  • 보이는 것: 403 PERMISSION_DENIED 오류가 나거나, AI Studio 키 목록에 Blocked 표시가 보입니다. 403은 접근 권한이 없다며 서버가 거절할 때 붙이는 응답 번호입니다.
  • 왜 그런지: 문서는 키가 유출 신고됐거나 막혔을 때, 또는 프로젝트 접근이 제한됐을 때를 원인으로 듭니다. 2026년 5월 7일부터는 제한을 걸지 않은 채 오래 쓰지 않은 키도 막습니다.
  • 어떻게 하는지: AI Studio에서 새 키를 만드는 방법이 가장 빠릅니다. 다만 프로젝트 자체가 제한됐다면 새 키로도 풀리지 않으니, 그 프로젝트의 결제 상태와 무료 등급 자격을 확인하세요.

새 키를 넣었는데 예전 오류가 그대로입니다

  • 보이는 것: GEMINI_API_KEY를 새 키로 바꿨는데 Python 코드에서 같은 오류가 계속 납니다.
  • 왜 그런지: 라이브러리는 GEMINI_API_KEY와 GOOGLE_API_KEY를 모두 찾고, 둘 다 있으면 GOOGLE_API_KEY를 씁니다. 예전에 넣어 둔 GOOGLE_API_KEY가 남아 있으면 새 키는 무시됩니다.
  • 어떻게 하는지: 환경 변수 목록에서 GOOGLE_API_KEY를 찾아 지우거나 새 키로 바꾸세요. Windows라면 바꾼 뒤 터미널을 새로 엽니다. 단, 이 변수는 다른 구글 도구가 쓰고 있을 수 있습니다. 직접 넣은 기억이 없거나 회사 PC라면 IT 담당자에게 먼저 묻고, 손대기 전에 원래 값을 메모해 두면 되돌릴 수 있습니다.

여기서 더 나아가려면

업무에 붙일 단계가 되면 키 관리부터 챙기세요. 문서는 키를 코드 저장소에 올리거나 웹페이지, 앱 코드 안에 넣지 말고 서버를 거쳐 쓰라고 권합니다.

한도가 모자라면 AI Studio에서 결제를 연결해 유료 등급으로 올립니다. 이때 Spend 화면에서 프로젝트별 지출 상한(아직 실험 기능)을 걸어 두면 예상 밖 청구를 막는 데 도움이 됩니다.

이상으로 글 마치겠습니다.

참고한 공식 문서

#Gemini API#구글#Google AI Studio#API 키#무료#무료 한도#사용법

같은 분류의 글