Gemini API 빠른 시작

이 빠른 시작에서는 라이브러리 를 설치하고 Interactions API를 사용하여 첫 번째 Gemini API 요청을 만드는 방법을 보여줍니다.

시작하기 전에

Gemini API를 사용하려면 요청을 인증하고 보안 한도를 적용하며 계정 사용량을 추적하는 데 사용할 API 키가 있어야 합니다.

AI Studio에서 무료로 만들어 시작하세요.

Gemini API 키 만들기

Google GenAI SDK 설치

Python

Python 3.9+ 이상을 사용하여 다음 pip 명령어를 사용하여 google-genai 패키지를 설치합니다.

pip install -q -U google-genai

JavaScript

Node.js v18+을 사용하여 다음 npm 명령어를 사용하여 TypeScript 및 JavaScript용 Google 생성형 AI SDK를 설치합니다.

npm install @google/genai

첫 번째 요청하기

Gemini API에 요청을 보내는 데 사용할 수 있는 방법은 두 가지입니다.

  • (권장) Interactions API는 유형화된 실행 단계를 통해 다단계 도구 사용, 오케스트레이션, 복잡한 추론 흐름을 기본적으로 지원하는 새로운 기본 요소입니다. 향후 기본 메인라인 제품군을 넘어서는 새로운 모델과 새로운 에이전트 기능 및 도구가 Interactions API에서만 출시될 예정입니다.
  • generateContent 는 모델에서 간단한 상태 비저장 응답을 생성하는 방법을 제공합니다. Interactions API를 사용하는 것이 좋지만 generateContent는 완전히 지원됩니다.

이 예에서는 Interactions API를 사용하여 Gemini 3 Flash 모델을 사용하여 Gemini API에 요청을 보냅니다.

API 키를 환경 변수 GEMINI_API_KEY로설정하면 Gemini API 라이브러리를 사용할 때 클라이언트에서 자동으로 선택됩니다 . 그렇지 않으면 클라이언트를 초기화할 때 API 키를 인수로 전달해야 합니다.

Gemini API 문서의 모든 코드 샘플은 환경 변수 GEMINI_API_KEY를 설정했다고 가정합니다.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

# The client gets the API key from the environment variable `GEMINI_API_KEY`.
client = genai.Client()

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

# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

// The client gets the API key from the environment variable `GEMINI_API_KEY`.
const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain how AI works in a few words",
  });

  const modelStep = interaction.steps.find(s => s.type === 'model_output');
  if (modelStep) {
    for (const contentBlock of modelStep.content) {
      if (contentBlock.type === 'text') console.log(contentBlock.text);
    }
  }
}

main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Explain how AI works in a few words"
  }'

상태 비저장 모드

기본적으로 Interactions API는 previous_interaction_id를 사용할 때 서버 측에서 대화 상태를 관리합니다. 클라이언트 측에서 대화 기록을 직접 관리하려면 store=false를 설정하고 후속 요청의 input 필드에 누적된 단계를 전달하여 상태 비저장 모드를 선택할 수 있습니다.

자세한 내용과 전체 다중 턴 상태 비저장 예시는 텍스트 생성 가이드를 참고하세요.

다음 단계

이제 첫 번째 API 요청을 했으므로 Gemini가 작동하는 모습을 보여주는 다음 가이드를 살펴보는 것이 좋습니다.