Interactions API

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

เหตุใดจึงควรใช้ Interactions API

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

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

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

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

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

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

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

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

เมื่อโทรหา interactions.create คุณจะ สร้างทรัพยากร 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 ใช้ร่วมกับ background=true ไม่ได้ และจะป้องกันไม่ให้ใช้ previous_interaction_id ในรอบถัดไป

คุณลบการโต้ตอบที่จัดเก็บไว้ได้ทุกเมื่อโดยใช้วิธีการลบที่อยู่ในเอกสารอ้างอิง API คุณจะลบการโต้ตอบได้ก็ต่อเมื่อ ทราบรหัสการโต้ตอบ

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

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

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

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

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

ชื่อแบบจำลอง ประเภท รหัสโมเดล
Gemini 3.1 Flash-Lite รุ่น gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite (เวอร์ชันตัวอย่าง) รุ่น gemini-3.1-flash-lite-preview
เวอร์ชันตัวอย่างของ Gemini 3.1 Pro รุ่น gemini-3.1-pro-preview
Gemini 3 Flash (เวอร์ชันตัวอย่าง) รุ่น gemini-3-flash-preview
Gemini 2.5 Pro รุ่น gemini-2.5-pro
Gemini 2.5 Flash รุ่น gemini-2.5-flash
Gemini 2.5 Flash-lite รุ่น gemini-2.5-flash-lite
ตัวอย่างคลิป Lyria 3 รุ่น lyria-3-clip-preview
เวอร์ชันตัวอย่างของ Lyria 3 Pro รุ่น lyria-3-pro-preview
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-pro-preview-12-2025
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-preview-04-2026
Deep Research เวอร์ชันตัวอย่าง Agent deep-research-max-preview-04-2026

SDK

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

  • ใน Python นี่คือแพ็กเกจ google-genai ตั้งแต่เวอร์ชัน 1.55.0 เป็นต้นไป
  • ใน JavaScript นี่คือแพ็กเกจ @google/genai จากเวอร์ชัน 1.33.0 เป็นต้นไป

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

ข้อจำกัด

  • สถานะเบต้า: Interactions API อยู่ในเวอร์ชันเบต้า/เวอร์ชันตัวอย่าง ฟีเจอร์และ สคีมาอาจมีการเปลี่ยนแปลง
  • MCP ระยะไกล: Gemini 3 ไม่รองรับ MCP ระยะไกล โดยจะพร้อมใช้งานเร็วๆ นี้

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

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

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

การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบที่มีอยู่

  • สคีมาขั้นตอน: อาร์เรย์ขั้นตอนใหม่จะแทนที่อาร์เรย์เอาต์พุต ซึ่งจะแสดงไทม์ไลน์ที่มีโครงสร้างของการโต้ตอบแต่ละรอบ

ดูข้อมูลเกี่ยวกับการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นล่าสุดและวิธีย้ายข้อมูลได้ที่คำแนะนำในการย้ายข้อมูลการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่น (พฤษภาคม 2026)

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

สำหรับภาระงานการผลิต คุณควรใช้ generateContent API มาตรฐานต่อไป ซึ่งยังคงเป็นเส้นทางที่แนะนำสำหรับการติดตั้งใช้งานที่เสถียร และเราจะยังคงพัฒนาและดูแลรักษาต่อไป

ความคิดเห็น

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

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