Interactions API

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

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

  • Giao diện chung cho tất 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 tạo văn bản một lượt, hiểu nhiều phương thức, đầu ra có cấu trúc, điều phối công cụ và quy trình công việc theo 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 các mô hình Gemini tiêu chuẩn cũng như các tác nhân chuyên biệt trực tiếp (chẳng hạn như Deep Research và các tác nhân được quản lý tuỳ chỉnh).
  • Các tính năng mới ngay khi dùng: 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 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ệ truy cập bộ nhớ đệm 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 không bắt buộc ở phía máy chủ cho phép lưu vào bộ nhớ đệm theo bối cảnh hiệu quả hơn trên các lượt, giúp giảm chi phí mã thông báo.
  • Nơi ra mắt các tính năng mới: Trong tương lai, tất cả các mô hình mới, tính năng nhiều phương thức, công cụ và tính năng theo tác nhân 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 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 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 chuyển 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 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ý tương tác dưới dạng 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ý cuộc 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 là theo 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. 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ý cuộc 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ả đố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 ở chế độ nền (sử dụng background=true) và mục đích quan sát.

  • 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, bạn có thể đặt store=false trong yêu cầu. 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, xin lưu ý rằng store=false không tương thích với việc 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 ở Cấp trả phí, bạn có thể định cấu hình khoảng thời gian giữ lại 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 giữ lại 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 lượt tương tác đã lưu trữ bất cứ lúc nào bằng phương thức delete theo lập trình, phương thức này yêu cầu mã lượt tương tác. Bạn cũng có thể xem và quản lý nhật ký các lượt 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 thời gian giữ lại, 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 các đ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 trả phí. Bạn có thể xem trực tiếp các yêu cầu này từ 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ệ truy cập bộ nhớ đệm: Tính năng lưu vào bộ nhớ đệm ngầm đượ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ý cuộc 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 Google GenAI để 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.
  • 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 bạn tạo một 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).

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