커뮤니티 입장하기

제미나이 API 첫 호출: 키 발급, 무료 한도, 요금 확인

제미나이 API 첫 호출은 구글 AI 스튜디오에서 키를 받아 환경 변수에 넣고, 라이브러리를 설치해 모델 이름과 문장 하나로 요청을 보내 답을 받는 순서입니다. 새 계정은 무료 등급에서 시작하고, 요청 한도는 프로젝트 단위로 AI 스튜디오 화면에서 확인하며, 유료 등급은 결제 계정을 연결하고 선결제하면 열립니다.

같은 말:제미나이 API 사용법Gemini API 키 발급제미나이 API 무료 한도Gemini API 요금GEMINI_API_KEY

게시 코스 6 / 8번째 개념
새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요
#AI#API#바이브코딩
Share
목차
  1. 🤔 앱에서는 되는데 코드로 옮기려니 막힐 때
  2. 🔑 제미나이 API 첫 호출의 정의
  3. 🗝️ 키를 받고 종류를 확인하기
  4. 🔐 키를 환경 변수에 넣기
  5. 💬 첫 요청 보내기
  6. 📏 한도는 어디에서 보는지
  7. 💳 요금과 결제 방식 (2026년 9월 28일 기준)
  8. ⚠️ 자주 하는 실수
  9. ❓ 자주 묻는 질문
  10. 📋 3줄 요약
  11. 📚 참고 자료

🤔 앱에서는 되는데 코드로 옮기려니 막힐 때

제미나이 앱에서 상담 문의 분류를 시켜 보니 쓸 만해서, 시트에 매일 쌓이는 문의 수백 건에 자동으로 붙이고 싶어집니다. 검색하면 API 키를 받으라는 안내가 나오는데, 키를 받고 나서 어디에 넣는지, 첫 요청은 어떻게 보내는지, 무료로 몇 번까지 되는지에서 막힙니다.

AI 스튜디오가 무엇이고 제미나이 앱과 어떻게 다른지는 구글 AI 스튜디오에서 다뤘습니다. 이 글은 그다음 한 걸음인 첫 호출을 다룹니다. 키를 받아 환경 변수에 넣고 요청 하나를 보내 답을 받기까지의 순서와, 그 뒤에 만나는 한도와 요금을 2026년 9월 28일 기준 구글 개발자 문서에서 확인해 단계별로 적었습니다. API가 무엇인지는 API 뜻에 있습니다.

🔑 제미나이 API 첫 호출의 정의

제미나이 API 첫 호출은 구글 AI 스튜디오에서 키를 받아 환경 변수에 넣고, 라이브러리를 설치해 모델 이름과 문장 하나로 요청을 보내 답을 받는 순서입니다.

단계하는 일걸리는 시간
키 받기aistudio.google.com에서 API 키 만들기1분
키 보관터미널의 환경 변수 GEMINI_API_KEY에 넣기2분
라이브러리 설치파이썬은 pip, 자바스크립트는 npm1분
첫 요청모델 이름과 문장 하나로 요청1분
한도 확인AI 스튜디오의 한도 화면 보기1분

🗝️ 키를 받고 종류를 확인하기

AI 스튜디오에 구글 계정으로 로그인하면 처음 쓰는 사용자에게는 기본 프로젝트와 키가 자동으로 만들어집니다. 이미 구글 클라우드 프로젝트가 있는 계정은 대시보드의 프로젝트 화면에서 그 프로젝트를 가져온 뒤 키를 만듭니다. 회사 프로젝트에서 키 만들기 버튼이 막혀 있으면 프로젝트 편집자 권한이 없는 것이라 관리자에게 요청하거나 조직에 속하지 않은 새 프로젝트를 만듭니다.

키의 종류가 2026년에 바뀌고 있습니다. 문서 기준으로 새로 만드는 키는 전부 인증 키인데, 서비스 계정에 묶여 있어 유출이 감지되면 빠르게 막을 수 있습니다. 예전의 표준 키는 제한을 걸지 않은 채로는 이미 거부되고, 문서는 2026년 9월에 표준 키의 요청을 거부한다고 적으면서 그 전에 인증 키로 옮기라고 안내합니다. 오래된 키를 코드에 넣어 두었다면 지금 새로 만드는 편이 안전합니다.

🔐 키를 환경 변수에 넣기

키는 코드 파일에 적지 않고 환경 변수로 넘깁니다. 환경 변수는 프로그램 바깥에 값을 두고 실행할 때 읽어 오는 방식이고, 개념은 환경 변수 뜻에 있습니다. 구글 라이브러리는 GEMINI_API_KEY나 GOOGLE_API_KEY 변수를 자동으로 찾고, 둘 다 있으면 GOOGLE_API_KEY를 먼저 씁니다.

맥의 zsh에서는 홈 폴더의 설정 파일 끝에 한 줄을 넣고 적용합니다. 터미널이 낯설면 터미널과 CLI 뜻을 먼저 봅니다.

echo 'export GEMINI_API_KEY=여기에_키' >> ~/.zshrc source ~/.zshrc

윈도우는 검색창에 "환경 변수"를 쳐서 시스템 속성의 환경 변수 창을 열고, 사용자 변수에 이름 GEMINI_API_KEY와 값을 새로 넣은 뒤 터미널을 새로 엽니다.

문서가 강조하는 규칙은 세 가지입니다. 깃 같은 소스 관리에 키를 올리지 않고, 웹이나 모바일 앱의 화면 코드에 키를 넣지 않으며(화면 코드의 키는 누구나 꺼낼 수 있어서 서버를 하나 두고 거기서 호출합니다), 운영 환경에서는 비밀 관리 도구에 두고 결제 알림을 켭니다.

💬 첫 요청 보내기

파이썬은 3.9 이상에서 라이브러리를 설치합니다.

pip install -q -U google-genai

첫 요청은 모델 이름과 문장 하나면 됩니다. 아래는 문서의 빠른 시작 예를 옮긴 것으로, 환경 변수에 키가 있으면 클라이언트가 알아서 읽습니다.

from google import genai client = genai.Client() response = client.models.generate_content( model="gemini-3.8-flash", contents="AI가 어떻게 동작하는지 세 문장으로 설명해 줘" ) print(response.text)

터미널에서 라이브러리 없이 확인하려면 curl로 같은 요청을 보냅니다.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{"contents":[{"parts":[{"text":"AI가 어떻게 동작하는지 세 문장으로 설명해 줘"}]}]}'

모델 이름은 2026년 9월 28일 기준 요금 문서에 있는 gemini-3.8-flash를 썼습니다. 빠른 시작 문서의 예제에는 gemini-3.5-flash가 남아 있어서 두 문서가 어긋나는데, 모델 목록 문서에서 현재 제공되는 이름을 확인하고 넣습니다. 이름 규칙은 제미나이 모델 라인업에 있습니다.

첫 답이 오면 다음 세 가지를 차례로 시험해 봅니다. 답이 만들어지는 대로 조금씩 받는 스트리밍, 앞 대화를 기억하는 채팅 도우미, 그리고 최신 정보가 필요할 때 구글 검색을 붙이는 그라운딩입니다. 그라운딩을 켜면 응답에 어떤 검색어를 썼고 어떤 페이지를 참고했는지 메타데이터로 함께 오므로, 답만 받지 말고 그 출처를 열어 보는 습관을 처음부터 들입니다. 출처를 대조하는 순서는 답변 검증 루틴에 있습니다.

📏 한도는 어디에서 보는지

요청 한도는 세 가지 기준으로 걸립니다. 분당 요청 수와 분당 입력 토큰 수, 하루 요청 수이고, 셋 가운데 하나라도 넘으면 오류가 납니다. 한도는 키가 아니라 프로젝트 단위로 걸리고, 하루 한도는 태평양 시각 자정에 초기화됩니다.

숫자는 문서에 표로 없습니다. 구글은 한도가 모델과 사용 등급에 따라 다르고 보장되지 않는다고 적으면서 AI 스튜디오의 한도 화면에서 내 프로젝트의 값을 보라고 안내합니다. 첫 호출 뒤에 그 화면을 열어 지금 쓰는 모델의 분당과 하루 한도를 적어 두는 것이 이 단계의 마지막 일입니다. 실험 모델과 미리보기 모델은 한도가 더 낮습니다.

등급은 결제 이력으로 정해집니다.

등급조건10분당 지출 한도
무료프로젝트만 있으면없음
1등급결제 계정 연결10달러
2등급100달러 이상 결제하고 첫 결제 뒤 3일50달러
3등급1,000달러 이상 결제하고 첫 결제 뒤 30일200달러

무료 등급에는 조건이 하나 붙습니다. 요금 문서는 무료 등급에서 입력한 내용이 구글의 제품 개선에 쓰이고 유료 등급에서는 쓰이지 않는다고 적습니다. 회사 자료로 시험한다면 이 조건을 먼저 봅니다.

💳 요금과 결제 방식 (2026년 9월 28일 기준)

유료 등급은 AI 스튜디오의 프로젝트 화면에서 결제 설정을 눌러 결제 계정을 연결하고 최소 5달러를 선결제하면 열립니다. 문서 기준으로 2026년 3월 23일부터 새 계정은 선결제 방식이 기본이고, 산 크레딧은 12개월 뒤 만료되며 잔액이 0달러가 되면 그 결제 계정에 묶인 모든 프로젝트의 키가 동시에 멈춥니다. 오래 도는 작업은 잔액을 넘겨 쓸 수 있으므로 자동 충전을 켜 두거나 잔액을 여유 있게 둡니다.

3.8 플래시의 표준 요금입니다. 100만 토큰당 미국 달러이고 출력에는 생각 토큰이 포함됩니다.

항목무료 등급유료 등급
입력무료0.75달러 (2027년 1월 1일부터 1.50달러)
출력무료3.75달러 (2027년 1월 1일부터 7.50달러)
구글 검색 그라운딩제공 안 됨월 5,000회 무료 뒤 1,000회당 14달러
제품 개선에 사용예아니요

두 가지를 봅니다. 하나는 도입가입니다. 지금 값은 2026년 12월 31일까지이고 2027년부터 두 배가 되므로 내년 예산은 정가로 잡습니다. 다른 하나는 검색 그라운딩입니다. 무료 등급에서는 켤 수 없고, 유료에서도 월 5,000회를 넘기면 검색 1,000회에 14달러가 따로 붙습니다. 이미지 모델과 영상 모델에는 무료 등급이 없습니다.

⚠️ 자주 하는 실수

  • 키를 코드 파일에 적어 저장소에 올립니다: 유출됩니다. 환경 변수와 비밀 관리 도구에 둡니다.
  • 뉴스에 나온 모델 이름을 그대로 넣습니다: 모델 목록 문서의 이름과 제공 상태를 먼저 봅니다.
  • 키를 여러 개 만들어 한도를 늘리려 합니다: 한도는 프로젝트 단위입니다.
  • 무료 등급에 회사 자료를 넣습니다: 입력이 제품 개선에 쓰입니다.
  • 선결제 잔액을 비워 둡니다: 0달러가 되면 키가 전부 멈춥니다.

❓ 자주 묻는 질문

제미나이 앱 요금제를 쓰면 API도 무료인가요?

되지 않습니다. 앱 요금제는 채팅 화면의 사용량을 정하고, API는 AI 스튜디오에서 발급한 키와 결제 계정으로 따로 관리됩니다. 새 API 계정은 무료 등급에서 시작하고, 앱 요금제를 올려도 API 한도는 바뀌지 않습니다.

무료 등급 하루 한도는 몇 번인가요?

문서에 숫자로 공개되어 있지 않습니다. 2026년 9월 28일 기준 구글은 한도가 모델과 등급에 따라 다르며 AI 스튜디오의 한도 화면에서 확인하라고만 안내합니다. 첫 호출 뒤 그 화면에서 직접 보는 것이 정확합니다.

키가 유출된 것 같으면 어떻게 하나요?

문서의 순서는 새 키를 만들고, 코드를 새 키로 바꿔 배포하고, 새 키가 동작하는 것을 확인한 뒤 유출된 키를 비활성화하고, 결제 기록과 사용량에서 이상한 호출이 있었는지 봅니다. 새 키를 확인하기 전에 옛 키를 지우면 서비스가 멈춥니다.

검색 그라운딩은 무료 등급에서 쓸 수 있나요?

2026년 9월 28일 기준 3.x 모델의 검색 그라운딩은 유료 등급에서만 됩니다. 유료 등급은 월 5,000회까지 무료이고 그 뒤 1,000회당 14달러입니다. 최신 정보 없이 시험하는 단계라면 그라운딩을 끄고 먼저 호출해 봅니다.

📋 3줄 요약

  1. 제미나이 API 첫 호출은 AI 스튜디오에서 키를 받아 GEMINI_API_KEY 환경 변수에 넣고 google-genai 라이브러리를 설치한 뒤 모델 이름과 문장 하나로 요청을 보내는 순서이며 새로 만드는 키는 서비스 계정에 묶인 인증 키입니다.

  2. 한도는 분당 요청과 분당 토큰, 하루 요청 세 가지로 프로젝트 단위로 걸리고 숫자는 문서가 아니라 AI 스튜디오의 한도 화면에서 보며, 무료 등급 입력은 구글 제품 개선에 쓰이고 유료는 쓰이지 않습니다.

  3. 2026년 9월 28일 기준 3.8 플래시는 100만 토큰당 입력 0.75달러와 출력 3.75달러이고 이 값은 2026년 12월 31일까지라 2027년부터 두 배가 되며, 유료 등급은 결제 계정을 연결해 최소 5달러를 선결제하면 열립니다.

📚 참고 자료

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

제미나이 API 키를 받아 파이썬 코드에 직접 적어 깃허브 공개 저장소에 올렸습니다. 가장 먼저 할 일은 무엇일까요?

7개념 / 클래스제미나이 딥 리서치(Deep Research) 사용법: 요청 문장과 검증

이어서 배우면 좋은 개념

관련 글