Interactions API

Interactions API là cách tốt nhất để tạo ứng 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à nên dùng cho tất cả các dự án mới. Mặc dù hiện được coi là cũ, nhưng API generateContent ban đầu vẫn được hỗ trợ đầy đủ.

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

  • Giao diện chung cho tất cả các ứng dụng: Được thiết kế làm giao diện tiêu chuẩn cho mọi trường hợp sử dụng, bao gồm cả việc tạo văn bản một lượt, hiểu biết đa phương thức, đầu ra có cấu trúc, điều phối công cụ và quy trình làm việc dựa trên tác nhân.
  • Một API cho các mô hình và tác nhân: Một điểm cuối và mẫu hợp nhất để gọi trực tiếp các mô hình Gemini tiêu chuẩn cũng như các tác nhân chuyên biệt (chẳng hạn như Deep Research và các tác nhân được quản lý tuỳ chỉnh).
  • Các chức năng mới ngay từ đầu: Các tính năng như trạng thái cuộc trò chuyện không bắt buộc phía máy chủ bằng previous_interaction_id, các bước thực thi có thể ghi nhận được để gỡ lỗi và kết xuất giao diện người dùng, cũng như thực thi trong nền cho các tác vụ chạy trong thời gian dài bằng background=true.
  • Giảm chi phí với tỷ lệ kết quả tìm kiếm trong bộ nhớ cache cao hơn: Khi sử dụng các cuộc trò chuyện nhiều lượt, tính năng quản lý trạng thái phía máy chủ không bắt buộc sẽ cho phép lưu vào bộ nhớ đệm ngữ cảnh hiệu quả hơn giữa các lượt, giảm chi phí mã thông báo.
  • Nơi ra mắt các tính năng mới: Từ nay về sau, tất cả các mô hình, tính năng đa phương thức, công cụ và tính năng dựa trên tác nhân mới sẽ ra mắt trên Interactions API.

Theo mặc định, Interactions API 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 giữ lại 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 chức năng cụ thể của Interactions API thông qua những hướng dẫn này. Bạn có thể 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 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 biểu thị một lượt hoàn thành trong cuộc trò chuyện hoặc việc cần làm. Nó hoạt động như một bản ghi phiên, chứa toàn bộ nhật ký 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 suy nghĩ 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 để có ngữ cảnh đầy đủ, mặc dù phản hồi interactions.create chỉ trả về các bước do mô hình tạo.

Khi thực hiện lệnh gọi đến interactions.create, bạn sẽ 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 tham số previous_interaction_id để 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ỉ lưu giữ nhật ký trò chuyện (đầu vào và đầu ra) bằng cách sử dụng previous_interaction_id. Các tham số khác là có phạm vi tương tác và chỉ áp dụng cho hoạt động 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 chúng. Bạn không bắt buộc phải 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à giữ lại 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ý trạng thái phía máy chủ (với previous_interaction_id), thực thi trong nền (bằng background=true) và mục đích quan sát.

  • Gói trả phí: Hệ thống lưu giữ các lượt tương tác trong 55 ngày.
  • Bậc 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 như vậ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 việc quản lý trạng thái; bạn có thể chọn không lưu trữ cho bất kỳ hoạt động tương tác nào. Tuy nhiên, xin lưu ý rằng store=false không tương thích với hoạt động thực thi ở chế độ nền và ngăn việc sử dụng previous_interaction_id cho các lượt tiếp theo.

Đối với các dự án thuộc Cấp có tính phí, bạn có thể định cấu hình khoảng thời gian lưu giữ trong AI Studio để tự động đánh dấu nhật ký cần xoá khỏi bộ nhớ dự án sau 7, 14, 28 hoặc 55 ngày. Thời gian lưu giữ ngắn hơn có thể ảnh hưởng đến việc truy xuất các cuộc trò chuyện trước đây.

Bạn có thể xoá các hoạt động tương tác đã lưu bất cứ lúc nào bằng phương thức delete theo phương thức lập trình. Phương thức này yêu cầu mã nhận dạng hoạt động tương tác. Bạn cũng có thể xem và quản lý nhật ký tương tác đã lưu trữ, bao gồm cả việc xoá khỏi bộ nhớ dự án trong AI Studio.

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

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

Xem các lượt tương tác trong AI Studio

API lưu trữ các yêu cầu Interactions API được thực thi bằng store=true cho các dự án ở Cấp có tính phí. Bạn có thể xem các nhật ký này ngay trên trang Nhật ký trong Google AI Studio. Hãy xem hướng dẫn về Nhật ký để biết thêm thông tin.

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

  • Tỷ lệ kết quả tìm kiếm trong bộ nhớ cache: Tính năng lưu vào bộ nhớ đệm ngầm ẩn được hỗ trợ ở cả chế độ có trạng thái và không trạng thái (xem phần Bắt đầu nhanh). Việc sử dụng previous_interaction_id (có trạng thái) để tiếp tục cuộc trò chuyện cho phép hệ thống dễ dàng sử dụng tính năng lưu vào bộ nhớ đệm ngầm 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 Agent và Model 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ột 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
Gemini 3.1 Pro (Bản xem trước) 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 đoạn video do Lyria 3 tạo Mô hình lyria-3-clip-preview
Lyria 3 Pro (Bản dùng thử) Mô hình lyria-3-pro-preview
Bản dùng thử Deep Research Tác nhân deep-research-preview-04-2026
Bản dùng thử 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 Google GenAI SDK để 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ở đi.
  • 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.
  • Khả năng tương thích của mô hình nhiều lượt: Khi kết hợp nhiều mô hình trong một cuộc trò chuyện (có trạng thái hoặc không trạng thái), các mô hình tiếp theo phải hỗ trợ các phương thức đầu ra của các mô hình trước đó làm dữ liệu đầu vào. Ví dụ: nếu tạo hình ảnh bằng gemini-3.1-flash-image, bạn không thể tiếp tục cuộc trò chuyện đó với một mô hình không chấp nhận dữ liệu đầu vào là hình ảnh (chẳng hạn như mô hình chỉ có văn bản hoặc mô hình tạo nhạc như Lyria).

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

Phản hồi

Ý kiến phản hồi của bạn đóng vai trò quan trọng trong quá trình phát triển Interactions API. 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