Gemini API 시작하기

Gemini API 시작하기

Google의 Gemini 모델을 한 번도 다뤄 본 적이 없다면 이 페이지 하나로 시작하면 돼요. API 키를 하나 만들고, SDK를 설치하고, 실제 요청을 한 번 날려 보는 흐름을 그대로 따라가 볼게요. 코드가 조금 길어 보이지만 핵심이 되는 인터랙션 하나만 이해하면 나머지는 다 그 늘어나는 구조라 부담 없습니다.

출처: Gemini API 시작하기 - Google 공식 문서

1. API 키 만들기

Gemini API를 쓰려면 요청을 인증하고, 보안 한도와 사용량을 계정에 연결해 주는 API 키가 필요해요. Google AI Studio가 새 사용자에게 프로젝트와 키를 자동으로 만들어 주니까, API keys 페이지에서 그대로 복사하면 됩니다. 새 키가 필요하면 Create API key를 눌러 키-프로젝트 쌍을 추가하면 돼요.

키는 보통 환경 변수로 등록해 두고 써요:

export GEMINI_API_KEY="YOUR_API_KEY"

무료 티어의 속도 제한이 아쉽다면 유료 티어로 올릴 수 있어요. API keys 또는 Projects 페이지에서 Set up billing을 누르고 Cloud Billing 계정을 연결하면 되고, 최소 $10(또는 해당 통화)의 크레딧을 선불로 채우는 방식이에요.

2. SDK 설치하고 첫 요청 보내기

Python SDK를 설치하고 단 한 번의 호출로 텍스트를 생성해 볼게요.

pip install -U google-genai

클라이언트를 만들고 요청을 보내면 됩니다:

from google import genai

client = genai.Client()

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

REST로도 같은 호출을 할 수 있어요. 엔드포인트는 https://generativelanguage.googleapis.com/v1beta/interactions이고, 인증은 x-goog-api-key 헤더로 전달해요:

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.7-flash",
    "input": "Explain how AI works in a few words"
  }'

REST로 호출하면 API가 메타데이터, 사용량 통계, 그리고 턴의 단계별 이력을 담은 Interaction 리소스 전체를 돌려줘요. SDK는 그 응답 위에 interaction.output_text 같은 편의 속성을 얹어서 최종 출력을 바로 꺼내 쓸 수 있게 해 줍니다.

3. 응답 스트리밍하기

대화가 더 자연스럽게 보이도록, 응답이 생성되는 대로 조각조각 받아 오는 스트리밍도 지원해요. stream=True만 붙이면 이벤트가 순서대로 내려옵니다.

stream = client.interactions.create(
    model="gemini-3.7-flash",
    input="Explain how AI works",
    stream=True
)
for event in stream:
    print(event)

REST에서는 URL에 ?alt=sse를 붙이면 서버가 server-sent events(SSE) 스트림으로 응답해요. 각 이벤트는 event_type과 함께 JSON 데이터를 실어 보냅니다.

4. 멀티턴 대화 이어가기

대화를 이어 가는 방법은 두 가지예요.

상태 유지형(권장): 서버가 previous_interaction_id를 받아 대화 전체 이력을 관리합니다. 대부분의 채팅·에이전트 워크플로에 좋아요.

interaction1 = client.interactions.create(
    model="gemini-3.7-flash",
    input="I have 2 dogs in my house.",
)
interaction2 = client.interactions.create(
    model="gemini-3.7-flash",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
)

무상태형: store=false로 두고 대화 이력을 클라이언트가 직접 관리해요. 이 경우 모델이 만들어 낸 thought, function_call 스텝을 받은 그대로 다 보존해서 다시 보내야 합니다.

더 알아보기