Interactions API

Interactions API เป็นวิธีที่ดีที่สุดในการสร้างด้วยโมเดลและ Agent ของ Gemini ตั้งแต่เดือนมิถุนายน 2026 เป็นต้นไป จะพร้อมให้บริการโดยทั่วไปและแนะนำให้ใช้กับโปรเจ็กต์ใหม่ทั้งหมด แม้ว่าตอนนี้จะถือว่าเป็นเวอร์ชันเดิมแล้ว แต่เรายังคงรองรับ generateContent API ต้นฉบับอย่างเต็มรูปแบบ

เหตุใดจึงต้องใช้ Interactions API

• อินเทอร์เฟซอเนกประสงค์สำหรับแอปพลิเคชันทั้งหมด: ออกแบบมาให้เป็นอินเทอร์เฟซมาตรฐาน สำหรับทุกกรณีการใช้งาน ซึ่งรวมถึงการสร้างข้อความแบบเทิร์นเดียว การทำความเข้าใจแบบมัลติโมดอล เอาต์พุตที่มีโครงสร้าง การประสานเครื่องมือ และ เวิร์กโฟลว์ของเอเจนต์
• API เดียวสำหรับโมเดลและเอเจนต์: Endpoint และรูปแบบที่รวมเป็นหนึ่งเดียวสำหรับ การเรียกโมเดล Gemini มาตรฐาน รวมถึงเอเจนต์เฉพาะทางโดยตรง (เช่น Deep Research และเอเจนต์ที่จัดการแบบกำหนดเอง)
• ความสามารถใหม่ที่พร้อมใช้งานทันที: ฟีเจอร์ต่างๆ เช่น สถานะการสนทนาฝั่งเซิร์ฟเวอร์ที่ไม่บังคับ โดยใช้ previous_interaction_id, ขั้นตอนการดำเนินการที่สังเกตได้ สำหรับการแก้ไขข้อบกพร่องและการแสดงผล UI และการดำเนินการในเบื้องหลัง สำหรับงานที่ใช้เวลานาน โดยใช้ background=true
• ลดต้นทุนด้วยอัตราการพบแคชที่สูงขึ้น: เมื่อใช้การสนทนาไปมา การจัดการสถานะฝั่งเซิร์ฟเวอร์ที่ไม่บังคับจะช่วยให้แคชบริบทมีประสิทธิภาพมากขึ้นในแต่ละรอบ ซึ่งจะช่วยลดต้นทุนโทเค็น
• ที่ที่จะเปิดตัวฟีเจอร์ใหม่: ต่อไปนี้ โมเดลใหม่ทั้งหมด ความสามารถแบบมัลติโมดัล เครื่องมือ และฟีเจอร์แบบเอเจนต์จะเปิดตัวใน Interactions API

โดยค่าเริ่มต้น Interactions API จะจัดเก็บคำขอเพื่อให้คุณใช้ประโยชน์จาก ฟีเจอร์การจัดการสถานะฝั่งเซิร์ฟเวอร์ได้โดยใช้ previous_interaction_id คุณเลือกใช้ลักษณะการทำงานแบบไม่เก็บสถานะได้โดยการตั้งค่า store=false ดูรายละเอียดได้ที่ส่วนการเก็บรักษาข้อมูล

เริ่มต้นใช้งาน

• ตั้งค่า Agent การเขียนโค้ด: เชื่อมต่อกับ MCP ของเอกสาร Gemini และติดตั้ง ทักษะ gemini-api-dev เพื่อให้ผู้ช่วยของคุณเข้าถึง เอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ล่าสุดและแนวทางปฏิบัติแนะนำได้โดยตรง โปรดดูขั้นตอนโดยละเอียดที่คู่มือการตั้งค่าเอเจนต์การเขียนโค้ด
• ย้ายข้อมูลจาก generateContent: หากมีการผสานรวมอยู่แล้ว โปรดทำตามคู่มือการย้ายข้อมูลเพื่อ เปลี่ยนไปใช้ Interactions API
• เริ่มต้นใช้งาน: ทำตามขั้นตอนในคู่มือการเริ่มต้นใช้งาน Interactions API

คำแนะนำฟีเจอร์

สำรวจความสามารถเฉพาะของ Interactions API ผ่านคำแนะนำเหล่านี้ คุณใช้ปุ่มเปิด/ปิดในหน้าเหล่านี้เพื่อสลับระหว่าง GenerateContent API กับ Interactions API ได้

• การสร้างข้อความ
• การสร้างรูปภาพ
• การทำความเข้าใจรูปภาพ
• การทำความเข้าใจเสียง
• การทำความเข้าใจวิดีโอ
• การประมวลผลเอกสาร
• การเรียกใช้ฟังก์ชัน
• เอาต์พุตที่มีโครงสร้าง
• เอเจนต์ Deep Research
• Flex Inference
• การอนุมานตามลำดับความสำคัญ

วิธีการทำงานของ Interactions API

API การโต้ตอบมีทรัพยากรหลักคือ Interaction Interaction แสดงถึงการสนทนาหรือภารกิจที่เสร็จสมบูรณ์ โดยจะทำหน้าที่เป็นบันทึกเซสชัน ซึ่งมีประวัติการโต้ตอบทั้งหมดเป็นลำดับขั้นตอนการดำเนินการตามลำดับเวลา ขั้นตอนเหล่านี้รวมถึงความคิดของโมเดล การเรียกใช้เครื่องมือและผลลัพธ์ฝั่งเซิร์ฟเวอร์หรือฝั่งไคลเอ็นต์ (เช่น function_call และ function_result) และ model_output สุดท้าย ทรัพยากรที่จัดเก็บ (ดึงข้อมูลผ่าน interactions.get) ยังมีขั้นตอน user_input สำหรับบริบททั้งหมดด้วย แม้ว่าคำตอบ interactions.create จะแสดงเฉพาะขั้นตอนที่โมเดลสร้างขึ้นก็ตาม

เมื่อโทรหา interactions.create คุณจะ สร้างทรัพยากร Interaction ใหม่

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

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

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

การจัดการสถานะฝั่งเซิร์ฟเวอร์

คุณสามารถใช้ id ของการโต้ตอบที่เสร็จสมบูรณ์ในการเรียกครั้งถัดไปโดยใช้พารามิเตอร์ previous_interaction_id เพื่อสนทนาต่อ เซิร์ฟเวอร์ ใช้รหัสนี้เพื่อดึงประวัติการสนทนา ซึ่งช่วยให้คุณไม่ต้อง ส่งประวัติการแชททั้งหมดอีกครั้ง

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

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

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

พารามิเตอร์ previous_interaction_id จะเก็บเฉพาะประวัติการสนทนา (อินพุตและเอาต์พุต) โดยใช้ previous_interaction_id พารามิเตอร์อื่นๆ เป็นระดับการโต้ตอบ และมีผลกับการโต้ตอบที่เฉพาะเจาะจงที่คุณสร้างขึ้นในขณะนี้เท่านั้น

• tools
• system_instruction
• generation_config (รวมถึง thinking_level, temperature ฯลฯ)

ซึ่งหมายความว่าคุณต้องระบุพารามิเตอร์เหล่านี้อีกครั้งในการโต้ตอบใหม่แต่ละครั้งหากต้องการให้มีผล การจัดการสถานะฝั่งเซิร์ฟเวอร์นี้เป็นตัวเลือก คุณยัง ใช้งานในโหมดไม่มีสถานะได้ด้วยการส่งประวัติการสนทนาทั้งหมดในแต่ละ คำขอ

การจัดเก็บและการเก็บรักษาข้อมูล

โดยค่าเริ่มต้น API จะจัดเก็บออบเจ็กต์การโต้ตอบทั้งหมด (store=true) เพื่อลดความซับซ้อนในการใช้ฟีเจอร์การจัดการสถานะฝั่งเซิร์ฟเวอร์ (ด้วยprevious_interaction_id), การดำเนินการในเบื้องหลัง (โดยใช้ background=true) และวัตถุประสงค์ด้านความสามารถในการสังเกต

• ระดับแบบชำระเงิน: ระบบจะเก็บรักษาการโต้ตอบไว้เป็นเวลา 55 วัน
• ระดับฟรี: ระบบจะเก็บการโต้ตอบไว้เป็นเวลา 1 วัน

หากไม่ต้องการให้ระบบดำเนินการ คุณสามารถ ตั้งค่า store=false ในคำขอได้ การควบคุมนี้แยกจากการจัดการสถานะ คุณเลือกไม่ใช้พื้นที่เก็บข้อมูลสำหรับการโต้ตอบใดก็ได้ อย่างไรก็ตาม โปรดทราบว่า store=false ใช้ร่วมกับการดำเนินการในเบื้องหลังไม่ได้ และจะป้องกันไม่ให้ใช้ previous_interaction_id ในรอบถัดๆ ไป

สำหรับโปรเจ็กต์ระดับแบบชำระเงิน คุณสามารถกำหนดค่าระยะเวลาเก็บรักษาใน AI Studio เพื่อทำเครื่องหมายบันทึกสำหรับการลบออกจากที่เก็บข้อมูลของโปรเจ็กต์โดยอัตโนมัติหลังจาก 7, 14, 28 หรือ 55 วัน ระยะเวลาเก็บรักษาที่สั้นลง อาจส่งผลต่อการดึงข้อมูลการสนทนาที่ผ่านมา

คุณลบการโต้ตอบที่จัดเก็บไว้ได้ทุกเมื่อโดยใช้วิธี delete แบบเป็นโปรแกรม ซึ่งต้องใช้รหัสการโต้ตอบ นอกจากนี้ คุณยังดูและจัดการบันทึกการโต้ตอบที่จัดเก็บไว้ รวมถึงการลบออกจากที่เก็บข้อมูลของโปรเจ็กต์ได้ใน AI Studio

หลังจากระยะเวลาการเก็บรักษาหมดอายุแล้ว ระบบจะลบข้อมูลของคุณโดยอัตโนมัติ

ระบบจะประมวลผลออบเจ็กต์การโต้ตอบตามข้อกำหนด

ดูการโต้ตอบใน AI Studio

API จะจัดเก็บคำขอ Interactions API ที่ดำเนินการด้วย store=true สำหรับ โปรเจ็กต์ในระดับแบบชำระเงิน คุณดูได้โดยตรงจาก หน้าบันทึกใน Google AI Studio ดูข้อมูลเพิ่มเติมได้ที่คู่มือบันทึก

แนวทางปฏิบัติแนะนำ

• อัตราการพบแคช: การแคชโดยนัยรองรับทั้งในโหมดเก็บสถานะและ ไม่เก็บสถานะ (ดูคู่มือเริ่มใช้งานฉบับย่อ) การใช้ previous_interaction_id (มีสถานะ) เพื่อสนทนาต่อช่วยให้ระบบใช้แคชโดยนัยสำหรับประวัติการสนทนาได้ง่ายขึ้น ซึ่งจะช่วยปรับปรุงประสิทธิภาพและลดต้นทุน
• การโต้ตอบแบบผสม: คุณสามารถผสมผสานการโต้ตอบของตัวแทนและโมเดลในการสนทนาได้อย่างยืดหยุ่น เช่น คุณสามารถใช้เอเจนต์เฉพาะทาง เช่น เอเจนต์ Deep Research เพื่อรวบรวมข้อมูลเริ่มต้น จากนั้นใช้โมเดล Gemini มาตรฐานสำหรับงานติดตามผล เช่น การสรุปหรือการจัดรูปแบบใหม่ โดยเชื่อมโยงขั้นตอนเหล่านี้กับ previous_interaction_id

โมเดลและเอเจนต์ที่รองรับ

SDK

คุณสามารถใช้ Google GenAI SDK เวอร์ชันล่าสุดเพื่อเข้าถึง Interactions API

• ใน Python นี่คือแพ็กเกจ google-genai ตั้งแต่เวอร์ชัน 2.3.0 เป็นต้นไป
• ใน JavaScript จะเป็นแพ็กเกจ @google/genai ตั้งแต่เวอร์ชัน 2.3.0 เป็นต้นไป
• ใน Go คือแพ็กเกจ google.golang.org/genai
• ใน Java นี่คือแพ็กเกจ com.google.genai:google-genai

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีติดตั้ง SDK ได้ในหน้าคลัง

ข้อจำกัด

• MCP ระยะไกล: Gemini 3 ไม่รองรับ MCP ระยะไกล โดยจะพร้อมใช้งานเร็วๆ นี้
• ความเข้ากันได้ของโมเดลแบบการสนทนาไปมา: เมื่อใช้โมเดลที่แตกต่างกันในการสนทนา (ไม่ว่าจะเป็นแบบเก็บสถานะหรือไม่เก็บสถานะ) โมเดลถัดไปต้องรองรับรูปแบบเอาต์พุตของโมเดลก่อนหน้าเป็นอินพุต เช่น หากคุณ สร้างรูปภาพโดยใช้ gemini-3.1-flash-image คุณจะสนทนาต่อกับโมเดลที่ไม่รับอินพุตรูปภาพไม่ได้ (เช่น โมเดลข้อความเท่านั้นหรือโมเดลสร้างเพลงอย่าง Lyria)

API ของ generateContent รองรับฟีเจอร์ต่อไปนี้ แต่ยังไม่พร้อมใช้งานใน Interactions API

• Batch API
• การเรียกฟังก์ชันอัตโนมัติ (Python)
• การแคชอย่างชัดเจน: โปรดทราบว่าการแคชโดยนัยฝั่งเซิร์ฟเวอร์พร้อมใช้งานใน Interactions API ผ่าน previous_interaction_id
• การตั้งค่าความปลอดภัย: Interactions API ไม่รองรับการตั้งค่าความปลอดภัยที่กำหนดเอง

ความคิดเห็น

ความคิดเห็นของคุณมีความสําคัญอย่างยิ่งต่อการพัฒนา Interactions API แชร์ความคิดเห็น รายงานข้อบกพร่อง หรือขอฟีเจอร์ได้ในฟอรัมชุมชนนักพัฒนาแอป Google AI

ขั้นตอนถัดไป

• ลองใช้สมุดบันทึกการเริ่มต้นใช้งาน Interactions API อย่างรวดเร็ว
• ดูข้อมูลเพิ่มเติมเกี่ยวกับเอเจนต์ Deep Research ของ Gemini