텍스트 생성

Gemini API는 텍스트, 이미지, 동영상, 오디오 입력에서 텍스트 출력을 생성할 수 있습니다.

다음은 기본적인 예입니다.

Python

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="How does AI work?"
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "How does AI work?",
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await 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": "How does AI work?"
  }'

Gemini로 생각하기

Gemini 모델은 요청에 응답하기 전에 모델이 추론할 수 있도록 기본적으로 '사고'가 사용 설정되어 있는 경우가 많습니다.

각 모델은 다양한 사고 구성을 지원하므로 비용, 지연 시간, 인텔리전스를 제어할 수 있습니다. 자세한 내용은 사고 가이드를 참고하세요.

Python

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="How does AI work?",
    generation_config={
        "thinking_level": "low"
    }
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "How does AI work?",
    generation_config: {
      thinking_level: "low",
    },
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await 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": "How does AI work?",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

시스템 요청 사항 및 기타 구성

시스템 요청 사항을 사용하여 Gemini 모델의 동작을 안내할 수 있습니다. system_instruction 매개변수를 전달하여 모델의 동작을 구성합니다.

Python

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    system_instruction="You are a cat. Your name is Neko.",
    input="Hello there"
)

print(interaction.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Hello there",
    system_instruction: "You are a cat. Your name is Neko.",
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await 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",
    "system_instruction": "You are a cat. Your name is Neko.",
    "input": "Hello there"
  }'

generation_config 파라미터를 사용하여 온도와 같은 기본 생성 파라미터를 재정의할 수도 있습니다.

Python

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

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain how AI works",
    generation_config={
        "temperature": 1.0
    }
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain how AI works",
    generation_config: {
      temperature: 1.0,
    },
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await 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",
    "generation_config": {
      "temperature": 1.0
    }
  }'

구성 가능한 매개변수와 설명의 전체 목록은 Interactions API 참조를 참고하세요.

멀티모달 입력

Gemini API는 멀티모달 입력을 지원하므로 텍스트와 미디어 파일을 결합할 수 있습니다. 다음 예에서는 이미지를 제공하는 방법을 보여줍니다.

Python

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

client = genai.Client()

uploaded_file = client.files.upload(file="path/to/organ.jpg")

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Tell me about this instrument"},
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type
        }
    ]
)
print(interaction.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const uploadedFile = await ai.files.upload({
    file: "path/to/organ.jpg",
    config: { mimeType: "image/jpeg" }
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      {type: "text", text: "Tell me about this instrument"},
      {
        type: "image",
        uri: uploadedFile.uri,
        mime_type: uploadedFile.mimeType
      }
    ],
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await main();

REST

# First upload the file using the Files API, then use the URI:
# 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": [
      {"type": "text", "text": "Tell me about this instrument"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg"
      }
    ]
  }'

이미지를 제공하는 다른 방법과 고급 이미지 처리에 관한 내용은 이미지 이해 가이드를 참고하세요. API는 문서, 동영상, 오디오 입력 및 이해도 지원합니다.

스트리밍 응답

기본적으로 모델은 전체 생성 프로세스가 완료된 후에만 대답을 반환합니다.

더 원활한 상호작용을 위해 스트리밍을 사용하여 응답 청크가 생성될 때 이를 처리하세요.

Python

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

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain how AI works",
    stream=True
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="")

자바스크립트

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

const ai = new GoogleGenAI({});

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

  for await (const event of stream) {
    if (event.event_type === "step.delta") {
      if (event.delta.type === "text") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

await main();

REST

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

멀티턴 대화

Interactions API는 previous_interaction_id를 사용하여 상호작용을 연결하여 멀티턴 대화를 지원합니다. 각 턴은 별도의 상호작용이며 API는 대화 기록을 자동으로 관리합니다.

Python

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

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="I have 2 dogs in my house.",
)
print(interaction1.steps[-1].content[0].text)

interaction2 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
)
print(interaction2.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction1 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "I have 2 dogs in my house.",
  });
  console.log("Response 1:", interaction1.steps.at(-1).content[0].text);

  const interaction2 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "How many paws are in my house?",
    previous_interaction_id: interaction1.id,
  });
  console.log("Response 2:", interaction2.steps.at(-1).content[0].text);
}

await main();

REST

# Specifies the API revision to avoid breaking changes when they become default
RESPONSE1=$(curl -s -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": "I have 2 dogs in my house."
  }')

INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')

# 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": "I have two dogs in my house. How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'"
  }'

스트리밍을 사용하면 previous_interaction_id을 스트리밍 메서드와 결합하여 멀티턴 대화에도 사용할 수 있습니다.

Python

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

client = genai.Client()

interaction1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="I have 2 dogs in my house.",
)
print(interaction1.steps[-1].content[0].text)

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="How many paws are in my house?",
    previous_interaction_id=interaction1.id,
    stream=True
)
for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "text":
            print(event.delta.text, end="")

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  const interaction1 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "I have 2 dogs in my house.",
  });
  console.log("Response 1:", interaction1.steps.at(-1).content[0].text);

  const stream = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "How many paws are in my house?",
    previous_interaction_id: interaction1.id,
    stream: true,
  });
  for await (const event of stream) {
    if (event.event_type === "step.delta") {
      if (event.delta.type === "text") {
        process.stdout.write(event.delta.text);
      }
    }
  }
}

await main();

REST

# Specifies the API revision to avoid breaking changes when they become default
RESPONSE1=$(curl -s -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": "I have 2 dogs in my house."
  }')
INTERACTION_ID=$(echo "$RESPONSE1" | jq -r '.id')

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  --no-buffer \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "How many paws are in my house?",
    "previous_interaction_id": "'$INTERACTION_ID'",
    "stream": true
  }'

스테이트리스 대화

기본적으로 previous_interaction_id를 사용하면 Interactions API가 대화 상태를 서버 측에서 관리합니다. 하지만 클라이언트 측에서 직접 대화 기록을 관리하여 상태 비저장 모드로 작동할 수도 있습니다.

스테이트리스 모드를 사용하려면 다음 단계를 따르세요. 1. 요청에서 store=false를 설정하여 서버 측 스토리지를 선택 해제합니다. 2. 클라이언트 측에서 대화 기록을 단계 배열로 유지합니다. 3. 후속 요청에서는 누적된 단계를 input 필드에 전달하고 새 턴을 user_input 단계로 추가합니다.

Python

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

client = genai.Client()

# Initialize history with the first user turn
history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "I have 2 dogs in my house."}]
    }
]

# Turn 1: Send request with store=False
interaction1 = client.interactions.create(
    model="gemini-3-flash-preview",
    store=False,
    input=history
)
print("Response 1:", interaction1.steps[-1].content[0].text)

# Append the model's response steps to history
for step in interaction1.steps:
    # Convert the SDK Step object to a dictionary
    history.append(step.model_dump())

# Append the next user turn as a user_input step
history.append({
    "type": "user_input",
    "content": [{"type": "text", "text": "How many paws are in my house?"}]
})

# Turn 2: Send full history with store=False
interaction2 = client.interactions.create(
    model="gemini-3-flash-preview",
    store=False,
    input=history
)
print("Response 2:", interaction2.steps[-1].content[0].text)

자바스크립트

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

const ai = new GoogleGenAI({});

async function main() {
  // Initialize history with the first user turn
  const history = [
    {
      type: "user_input",
      content: [{ type: "text", text: "I have 2 dogs in my house." }]
    }
  ];

  // Turn 1: Send request with store: false
  const interaction1 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    store: false,
    input: history
  });
  console.log("Response 1:", interaction1.steps.at(-1).content[0].text);

  // Append model response steps to history
  history.push(...interaction1.steps);

  // Append the next user turn
  history.push({
    type: "user_input",
    content: [{ type: "text", text: "How many paws are in my house?" }]
  });

  // Turn 2: Send full history with store: false
  const interaction2 = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    store: false,
    input: history
  });
  console.log("Response 2:", interaction2.steps.at(-1).content[0].text);
}

await main();

REST

# Turn 1: Send request with store: false
# Specifies the API revision to avoid breaking changes when they become default
RESPONSE1=$(curl -s -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",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "I have 2 dogs in my house."}]
      }
    ]
  }')

# Extract the steps from response
MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')

# Reconstruct the full history for Turn 2 by combining:
# 1. First user input
# 2. Model response steps
# 3. Second user input
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": [{"type": "text", "text": "I have 2 dogs in my house."}]}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --argjson second_input '[{"type": "user_input", "content": [{"type": "text", "text": "How many paws are in my house?"}]}]' \
  "'"'"'$first_input + $model_steps + $second_input'"'"'")

# Turn 2: Send the full history
# 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\",
    \"store\": false,
    \"input\": $HISTORY
  }"

프롬프트 작성 팁

Gemini를 최대한 활용하는 방법에 관한 제안은 프롬프트 엔지니어링 가이드를 참고하세요.

다음 단계