시작하기

이 가이드에서는 Interactions API를 사용하여 Gemini API를 시작하는 방법을 설명합니다. 1분 이내에 첫 번째 API 호출을 하고 텍스트 생성, 멀티모달 이해, 이미지 생성, 구조화된 출력, 도구, 함수 호출, 에이전트, 백그라운드 실행을 살펴봅니다.

Interactions API는 Python 및 JavaScript SDK와 REST를 통해 사용할 수 있습니다.

1. API 키 가져오기

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

  • Google AI Studio는 신규 사용자를 위해 프로젝트와 API 키를 자동으로 생성합니다. API 키 페이지에서 복사할 수 있습니다.
  • 새 키가 필요한 경우 AI Studio에서 API 키 만들기를 클릭하고 대화상자에 따라 새 키-프로젝트 쌍을 추가합니다.

Gemini API 키 만들기

키를 환경 변수로 설정합니다.

export GEMINI_API_KEY="YOUR_API_KEY"

유료 등급으로 업그레이드

유료 등급으로 업그레이드하면 비율 제한이 증가하며 Cloud Billing을 설정해야 합니다.

  • AI Studio API 키 또는 프로젝트 페이지에서 결제 설정을 클릭합니다.
  • Cloud Billing 대화상자에 따라 결제 계정을 만들거나 연결하고, 지급 수단을 추가하고, 유료 크레딧으로 최소 10달러 (또는 해당 통화)를 선불합니다.
  • Google AI Studio의 대시보드 > 사용량에서 API 사용량을 확인합니다.

자세한 내용은 결제 페이지를 참고하세요.

2. SDK 설치 및 첫 번째 호출 만들기

SDK를 설치하고 단일 API 호출로 텍스트를 생성합니다.

Python

SDK를 설치합니다.

pip install -U google-genai

클라이언트를 초기화하고 요청을 합니다.

from google import genai

client = genai.Client()

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

자바스크립트

SDK를 설치합니다.

npm install @google/genai

클라이언트를 초기화하고 요청을 합니다.

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.6-flash",
  input: "Explain how AI works in a few words",
});
console.log(interaction.output_text);

REST

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

대답:

{
  "id": "v1_ChdpQUFvYXI...",
  "status": "completed",
  "usage": {
    "total_tokens": 197,
    "total_input_tokens": 8,
    "total_output_tokens": 12
  },
  "created": "2026-06-09T12:01:25Z",
  "steps": [
    {
      "type": "thought",
      "signature": "EvEFCu4FAQw..."
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "AI learns patterns from data, then uses those patterns to make predictions or decisions on new data."
        }
      ]
    }
  ],
  "object": "interaction",
  "model": "gemini-3.6-flash",
}

REST를 사용하면 API는 메타데이터, 사용 통계, 턴의 단계별 기록이 포함된 전체 Interaction 리소스를 반환합니다.

SDK는 전체 응답을 노출하는 동시에 최종 출력에 직접 액세스할 수 있는 interaction.output_text, interaction.output_image과 같은 편의 속성도 제공합니다. 상호작용 개요에서 응답 구조에 대해 자세히 알아보거나 텍스트 생성 가이드에서 시스템 안내 및 생성 구성에 대해 자세히 알아보세요.

3. 대답 스트리밍

더 원활한 상호작용을 위해 대답이 생성되는 대로 스트리밍하세요. 각 step.delta 이벤트는 즉시 표시할 수 있는 텍스트 청크를 제공합니다.

Python

from google import genai

client = genai.Client()

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

자바스크립트

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const stream = await ai.interactions.create({
  model: "gemini-3.6-flash",
  input: "Explain how AI works",
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Explain how AI works",
    "stream": true
  }'

스트리밍 시 서버는 서버 전송 이벤트 (SSE) 스트림으로 응답합니다. 각 이벤트에는 유형과 JSON 데이터가 포함됩니다.

대답:

event: interaction.created
data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.6-flash"},"event_type":"interaction.created"}

event: step.start
data: {"index":0,"step":{"type":"thought"},"event_type":"step.start"}

event: step.delta
data: {"index":0,"delta":{"signature":"EvEFCu4F...","type":"thought_signature"},"event_type":"step.delta"}

event: step.stop
data: {"index":0,"event_type":"step.stop"}

event: step.start
data: {"index":1,"step":{"type":"model_output"},"event_type":"step.start"}

event: step.delta
data: {"index":1,"delta":{"text":"AI ","type":"text"},"event_type":"step.delta"}

event: step.delta
data: {"index":1,"delta":{"text":"works ","type":"text"},"event_type":"step.delta"}

event: step.stop
data: {"index":1,"event_type":"step.stop"}

event: interaction.completed
data: {"interaction":{"id":"v1_Chd...","status":"completed","usage":{"total_tokens":197}},"event_type":"interaction.completed"}

스트리밍 이벤트 및 델타 유형 처리에 관한 자세한 내용은 스트리밍 상호작용 가이드를 참고하세요.

4. 멀티턴 대화

Interactions API는 다음 두 가지 접근 방식으로 멀티턴 대화를 지원합니다.

  • 상태 저장 (권장): previous_interaction_id를 사용하여 서버에서 대화를 계속합니다. 서버에서 기록을 관리하고 캐싱을 최적화해야 하는 대부분의 채팅 및 에이전트 워크플로에 적합합니다.

  • 스테이트리스: 각 요청에서 이전 턴 (중간 모델 사고 및 도구 단계 포함)을 모두 전달하여 클라이언트에서 대화 기록을 관리합니다.

previous_interaction_id를 전달하여 상호작용을 연결합니다. 서버에서 전체 대화 기록을 관리합니다.

Python

from google import genai

client = genai.Client()

# Server-side state (recommended)
interaction1 = client.interactions.create(
    model="gemini-3.6-flash",
    input="I have 2 dogs in my house.",
)
print("Response 1:", interaction1.output_text)

interaction2 = client.interactions.create(
    model="gemini-3.6-flash",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
)
print("Response 2:", interaction2.output_text)

자바스크립트

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Server-side state (recommended)
const interaction1 = await ai.interactions.create({
  model: "gemini-3.6-flash",
  input: "I have 2 dogs in my house.",
});
console.log("Response 1:", interaction1.output_text);

const interaction2 = await ai.interactions.create({
  model: "gemini-3.6-flash",
  input: "How many paws are in my house?",
  previous_interaction_id: interaction1.id,
});
console.log("Response 2:", interaction2.output_text);

REST

RESPONSE1=$(curl -s -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.6-flash",
    "input": "I have 2 dogs in my house."
  }')

INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')
echo "Interaction 1 ID: $INTERACTION_ID"

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.6-flash",
    "input": "How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'"
  }'

스테이트리스(Stateless)

클라이언트 측에서 store=false를 설정하고 대화 기록을 관리합니다. 모델에서 생성된 모든 단계 (thought 및 function_call 단계 포함)를 수신된 그대로 유지하고 다시 전송해야 합니다.

Python

from google import genai

client = genai.Client()

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "I have 2 dogs in my house."}]
    }
]

interaction1 = client.interactions.create(
    model="gemini-3.6-flash",
    store=False,
    input=history
)
print("Response 1:", interaction1.steps[-1].content[0].text)

for step in interaction1.steps:
    history.append(step.model_dump())

history.append({
    "type": "user_input",
    "content": [{"type": "text", "text": "How many paws are in my house?"}]