Interactions API

Interactions API là giao diện mới của chúng tôi và là cách đơn giản nhất để xây dựng bằng các mô hình và tác nhân Gemini. Kể từ tháng 6 năm 2026, API này sẽ được cung cấp rộng rãi và là giao diện được đề xuất cho tất cả các dự án mới.

Mặc dù hiện được coi là API cũ, nhưng API generateContent vẫn được hỗ trợ đầy đủ.

Tại sao bạn nên sử dụng Interactions API?

  • Các tính năng mới có sẵn: Trạng thái cuộc trò chuyện không bắt buộc ở phía máy chủ bằng cách sử dụng previous_interaction_id, các bước thực thi có thể quan sát được để gỡ lỗi và kết xuất giao diện người dùng, cũng như thực thi ở chế độ nền cho các tác vụ chạy trong thời gian dài bằng cách sử dụng background=true.
  • Chi phí thấp hơn với tỷ lệ kết quả tìm kiếm trong bộ nhớ cache cao hơn: Tính năng quản lý trạng thái ở phía máy chủ giúp bộ nhớ đệm theo bối cảnh hiệu quả hơn trên các lượt, giảm chi phí mã thông báo cho các cuộc trò chuyện nhiều lượt.
  • Được xây dựng cho các mô hình và tác nhân tiên tiến: Được xây dựng có mục đích cho các mô hình tư duy, sử dụng công cụ nhiều bước và các quy trình suy luận phức tạp – đơn giản hoá quy trình xây dựng, gỡ lỗi và điều phối các ứng dụng có tích hợp tác nhân.
  • Một API duy nhất cho các mô hình và tác nhân: Một giao diện hợp nhất để gọi trực tiếp các mô hình và tác nhân Gemini, chẳng hạn như Deep Research và các tác nhân được quản lý tuỳ chỉnh – không cần tìm hiểu các điểm cuối hoặc mẫu riêng biệt.
  • Nơi ra mắt các tính năng mới: Trong tương lai, các mô hình và khả năng mới ngoài dòng sản phẩm chính, cùng với các công cụ và khả năng của tác nhân AI mới, sẽ ra mắt trên Interactions API.

Theo mặc định, Interactions API sẽ lưu trữ các yêu cầu để bạn có thể tận dụng các tính năng quản lý trạng thái ở phía máy chủ bằng cách sử dụng previous_interaction_id. Bạn có thể chọn hành vi không trạng thái bằng cách đặt store=false. Hãy xem phần lưu giữ dữ liệu để biết thông tin chi tiết.

Bắt đầu

Hướng dẫn về tính năng

Khám phá các tính năng cụ thể của Interactions API thông qua các hướng dẫn này. Bạn có thể sử dụng nút bật/tắt trên các trang này để chuyển đổi giữa generateContent và Interactions API:

Cách thức hoạt động của Interactions API

Interactions API tập trung vào một tài nguyên cốt lõi: Interaction. Interaction đại diện cho một lượt hoàn chỉnh trong một cuộc trò chuyện hoặc tác vụ. Đây là bản ghi phiên, chứa toàn bộ nhật ký của một lượt tương tác dưới dạng một chuỗi các bước thực thi theo trình tự thời gian. Các bước này bao gồm ý tưởng của mô hình, lệnh gọi và kết quả của công cụ ở phía máy chủ hoặc phía máy khách (chẳng hạn như function_call và function_result) và model_output cuối cùng. Tài nguyên được lưu trữ (truy xuất thông qua interactions.get) cũng bao gồm các bước user_input cho toàn bộ bối cảnh, mặc dù phản hồi interactions.create chỉ trả về các bước do mô hình tạo.

Khi bạn gọi interactions.create, bạn đang tạo một tài nguyên Interaction mới.

Quản lý trạng thái ở phía máy chủ

Bạn có thể sử dụng id của một lượt tương tác đã hoàn tất trong một lệnh gọi tiếp theo bằng cách sử dụng previous_interaction_id tham số để tiếp tục cuộc trò chuyện. Máy chủ sử dụng mã nhận dạng này để truy xuất nhật ký trò chuyện, giúp bạn không phải gửi lại toàn bộ nhật ký trò chuyện.

Tham số previous_interaction_id chỉ giữ lại nhật ký cuộc trò chuyện (dữ liệu đầu vào và đầu ra) bằng cách sử dụng previous_interaction_id. Các tham số khác có phạm vi tương tác và chỉ áp dụng cho lượt tương tác cụ thể mà bạn hiện đang tạo:

  • tools
  • system_instruction
  • generation_config (bao gồm thinking_level, temperature, v.v.)

Điều này có nghĩa là bạn phải chỉ định lại các tham số này trong mỗi lượt tương tác mới nếu muốn áp dụng các tham số đó. Bạn có thể chọn quản lý trạng thái ở phía máy chủ; bạn cũng có thể hoạt động ở chế độ không trạng thái bằng cách gửi toàn bộ nhật ký trò chuyện trong mỗi yêu cầu.

Lưu trữ và lưu giữ dữ liệu

Theo mặc định, API sẽ lưu trữ tất cả các đối tượng Tương tác (store=true) để đơn giản hoá việc sử dụng các tính năng quản lý state ở phía máy chủ (với previous_interaction_id), thực thi ở chế độ nền (sử dụng background=true) và mục đích khả năng ghi nhận.

  • Cấp trả phí: Hệ thống giữ lại các lượt tương tác trong 55 ngày.
  • Cấp miễn phí: Hệ thống giữ lại các lượt tương tác trong 1 ngày.

Nếu không muốn điều này, bạn có thể đặt store=false trong yêu cầu của mình. Chế độ kiểm soát này tách biệt với tính năng quản lý trạng thái; bạn có thể chọn không lưu trữ cho bất kỳ lượt tương tác nào. Tuy nhiên, hãy lưu ý rằng store=false không tương thích với background=true và ngăn việc sử dụng previous_interaction_id cho các lượt tiếp theo.

Bạn có thể xoá các lượt tương tác đã lưu trữ bất cứ lúc nào bằng phương thức xoá có trong Tài liệu tham khảo API. Bạn chỉ có thể xoá các lượt tương tác nếu biết mã lượt tương tác.

Sau khi hết khoảng thời gian lưu giữ, dữ liệu của bạn sẽ tự động bị xoá.

Hệ thống xử lý các đối tượng Tương tác theo các điều khoản.

Các phương pháp hay nhất

  • Tỷ lệ truy cập bộ nhớ đệm: Việc sử dụng previous_interaction_id để tiếp tục cuộc trò chuyện cho phép hệ thống dễ dàng sử dụng bộ nhớ đệm ngầm ẩn cho nhật ký trò chuyện, giúp cải thiện hiệu suất và giảm chi phí.
  • Kết hợp các lượt tương tác: Bạn có thể linh hoạt kết hợp các lượt tương tác của Tác nhân và Mô hình trong một cuộc trò chuyện. Ví dụ: bạn có thể sử dụng một tác nhân chuyên biệt, chẳng hạn như tác nhân Deep Research, để thu thập dữ liệu ban đầu, sau đó sử dụng mô hình Gemini tiêu chuẩn cho các tác vụ tiếp theo như tóm tắt hoặc định dạng lại, liên kết các bước này với previous_interaction_id.

Các mô hình và tác nhân được hỗ trợ

Tên mô hình Loại Mã kiểu máy
Gemini 3.5 Flash Mô hình gemini-3.5-flash
Bản xem trước Gemini 3.1 Pro Mô hình gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite Mô hình gemini-3.1-flash-lite
Bản xem trước Gemini 3 Flash Mô hình gemini-3-flash-preview
Gemini 2.5 Pro Mô hình gemini-2.5-pro
Gemini 2.5 Flash Mô hình gemini-2.5-flash
Gemini 2.5 Flash-lite Mô hình gemini-2.5-flash-lite
Hình ảnh Gemini 3 Pro Mô hình gemini-3-pro-image
Hình ảnh Gemini 3.1 Flash Mô hình gemini-3.1-flash-image
Bản xem trước Gemini 3.1 Flash TTS Mô hình gemini-3.1-flash-tts-preview
Gemma 4 31B IT Mô hình gemma-4-31b-it
Gemma 4 26B MoE IT Mô hình gemma-4-26b-a4b-it
Bản xem trước Lyria 3 Clip Mô hình lyria-3-clip-preview
Bản xem trước Lyria 3 Pro Mô hình lyria-3-pro-preview
Bản xem trước Deep Research Tác nhân deep-research-preview-04-2026
Bản xem trước Deep Research Tác nhân deep-research-max-preview-04-2026
Bản xem trước Antigravity Tác nhân antigravity-preview-05-2026

SDK

Bạn có thể sử dụng phiên bản mới nhất của SDK GenAI của Google để truy cập vào Interactions API.

  • Trên Python, đây là gói google-genai từ phiên bản 2.3.0 trở lên.
  • Trên JavaScript, đây là gói @google/genai từ phiên bản 2.3.0 trở lên.

Bạn có thể tìm hiểu thêm về cách cài đặt SDK trên trang Thư viện.

Các điểm hạn chế

  • MCP từ xa: Gemini 3 không hỗ trợ MCP từ xa, tính năng này sẽ sớm ra mắt.

Các tính năng sau được API generateContent hỗ trợ nhưng chưa có trong Interactions API:

Phản hồi

Ý kiến phản hồi của bạn rất quan trọng đối với việc phát triển Interactions API. Hãy chia sẻ ý kiến, báo cáo lỗi hoặc yêu cầu tính năng trên Diễn đàn cộng đồng nhà phát triển AI của Google.

Bước tiếp theo