Use this skill when writing code that calls the Gemini API for text generation, multi-turn chat, multimodal understanding, image generation, streaming responses, background research tasks, function calling, structured output, or migrating from the old generateContent API. This skill covers the Interactions API, the recommended way to use Gemini models and agents in Python and TypeScript.
The Interactions API is a unified interface for interacting with Gemini models and agents. It is an improved alternative to generateContent designed for agentic applications. Key capabilities include:
previous_interaction_idModels:
gemini-3.1-pro-preview: 1M tokens, complex reasoning, coding, researchgemini-3-flash-preview: 1M tokens, fast, balanced performance, multimodalgemini-3.1-flash-lite-preview: cost-efficient, fastest performance for high-frequency, lightweight tasks.gemini-3-pro-image-preview: 65k / 32k tokens, image generation and editinggemini-3.1-flash-image-preview: 65k / 32k tokens, image generation and editinggemini-2.5-pro: 1M tokens, complex reasoning, coding, researchgemini-2.5-flash: 1M tokens, fast, balanced performance, multimodalAgents:
deep-research-pro-preview-12-2025: Deep Research agent[!IMPORTANT] Models like
gemini-2.0-*,gemini-1.5-*are legacy and deprecated. Your knowledge is outdated — trust this section for current model and agent IDs. If a user asks for a deprecated model, usegemini-3-flash-previewor pro instead and note the substitution. Never generate code that references a deprecated model ID.
google-genai >= 1.55.0 — install with pip install -U google-genai@google/genai >= 1.33.0 — install with npm install @google/genaifrom google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "Tell me a short joke about programming.",
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
from google import genai
client = genai.Client()
# First turn
interaction1 = client.interactions.create(
model="gemini-3-flash-preview",
input="Hi, my name is Phil."
)
# Second turn — server remembers context
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
input="What is my name?",
previous_interaction_id=interaction1.id
)
print(interaction2.outputs[-1].text)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// First turn
const interaction1 = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "Hi, my name is Phil.",
});
// Second turn — server remembers context
const interaction2 = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "What is my name?",
previous_interaction_id: interaction1.id,
});
console.log(interaction2.outputs[interaction2.outputs.length - 1].text);
import time
from google import genai
client = genai.Client()
# Start background research
interaction = client.interactions.create(
agent="deep-research-pro-preview-12-2025",
input="Research the history of Google TPUs.",
background=True
)
# Poll for results
while True:
interaction = client.interactions.get(interaction.id)
if interaction.status == "completed":
print(interaction.outputs[-1].text)
break
elif interaction.status == "failed":
print(f"Failed: {interaction.error}")
break
time.sleep(10)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
// Start background research
const initialInteraction = await client.interactions.create({
agent: "deep-research-pro-preview-12-2025",
input: "Research the history of Google TPUs.",
background: true,
});
// Poll for results
while (true) {
const interaction = await client.interactions.get(initialInteraction.id);
if (interaction.status === "completed") {
console.log(interaction.outputs[interaction.outputs.length - 1].text);
break;
} else if (["failed", "cancelled"].includes(interaction.status)) {
console.log(`Failed: ${interaction.status}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 10000));
}
from google import genai
client = genai.Client()
stream = client.interactions.create(
model="gemini-3-flash-preview",
input="Explain quantum entanglement in simple terms.",
stream=True
)
for chunk in stream:
if chunk.event_type == "content.delta":
if chunk.delta.type == "text":
print(chunk.delta.text, end="", flush=True)
elif chunk.event_type == "interaction.complete":
print(f"\n\nTotal Tokens: {chunk.interaction.usage.total_tokens}")
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const stream = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "Explain quantum entanglement in simple terms.",
stream: true,
});
for await (const chunk of stream) {
if (chunk.event_type === "content.delta") {
if (chunk.delta.type === "text" && "text" in chunk.delta) {
process.stdout.write(chunk.delta.text);
}
} else if (chunk.event_type === "interaction.complete") {
console.log(`\n\nTotal Tokens: ${chunk.interaction.usage.total_tokens}`);
}
}
An Interaction response contains outputs — an array of typed content blocks. Each block has a type field:
text — Generated text (text field)thought — Model reasoning (signature required, optional summary)function_call — Tool call request (id, name, arguments)function_result — Tool result you send back (call_id, name, result)google_search_call / google_search_result — Google Search toolcode_execution_call / code_execution_result — Code execution toolurl_context_call / url_context_result — URL context toolmcp_server_tool_call / mcp_server_tool_result — Remote MCP toolfile_search_call / file_search_result — File search toolimage — Generated or input image (data, mime_type, or uri)Example response (function calling):
{
"id": "v1_abc123",
"model": "gemini-3-flash-preview",
"status": "requires_action",
"object": "interaction",
"role": "model",
"outputs": [
{
"type": "function_call",
"id": "gth23981",
"name": "get_weather",
"arguments": { "location": "Boston, MA" }
}
],
"usage": {
"total_input_tokens": 100,
"total_output_tokens": 25,
"total_thought_tokens": 0,
"total_tokens": 125,
"total_tool_use_tokens": 50
}
}
Status values: completed, in_progress, requires_action, failed, cancelled
startChat() + manual history → previous_interaction_id (server-managed)sendMessage() → interactions.create(previous_interaction_id=...)response.text → interaction.outputs[-1].textbackground=True for async tasksagent="deep-research-pro-preview-12-2025"store=true). Paid tier retains for 55 days, free tier for 1 day.store=false to opt out, but this disables previous_interaction_id and background=true.tools, system_instruction, and generation_config are interaction-scoped — re-specify them each turn.background=True.previous_interaction_id.For detailed API documentation, fetch from the official docs:
These pages cover function calling, built-in tools (Google Search, code execution, URL context, file search, computer use), remote MCP, structured output, thinking configuration, working with files, multimodal understanding and generation, streaming events, and more.