domains / software-engineering / gemini-api-integration / gemini-interactions-api

gemini-interactions-api

Skill card

combined

The two skills cover the same API but contain conflicting and complementary information. The google/skills copy provides detailed authentication steps (gcloud login, API enablement) and specific client initialization options (env vars vs inline vs API key) that the sickn33 copy omits. Conversely, the sickn33 copy lists a broader range of supported models (including image, video, TTS, and Gemma models) and specific response helper properties (output_image, output_audio) that the google/skills copy lacks. Crucially, they disagree on the recommended default model (gemini-3.8-flash vs gemini-3.5-flash) and the scope of the API (google/skills focuses on the 'Enterprise Agent Platform' with specific env vars, while sickn33 presents a more general 'Gemini API' usage). Combining them is necessary to provide a complete and accurate guide that includes both the authentication/setup details and the full model/response surface.

Repositories

Other copies

Combined skill

---
name: gemini-interactions-api
description: Guides the usage of Gemini Interactions API for multi-turn conversations, background execution, streaming, structured output, function calling, and multimodal generation.
---

# Gemini Interactions API Skill

This skill provides instructions for authenticating, connecting to, and utilizing the stateful, server-managed **Gemini Interactions API**.

> [!IMPORTANT] **CRITICAL: Unified SDK, Latest Models & Model/Agent Targeting**
> **Unified SDK**: Use the Google Gen AI SDK (**`google-genai >= 2.3.0`** for Python, **`@google/genai >= 2.3.0`** for JS/TS). Legacy SDKs like `google-cloud-aiplatform`, `@google-cloud/vertexai`, `google-generativeai`, and `@google/generative-ai` are strictly unsupported for Interactions.
> **Latest Models Only**: Use current models such as `gemini-3.5-flash` (fast, balanced, multimodal), `gemini-3.1-pro-preview` (complex reasoning), or `gemini-3.1-flash-lite` (cost-efficient). For multimodal generation, use `gemini-3-pro-image`, `gemini-3.1-flash-tts-preview`, or `gemini-omni-flash-preview`. Legacy models (`gemini-2.5-*`, `gemini-2.0-*`, `gemini-1.5-*`) are deprecated. If a user asks for a deprecated model, use `gemini-3.5-flash` instead and note the substitution.
> **Model & Agent Targeting**: Target foundation models directly using `model="..."`, or target autonomous managed/custom agents using `agent="<AGENT_ID>"`. Managed agents require `environment="remote"`.
> **Turn-Scoped Parameters**: Parameters like `tools`, `system_instruction`, and `generation_config` are turn-scoped. They **MUST** be passed with each interaction request.

## 1. Authentication & Setup

1. **Login** (for Enterprise/ADC):
   ```bash
   gcloud auth application-default login
   ```
2. **Enable API** (if not already enabled):
   ```bash
   gcloud services enable aiplatform.googleapis.com
   ```

## 2. Client Initialization

### Option A: Environment Variables (Recommended for Enterprise)

```bash
export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
```

#### Python
```python
from google import genai
client = genai.Client()
```

#### TypeScript/JavaScript
```typescript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI();
```

### Option B: Explicit Inline Parameters

#### Python
```python
from google import genai
import google.auth
_, project_id = google.auth.default()
client = genai.Client(enterprise=True, project=project_id, location="global")
```

### Option C: Express Mode (API Key)

#### Python
```python
from google import genai
client = genai.Client(enterprise=True, api_key="YOUR_API_KEY")
```

## 3. Core Interactions API Usage

### Quick Start (Single-Turn)

#### Python
```python
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain serverless computing in one sentence."
)
print(interaction.output_text)
```

#### TypeScript/JavaScript
```typescript
const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Explain serverless computing in one sentence."
});
console.log(interaction.output_text);
```

### Stateful Conversation (Multi-Turn)

Interactions are stateful by default. Store the conversation state in the cloud and reference it in the subsequent turn using `previous_interaction_id`.

#### Python
```python
# Turn 1
interaction1 = client.interactions.create(
    model="gemini-3.5-flash",
    input="Hi, my name is Phil."
)
# Turn 2
interaction2 = client.interactions.create(
    model="gemini-3.5-flash",
    input="What is my name?",
    previous_interaction_id=interaction1.id
)
print(interaction2.output_text)
```

## 4. Response Helpers

The SDK provides convenience properties on the `Interaction` response object:

| Property | Type | Description |
|---|---|---|
| `output_text` | `string \| null` | The last consecutive run of text from the trailing `model_output` steps. |
| `output_image` | `Image \| null` | The last image generated by the model. Returns an object with `data` (base64) and `mime_type`. |
| `output_audio` | `Audio \| null` | The last audio generated by the model. Returns an object with `data` (base64) and `mime_type`. |

## 5. Important Notes

- **Storage**: Interactions are stored by default (`store=true`). Paid tier retains for 55 days, free tier for 1 day. Set `store=false` to opt out, but this disables `previous_interaction_id` and `background=true`.
- **Documentation**: Before writing complex code, fetch the relevant documentation page for the full API surface and edge cases.
- **Migration**: When migrating from `generateContent`, refer to migration guides for scoping and checklists.