Начало работы

Это руководство поможет вам начать работу с API Gemini, используя API взаимодействий . Вы совершите свой первый вызов API менее чем за минуту и ​​изучите генерацию текста, понимание мультимодальных данных, генерацию изображений, структурированный вывод, инструменты, вызов функций, агентов и фоновое выполнение.

API для взаимодействия доступен через SDK для Python и JavaScript , а также через REST.

1. Получите ключ API.

Для использования API Gemini вам потребуется ключ API, который позволит аутентифицировать ваши запросы, устанавливать ограничения безопасности и отслеживать использование в рамках вашей учетной записи.

  • Google AI Studio автоматически создает проект и ключ API для новых пользователей. Вы можете скопировать его со страницы ключей API .
  • Если вам нужен новый ключ, нажмите «Создать ключ API» в AI Studio и следуйте инструкциям в диалоговом окне, чтобы добавить новую пару «ключ-проект».

Создайте ключ API Gemini

Установите свой ключ в качестве переменной окружения:

export GEMINI_API_KEY="YOUR_API_KEY"

Перейдите на платный тариф

Переход на платный тариф увеличивает лимиты трафика и требует настройки облачной оплаты.

  • На страницах ключей API AI Studio или проектов нажмите «Настроить выставление счетов» .
  • В диалоговом окне «Облачные платежи» создайте или свяжите платежный аккаунт, добавьте способ оплаты и внесите предоплату в размере не менее 10 долларов США (или эквивалентной суммы в другой валюте).
  • Просматривайте использование API в Google AI Studio в разделе «Панель управления» > «Использование» .

Дополнительную информацию см. на странице «Оплата» .

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.7-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

JavaScript

Установите SDK:

npm install @google/genai

Инициализируйте клиент и отправьте запрос:

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

const ai = new GoogleGenAI({});

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

ОТДЫХ 

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"
  }'

Ответ:

{
  "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.7-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.7-flash",
    input="Explain how AI works",
    stream=True
)
for event in stream:
    print(event)

JavaScript 

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

const ai = new GoogleGenAI({});

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

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

ОТДЫХ 

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.7-flash",
    "input": "Explain how AI works",
    "stream": true
  }'

При потоковой передаче сервер отвечает потоком событий, отправляемых сервером (SSE). Каждое событие включает в себя тип и данные в формате JSON.

Ответ: 

event: interaction.created
data: {"interaction":{"id":"v1_Chd...","status":"in_progress","model":"gemini-3.7-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. Многоэтапные переговоры

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.7-flash",
    input="I have 2 dogs in my house.",
)
print("Response 1:", interaction1.output_text)

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

JavaScript 

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

const ai = new GoogleGenAI({});

// Server-side state (recommended)
const interaction1 = await ai.interactions.create({
  model: "gemini-3.7-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.7-flash",
  input: "How many paws are in my house?",
  previous_interaction_id: interaction1.id,
});
console.log("Response 2:", interaction2.output_text);

ОТДЫХ 

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

Лица без гражданства

Установите 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.7-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?"}]
})

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

JavaScript 

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

const ai = new GoogleGenAI({});

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

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

history.push(...interaction1.steps);

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

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

ОТДЫХ 

# Turn 1: Send with store: false
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.7-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": "I have 2 dogs in my house."
      }
    ]
  }')

MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')

# Turn 2: Build full history
HISTORY=$(jq -n \
  --argjson first_input '[{"type": "user_input", "content": "I have 2 dogs in my house."}]' \
  --argjson model_steps "$MODEL_STEPS" \
  --argjson second_input '[{"type": "user_input", "content": "How many paws are in my house?"}]' \
  '$first_input + $model_steps + $second_input')

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\",
    \"store\": false,
    \"input\": $HISTORY
  }"

Ответ: 

{
  "id": "v2_Chd...",