Hướng dẫn chuyển đổi API Gemini 3.7 Flash sang 3.8 Flash

Google đã ra mắt Gemini 3.8 Flash vào ngày 2 tháng 9 năm 2026, ba tuần sau 3.7 Flash, với cùng giá giới thiệu và tốc độ tương đương. Mã nhận dạng mô hình là gemini-3.8-flash, không có hậu tố bản xem trước, và mô tả mô hình cho biết nó “dựa trên Gemini 3.7 Flash”. Do đó, hầu hết các nhóm mong đợi một thay đổi đơn giản. Đối với một lời nhắc trò chuyện thông thường, đúng là như vậy. Nhưng đối với bất cứ điều gì thiết lập các thông số tư duy, điều chỉnh lấy mẫu hoặc chạy vòng lặp công cụ, có chín điều cần kiểm tra, và hai trong số đó trả về lỗi mà 3.7 Flash chưa bao giờ gặp phải.

Hướng dẫn này là một danh sách kiểm tra, được xây dựng từ trang Có gì mới trong Gemini 3.8 Flash của Google và hướng dẫn dành cho nhà phát triển Gemini 3. Mỗi mục có một đoạn mã "trước" và "sau" cho cả hai hình thức API: API Tương tác (Interactions API), mà Google hiện coi là đường dẫn chính, và điểm cuối generateContent cũ mà hầu hết mã 3.7 Flash vẫn sử dụng. Mọi đoạn mã đều có thể được dán vào Apidog và gửi đến điểm cuối trực tiếp trước khi triển khai vào sản xuất. Nếu bạn muốn tổng quan về mô hình trước tiên, hãy bắt đầu với Gemini 3.8 Flash là gì.

Một lưu ý chung trước danh sách. Google cho biết 3.8 Flash được thiết kế để "làm việc chăm chỉ hơn": đối với các tác vụ phức tạp, nó thực hiện các bước suy luận nhỏ hơn, xác minh công việc của mình và gọi các công cụ lặp đi lặp lại. Đó là nguồn gốc của hầu hết các cải tiến và cũng là lý do tại sao một quá trình di chuyển cần phải xem xét lại ngân sách token, chứ không chỉ là sự khác biệt về cấu hình.

button

Những thay đổi và không thay đổi

Khu vực	3.7 Flash	3.8 Flash
ID Mô hình	`gemini-3.7-flash`	`gemini-3.8-flash`
Ngữ cảnh / đầu ra	1,048,576 / 65,536	Tương tự
Giá (giới thiệu đến 31/12/2026)	$0.75 / $3.75 trên 1M	Tương tự, sau đó $1.50 / $7.50 cho cả hai từ 01/01/2027
Mức độ tư duy	thấp, trung bình, cao	Tương tự; `minimal` trả về lỗi xác thực; mặc định là `medium`
Token mỗi tác vụ	cơ bản	+30% token đầu ra trung bình (Artificial Analysis)
Kết quả hàm	`call_id` + `name`	Cả hai đều bắt buộc, được thực thi
Trạng thái hỗ trợ	"vẫn được hỗ trợ đầy đủ", không có ngày ngừng hỗ trợ	Hiện tại

Nguồn thông tin về giá: Trang Giá API Gemini của Google, nơi các dòng 3.6, 3.7 và 3.8 Flash là giống hệt nhau.

Bước 0: Quyết định có nên di chuyển hay không

Không có gì bắt buộc phải di chuyển. Bài đăng ra mắt của Google cho biết "Gemini 3.7 Flash vẫn được hỗ trợ đầy đủ", và không có ngày ngừng hỗ trợ nào được công bố. Giá mỗi token không thay đổi, vì vậy sự khác biệt về chi phí duy nhất là việc sử dụng. Artificial Analysis đã đo lường Gemini 3.8 Flash ở mức độ tư duy cao sử dụng khoảng 48 nghìn token đầu ra mỗi tác vụ trên chỉ số của họ, nhiều hơn 30% so với 3.7 Flash, điều này làm tăng chi phí mỗi tác vụ từ 0,40 đô la lên 0,58 đô la với cùng mức giá. Điểm chỉ số của họ tăng từ 56 lên 59, và độ chính xác sử dụng công cụ trên τ³-Banking tăng 12 điểm lên 45%.

Vì vậy, sự đánh đổi là khả năng cao hơn trên mỗi tác vụ với nhiều token hơn trên mỗi tác vụ. Nếu khối lượng công việc của bạn ngắn, nhạy cảm về độ trễ, hoặc đã vượt qua các bài đánh giá trên 3.7 Flash, bạn có thể giữ nguyên. So sánh đầy đủ 3.8 Flash vs 3.7 Flash có một ma trận quyết định theo khối lượng công việc. Nếu bạn đang di chuyển, hãy tiếp tục đọc.

Bước 1: Thay đổi ID mô hình ở cả hai định dạng

API Tương tác (Interactions API) (API chính của Google cho Gemini 3.x):

{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}

API generateContent cũ (vẫn được hỗ trợ, không có ngày ngừng hoạt động):

POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent

Python SDK, cả hai đường dẫn:

client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))

Nếu bạn chưa bao giờ sử dụng API Tương tác (Interactions API), hướng dẫn API 3.8 Flash bao gồm cả hai hình thức từ đầu đến cuối; hướng dẫn chi tiết API 3.7 Flash cũ hơn chỉ bao gồm generateContent, đó là lý do tại sao hướng dẫn này hiển thị cả hai.

Danh sách kiểm tra di chuyển chín mục

Thực hiện theo thứ tự này. Các mục từ 1 đến 4 là những thay đổi cấu hình sẽ xuất hiện ngay lập tức. Các mục 5 và 6 ảnh hưởng đến vòng lặp công cụ và trạng thái nhiều lượt. Các mục từ 7 đến 9 là những thay đổi về lập kế hoạch và phương tiện mà bạn sẽ chỉ phát hiện được khi thử nghiệm.

1. Ánh xạ `thinking_level: "minimal"` sang `"low"`

Đây là mục gây lỗi đầu tiên. 3.8 Flash chấp nhận các giá trị low, medium và high. Gửi minimal sẽ trả về lỗi xác thực. Mặc định khi bạn không gửi gì là medium. Gemini 3 Pro mặc định là high, vì vậy đừng sao chép cấu hình Pro và cho rằng nó sẽ khớp.

Trước (3.7 Flash, Interactions):

{"generation_config": {"thinking_level": "minimal"}}

Sau (3.8 Flash):

{"generation_config": {"thinking_level": "low"}}

Định dạng cũ, sau:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Tài liệu về tư duy của Google mô tả low là cài đặt độ trễ và medium là mặc định cho mã phức tạp và công việc tác tử. Mức độ nên sử dụng cho mỗi tuyến là một bài viết riêng; đối với mục đích di chuyển, low là sự thay thế trực tiếp cho minimal.

2. Xóa `temperature`, `top_p`, và `top_k`

Hướng dẫn của Google cho mọi mô hình Gemini 3 là giữ nhiệt độ ở mức mặc định là 1.0. Việc giảm nhiệt độ "có thể gây ra vòng lặp hoặc giảm hiệu suất". Nhiều cấu hình 3.7 Flash vẫn giữ temperature: 0.2 từ các thế hệ trước. Hãy xóa các khóa lấy mẫu thay vì thiết lập chúng.

{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}

Nếu bạn đã sử dụng nhiệt độ thấp để nhận được JSON có thể lặp lại, hãy sử dụng đầu ra có cấu trúc thay thế. Chúng được hỗ trợ trên 3.8 Flash và cung cấp cho bạn phản hồi có hình dạng schema mà không cần chạm vào lấy mẫu.

3. Thay thế `thinking_budget` bằng `thinking_level`

thinking_budget là một giới hạn token dạng số nguyên. thinking_level là một chuỗi enum. Không có ánh xạ số học giữa chúng, vì vậy hãy chọn mức độ theo mục đích: các tuyến đường cần độ trễ thấp sẽ nhận low, các tuyến đường mặc định sẽ nhận medium, các tuyến đường đa bước khó nhất sẽ nhận high.

{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Token tư duy vẫn được tính phí như token đầu ra và được báo cáo trong usageMetadata.thoughtsTokenCount, vì vậy việc kiểm soát chi phí chuyển từ giới hạn cứng sang lựa chọn mức độ cộng với một xác nhận trong các bài kiểm tra của bạn (xem phần hồi quy bên dưới).

4. Xóa `candidate_count`

Gemini 3 và các phiên bản sau này không hỗ trợ nhiều ứng viên. Hãy loại bỏ khóa này và loại bỏ bất kỳ mã nào đã lập chỉ mục candidates[1] trở đi.

{"generationConfig": {"candidateCount": 2}}

{"generationConfig": {}}

Nếu bạn đã lấy mẫu một vài ứng viên để chọn ra ứng viên tốt nhất, thì giải pháp thay thế trên 3.8 Flash là một mức độ tư duy cao hơn, thực hiện việc xác minh trong một phản hồi duy nhất.

5. Đặt `call_id` và `name` vào mỗi kết quả hàm

Đây là điểm phá vỡ cứng thứ hai. Trên 3.8 Flash, mọi kết quả hàm bạn gửi lại phải chứa cả id của lời gọi và name của hàm. Hướng dẫn Gemini 3 của Google nói rằng "đảm bảo tất cả các đối tượng FunctionResponse bao gồm call_id và name". Mã chỉ phản hồi tên sẽ thất bại trong lượt kết quả công cụ.

API Tương tác (Interactions API), sau:

{
  "previous_interaction_id": "<id from the function_call step>",
  "input": [{
    "type": "function_result",
    "name": "get_weather",
    "call_id": "<id from the function_call step>",
    "result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
  }]
}

Bước function_call của mô hình cung cấp cho bạn id, name và arguments; hãy sao chép hai mục đầu tiên trở lại. Trong định dạng cũ, phần functionResponse mang cùng giá trị trong một trường có tên id (khớp với id trong phần functionCall của mô hình) cùng với name và response. Tài liệu tham khảo gọi hàm của Google có các ví dụ chính tắc, và hướng dẫn gọi hàm 3.8 Flash giải thích toàn bộ vòng lặp hai lượt, bao gồm lý do tại sao 3.8 Flash gọi công cụ nhiều lần hơn trên mỗi tác vụ so với 3.7 Flash.

6. Truyền lại các chữ ký tư duy chính xác như đã nhận được

Các mô hình Gemini 3 đính kèm chữ ký tư duy vào các phần phản hồi. Khi bạn tự xây dựng lượt tiếp theo, hãy trả về mọi phần không thay đổi, bao gồm cả chữ ký, cho tất cả các loại phần, không chỉ văn bản. Việc loại bỏ hoặc tái tuần tự hóa chúng sẽ làm giảm tính liên tục của mô hình ở bước tiếp theo.

API Tương tác (Interactions API) loại bỏ công việc này khi bạn để máy chủ duy trì trạng thái: truyền previous_interaction_id và Google sẽ giữ lịch sử. Nếu bạn đặt store: false cho một cuộc gọi không trạng thái, bạn lại tự sở hữu lịch sử và phải tự gửi lại các khối tư duy và chữ ký. Trong `generateContent` cũ, bạn luôn sở hữu lịch sử, vì vậy hãy kiểm tra bất kỳ mã nào xây dựng lại `contents` từ một bản sao đã cắt bớt của phản hồi cuối cùng.

7. Dự toán nhiều token hơn cho mỗi tuyến

Mục này không có lỗi để phát hiện, đó là lý do tại sao nó bị bỏ qua. Con số +30% token đầu ra từ Artificial Analysis là mức trung bình trên chỉ số của họ ở mức độ tư duy cao. Cách diễn đạt của Google là mô hình "có thể sử dụng nhiều token hơn cho các tác vụ phức tạp và chạy dài hơn, theo thiết kế" và việc sử dụng tăng lên "đặc biệt ở các mức độ nỗ lực cao hơn".

Các điểm cuối nhạy cảm về độ trễ: low. AA đo được 0,8 phút mỗi tác vụ ở mức thấp so với 2,5 phút ở mức cao, và 0,24 đô la mỗi tác vụ so với 0,58 đô la.
Các tuyến mặc định: medium, khoảng 0,41 đô la mỗi tác vụ trên cùng chỉ số.
Vòng lặp tác tử: mong đợi nhiều lượt gọi công cụ hơn trên mỗi tác vụ, vì vậy hãy giới hạn vòng lặp bằng số lượt, chứ không chỉ bằng token.

Cũng cần xem xét lại giới hạn 65.536 token đầu ra. Một lời nhắc 3.7 Flash đã trả về 40k token cùng với tư duy giờ đây có thể chạy gần giới hạn hơn. Nếu bạn đang mô hình hóa hóa đơn, phân tích giá 3.8 Flash đưa ra các con số mỗi tác vụ ở cả ba cấp độ.

8. Thử nghiệm `media_resolution_high` trên tệp PDF so với video

3.8 Flash chấp nhận đầu vào là văn bản, hình ảnh, video, âm thanh và PDF. Cài đặt độ phân giải phương tiện thay đổi số lượng token mà mỗi đầu vào phương tiện tiêu thụ, và chi phí khác nhau tùy theo loại phương tiện, vì vậy cùng một cài đặt có thể rẻ trên một trang PDF nhưng có thể đắt trên một video dài. Đừng chuyển cài đặt độ phân giải cao toàn cầu từ 3.7 Flash sang mà không đo lường. Hãy gửi một tệp PDF đại diện và một video đại diện ở mỗi độ phân giải và so sánh usageMetadata.promptTokenCount giữa chúng.

9. Bỏ qua mọi lệnh gọi phân đoạn hình ảnh

Phân đoạn hình ảnh không được hỗ trợ trên các mô hình Gemini 3. Nếu một quy trình thời 3.7 Flash vẫn định tuyến phân đoạn thông qua một mô hình Gemini cũ hơn, thì đường dẫn đó tách biệt với việc di chuyển này; nếu một lời nhắc yêu cầu 3.8 Flash tạo mặt nạ phân đoạn, hãy mong đợi nó sẽ thất bại thay vì trả về đầu ra có thể sử dụng được. Tạo hình ảnh, tạo âm thanh và Live API cũng không được hỗ trợ trên 3.8 Flash, theo trang mô hình.

Xây dựng kế hoạch hồi quy trong Apidog

Một quá trình di chuyển với hai thay đổi gây lỗi và sự dịch chuyển trong việc sử dụng token cần một so sánh có thể lặp lại, không phải một lệnh curl một lần. Đây là thiết lập chúng tôi sử dụng trong Apidog, hoạt động hiệu quả vì Apidog là một ứng dụng khách API và công cụ chạy thử nghiệm: nó gửi các yêu cầu, kiểm tra phản hồi và lên lịch chạy. Nó không chạy mô hình.

Môi trường và biến. Tạo một môi trường Gemini với GEMINI_API_KEY được lưu trữ dưới dạng biến bí mật và một biến MODEL. Sử dụng {{MODEL}} trong URL của yêu cầu generateContent và trong trường model của yêu cầu Interactions, để cùng một yêu cầu đã lưu có thể chạy trên một trong hai mô hình.

Lời nhắc vàng (Golden prompts). Lưu 10 đến 20 lời nhắc đại diện cho các tuyến đường thực tế của bạn: một lượt trò chuyện ngắn, một trích xuất đầu ra có cấu trúc, một lệnh gọi hàm hai lượt với một công cụ giả lập, một đầu vào PDF và một đầu vào video. Mỗi lời nhắc là một yêu cầu trong một kịch bản kiểm thử.

Xác nhận (Assertions). Thêm ba xác nhận cho mỗi yêu cầu:

Trạng thái là 200, và nội dung phản hồi khớp với một schema JSON. Đối với các tuyến đầu ra có cấu trúc, hãy xác nhận trên các trường bạn phân tích cú pháp ở phía sau.
usageMetadata.thoughtsTokenCount duy trì dưới mức trần bạn đặt cho mỗi tuyến (ví dụ, 8.000 trên một tuyến low). Đây là bảo vệ để phát hiện một cấu hình đã âm thầm quay về medium.
usageMetadata.totalTokenCount duy trì dưới ngân sách của tuyến từ mục 7.

Song song. Sao chép kịch bản, đặt MODEL thành gemini-3.7-flash trong một bản và gemini-3.8-flash trong bản còn lại, và chạy cả hai. Báo cáo kiểm thử của Apidog hiển thị trạng thái đạt/không đạt cho mỗi xác nhận và nội dung phản hồi, vì vậy sự khác biệt token trên mỗi lời nhắc có thể nhìn thấy trong một chế độ xem thay vì phải tái tạo từ nhật ký. Đối với kịch bản gọi hàm, hãy thêm một xác nhận rằng call_id bạn gửi lại bằng với id từ function_call của bước trước.

Lên lịch. Biến kịch bản 3.8 Flash thành một lần chạy theo lịch trình để các giới hạn token được kiểm tra hàng ngày trong suốt thời gian triển khai. Hướng dẫn kiểm thử API theo lịch trình bao gồm việc thiết lập. Nếu bạn muốn làm theo trong ứng dụng, Tải xuống Apidog và nhập các đoạn curl ở trên.

Khôi phục: giữ 3.7 Flash phía sau một cờ cấu hình

Vì 3.7 Flash vẫn được hỗ trợ đầy đủ và có cùng mức giá với 3.8 Flash, việc khôi phục sẽ rẻ: hãy giữ ID mô hình trong cấu hình thay vì trong mã.

{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}

Ba quy tắc giúp cờ an toàn:

Giữ nguyên định dạng yêu cầu đã di chuyển trên cả hai mô hình. Các mục từ 1 đến 6 (không có minimal, không có khóa lấy mẫu, thinking_level chứ không phải thinking_budget, không có candidate_count, call_id + name, giữ nguyên chữ ký) đều hợp lệ trên 3.7 Flash, vì vậy một cờ được lật không bao giờ cần đường dẫn mã thứ hai.
Triển khai theo từng tuyến. Lật các tuyến có độ trễ cấp low trước tiên, vì sự khác biệt về token của chúng là nhỏ nhất; lật các vòng lặp tác tử cuối cùng, sau khi kịch bản song song đã vượt qua trong vài ngày.
Theo dõi token, không chỉ lỗi. Một tác nhân kích hoạt khôi phục trên 3.8 Flash có nhiều khả năng là sự suy giảm về chi phí hoặc độ trễ hơn là lỗi 4xx, vì vậy hãy tích hợp các xác nhận giới hạn token vào hệ thống cảnh báo của bạn.

Câu hỏi thường gặp

Gemini 3.8 Flash có tốn kém hơn 3.7 Flash không? Không tính theo mỗi token. Cả hai đều có giá 0,75 đô la đầu vào / 3,75 đô la đầu ra trên 1 triệu token cho đến ngày 31 tháng 12 năm 2026, và cả hai đều tăng lên 1,50 đô la / 7,50 đô la vào ngày 1 tháng 1 năm 2027. Tính theo mỗi tác vụ, 3.8 Flash sử dụng nhiều token hơn theo thiết kế; Artificial Analysis đã đo được khoảng 30% token đầu ra nhiều hơn trên chỉ số của họ ở mức độ tư duy cao.

Điều gì xảy ra nếu tôi để nguyên thinking_level: "minimal"? Yêu cầu sẽ thất bại với lỗi xác thực trên 3.8 Flash. Hãy thay thế nó bằng low. Hướng dẫn về các mức độ tư duy giải thích từng mức độ còn lại làm gì và cách đo lường sự khác biệt.

Tôi có phải chuyển sang Interactions API để sử dụng 3.8 Flash không? Không. generateContent được mô tả là cũ nhưng vẫn được hỗ trợ đầy đủ mà không có ngày ngừng hoạt động, và 3.8 Flash hoạt động trên đó. Interactions API bổ sung trạng thái hội thoại phía máy chủ thông qua previous_interaction_id, loại bỏ việc quản lý chữ ký tư duy ở mục 6.

Liệu 3.7 Flash có bị ngừng hỗ trợ không? Google cho biết nó "vẫn được hỗ trợ đầy đủ" và chưa công bố ngày ngừng hỗ trợ. Đó là điều làm cho việc khôi phục bằng cờ cấu hình trở nên khả thi.

Tôi có thể giữ nguyên cài đặt nhiệt độ (temperature) mà tôi đã điều chỉnh cho 3.7 Flash không? Lời khuyên của Google cho tất cả các mô hình Gemini 3 là để nhiệt độ ở mức 1.0. Nếu bạn đã từng ghi đè nó trên 3.7 Flash, thì đây là lúc để loại bỏ nó và kiểm tra các đánh giá của bạn; đầu ra có cấu trúc là cách được hỗ trợ để có được các hình dạng xác định.

Triển khai theo từng giai đoạn

Bản thân quá trình di chuyển là nhỏ: một thay đổi ID, bốn lần xóa hoặc đổi tên cấu hình, hai trường vòng lặp công cụ và một kiểm toán chữ ký. Phần tốn thời gian là chứng minh ngân sách token được giữ vững cho mỗi tuyến, và đó là một vấn đề kiểm thử. Lưu các lời nhắc vàng, xác nhận schema và giới hạn token, chạy 3.7 và 3.8 Flash song song cho đến khi các con số ổn định, sau đó lật cờ từng tuyến một. Nếu một tuyến bị hồi quy, cờ sẽ đưa nó trở lại 3.7 Flash mà không cần thay đổi mã, và bạn vẫn giữ các tuyến đã cải thiện.