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

Checklist di chuyển từ Gemini 3.7 Flash sang Gemini 3.8 Flash

Google ra mắt Gemini 3.8 Flash vào ngày 2 tháng 9 năm 2026, chỉ ba tuần sau Gemini 3.7 Flash, với cùng mức giá giới thiệu và tốc độ tương đương. Model ID là gemini-3.8-flash, không có hậu tố preview, và được mô tả là “dựa trên Gemini 3.7 Flash”. Với lời nhắc trò chuyện thông thường, việc chuyển đổi khá đơn giản. Tuy nhiên, nếu bạn cấu hình mức độ tư duy, điều chỉnh sampling hoặc chạy vòng lặp công cụ, có chín điểm cần kiểm tra—trong đó hai điểm có thể trả về lỗi mà Gemini 3.7 Flash không gặp phải.

Dùng thử Apidog ngay hôm nay

Bài viết này là checklist dựa trên trang Có gì mới trong Gemini 3.8 Flash và tài liệu dành cho nhà phát triển Gemini 3. Mỗi ví dụ có thể được dán vào Apidog để gửi trực tiếp đến API trước khi triển khai production. Nếu cần tổng quan trước, hãy đọc bài Gemini 3.8 Flash là gì.

Gemini 3.8 Flash được thiết kế để “làm việc chăm chỉ hơn”: với tác vụ phức tạp, model thực hiện các bước suy luận nhỏ hơn, tự kiểm tra kết quả và gọi công cụ lặp lại. Đây là nguồn gốc của nhiều cải tiến, nhưng cũng khiến bạn phải xem lại ngân sách token thay vì chỉ đổi model ID.

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

Hạng mục	Gemini 3.7 Flash	Gemini 3.8 Flash
Model ID	gemini-3.7-flash	gemini-3.8-flash
Context / output	1.048.576 / 65.536	Tương tự
Giá đến 31/12/2026	$0,75 / $3,75 trên 1 triệu token	Tương tự
Giá từ 01/01/2027	—	$1,50 / $7,50 cho cả hai model
Mức độ tư duy	low, medium, high	Tương tự; minimal gây lỗi xác thực; mặc định là medium
Token mỗi tác vụ	Cơ bản	Trung bình nhiều hơn 30% token đầu ra (Artificial Analysis)
Kết quả hàm	call_id + name	Cả hai đều bắt buộc và được thực thi
Trạng thái hỗ trợ	Vẫn được hỗ trợ đầy đủ, chưa có ngày ngừng hỗ trợ	Hiện tại

Nguồn giá: Gemini API Pricing, trong đó các dòng Gemini 3.6, 3.7 và 3.8 Flash hiện có cùng mức giá.

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

Bạn không bắt buộc phải di chuyển. Google cho biết Gemini 3.7 Flash “vẫn được hỗ trợ đầy đủ” và chưa công bố ngày ngừng hỗ trợ.

Giá trên mỗi token không đổi; khác biệt về chi phí đến từ mức sử dụng. Artificial Analysis đo được Gemini 3.8 Flash ở mức tư duy cao sử dụng khoảng 48.000 token đầu ra mỗi tác vụ—nhiều hơn 30% so với Gemini 3.7 Flash. Với cùng mức giá, chi phí mỗi tác vụ tăng từ khoảng $0,40 lên $0,58.

Đổi lại:

• Điểm benchmark tăng từ 56 lên 59.
• Độ chính xác sử dụng công cụ trên τ³-Banking tăng 12 điểm, lên 45%.
• Khả năng xử lý mỗi tác vụ cao hơn nhưng cần nhiều token hơn.

Nếu workload ngắn, nhạy cảm với độ trễ hoặc đã đạt yêu cầu trên Gemini 3.7 Flash, bạn có thể giữ nguyên. Xem so sánh đầy đủ Gemini 3.8 Flash và Gemini 3.7 Flash để chọn theo từng workload.

Bước 1: Đổi model ID ở cả hai định dạng API

Interactions API

Đây là đường dẫn chính Google khuyến nghị cho Gemini 3.x:

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

API generateContent

Endpoint cũ vẫn được hỗ trợ và chưa 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

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 chưa dùng Interactions API, hướng dẫn API Gemini 3.8 Flash trình bày cả hai định dạng. Hướng dẫn Gemini 3.7 Flash chủ yếu tập trung vào generateContent.

Checklist di chuyển chín mục

Thực hiện theo thứ tự:

• Mục 1–4: thay đổi cấu hình, thường phát hiện ngay.
• Mục 5–6: ảnh hưởng đến vòng lặp công cụ và trạng thái nhiều lượt.
• Mục 7–9: liên quan đến lập kế hoạch và media, chỉ lộ ra khi kiểm thử thực tế.

1. Đổi thinking_level: "minimal" thành "low"

Đây là lỗi xác thực đầu tiên. Gemini 3.8 Flash chỉ chấp nhận low, medium và high. Khi không truyền giá trị, mặc định là medium.

Gemini 3 Pro mặc định là high, vì vậy không nên sao chép nguyên cấu hình của Pro.

Trước — Interactions API:

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

Sau — Gemini 3.8 Flash:

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

Định dạng cũ:

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

Theo tài liệu về thinking của Google, low phù hợp với endpoint nhạy cảm về độ trễ, còn medium là mặc định cho tác vụ phức tạp và tác vụ agent. Khi di chuyển, low là thay thế trực tiếp cho minimal.

2. Xóa temperature, top_p và top_k

Google khuyến nghị giữ nhiệt độ mặc định 1.0 trên mọi model Gemini 3. Việc giảm nhiệt độ có thể gây vòng lặp hoặc làm giảm hiệu suất. Nhiều cấu hình Gemini 3.7 Flash vẫn giữ các giá trị cũ như temperature: 0.2; hãy xóa chúng thay vì tiếp tục tinh chỉnh sampling.

Trước:

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

Sau:

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

Nếu trước đây bạn dùng nhiệt độ thấp để tạo JSON ổn định, hãy chuyển sang structured output. Tính năng này được hỗ trợ trên Gemini 3.8 Flash và đảm bảo response tuân theo schema mà không cần thay đổi sampling.

3. Thay thinking_budget bằng thinking_level

thinking_budget là giới hạn token dạng số nguyên, còn thinking_level là enum dạng chuỗi. Không có phép ánh xạ số học trực tiếp giữa hai loại.

Chọn mức theo mục đích:

• low: route cần độ trễ thấp.
• medium: route mặc định.
• high: tác vụ đa bước hoặc khó nhất.

Trước:

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

Sau:

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

Token tư duy vẫn được tính như token đầu ra và xuất hiện trong usageMetadata.thoughtsTokenCount. Việc kiểm soát chi phí vì vậy chuyển từ giới hạn cứng sang lựa chọn mức độ kết hợp với các assertion trong bộ kiểm thử hồi quy.

4. Xóa candidate_count

Gemini 3 trở lên không hỗ trợ nhiều candidate. Xóa trường này và mọi logic đọc candidates[1] trở đi.

Trước:

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

Sau:

{"generationConfig": {}}

Nếu trước đây bạn tạo nhiều candidate rồi chọn kết quả tốt nhất, hãy thử dùng mức tư duy high để model tự xác minh trong một response duy nhất.

5. Gửi call_id và name trong mọi function result

Đây là lỗi phá vỡ thứ hai. Trên Gemini 3.8 Flash, mọi function result gửi lại model phải chứa cả ID của lời gọi và tên hàm. Tài liệu Gemini 3 yêu cầu tất cả FunctionResponse bao gồm call_id và name.

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 cung cấp id, name và arguments. Hãy sao chép id và name vào kết quả tương ứng.

Trong định dạng cũ, functionResponse dùng cùng giá trị trong trường id—khớp với id ở functionCall—cùng với name và response. Xem tài liệu function calling và hướng dẫn function calling với Gemini 3.8 Flash để kiểm tra toàn bộ vòng lặp hai lượt.

Gemini 3.8 Flash có xu hướng gọi công cụ nhiều lần hơn Gemini 3.7 Flash, vì vậy hãy kiểm tra cả số lượt gọi tối đa.

6. Truyền lại chính xác thinking signature

Model Gemini 3 đính kèm thinking signature vào các phần response. Khi tự xây dựng lượt tiếp theo, hãy gửi lại mọi phần không thay đổi, bao gồm signature, cho tất cả loại phần—not chỉ phần văn bản. Loại bỏ hoặc tuần tự hóa lại chúng có thể làm giảm tính liên tục ở lượt kế tiếp.

Với Interactions API, bạn có thể để server quản lý trạng thái bằng previous_interaction_id. Google sẽ giữ lịch sử giúp bạn.

Nếu đặt store: false, bạn phải tự quản lý lịch sử và gửi lại các khối tư duy cùng signature. Với generateContent, ứng dụng luôn tự quản lý lịch sử; hãy kiểm tra code đang dựng lại contents từ bản sao đã cắt bớt của response cuối.

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

Không có lỗi rõ ràng ở mục này nên nó thường bị bỏ qua. Con số +30% token đầu ra là mức trung bình Artificial Analysis đo được trên benchmark của họ ở mức tư duy cao.

Google mô tả rằng model có thể dùng nhiều token hơn cho tác vụ phức tạp và kéo dài, đặc biệt ở mức effort cao.

Gợi ý cấu hình:

• Endpoint nhạy cảm về độ trễ: dùng low. Artificial Analysis đo được khoảng 0,8 phút và $0,24 mỗi tác vụ ở mức thấp, so với 2,5 phút và $0,58 ở mức cao.
• Route mặc định: dùng medium, khoảng $0,41 mỗi tác vụ trên cùng benchmark.
• Agent loop: dự kiến nhiều lượt gọi công cụ hơn; giới hạn theo số lượt, không chỉ theo token.

Hãy xem lại giới hạn output 65.536 token. Một prompt Gemini 3.7 Flash từng trả về 40.000 token cùng phần tư duy có thể tiến gần giới hạn hơn trên Gemini 3.8 Flash. Phân tích giá Gemini 3.8 Flash có số liệu theo từng mức độ.

8. Đo media_resolution_high riêng trên PDF và video

Gemini 3.8 Flash nhận văn bản, hình ảnh, video, âm thanh và PDF. Độ phân giải media ảnh hưởng đến số token đầu vào, nhưng chi phí còn phụ thuộc loại media.

Vì vậy, cùng một thiết lập có thể hợp lý với một trang PDF nhưng đắt đối với video dài. Không nên áp dụng toàn cục thiết lập độ phân giải cao từ Gemini 3.7 Flash.

Hãy kiểm thử:

1. Một PDF đại diện ở từng mức độ phân giải.
2. Một video đại diện ở từng mức độ phân giải.
3. So sánh usageMetadata.promptTokenCount.

9. Bỏ qua các lời gọi image segmentation

Image segmentation không được hỗ trợ trên model Gemini 3. Nếu workflow Gemini 3.7 Flash đang định tuyến segmentation sang model Gemini cũ hơn, đó là một đường dẫn riêng và không thuộc phạm vi di chuyển này.

Nếu prompt yêu cầu Gemini 3.8 Flash tạo segmentation mask, hãy dự kiến request thất bại thay vì nhận output dùng được.

Theo trang model Gemini 3.8 Flash, image generation, audio generation và Live API cũng không được hỗ trợ.

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

Một quá trình di chuyển có hai thay đổi gây lỗi cùng sự thay đổi về token cần một phép so sánh có thể lặp lại, không chỉ một lệnh curl chạy một lần.

Apidog phù hợp cho việc này vì có thể gửi request, kiểm tra response và lên lịch chạy. Apidog là API client và công cụ kiểm thử; nó không chạy model.

1. Tạo environment và biến

Tạo environment Gemini với:

• GEMINI_API_KEY: lưu dưới dạng secret.
• MODEL: biến chứa model ID.

Dùng {{MODEL}} trong URL của request generateContent và trong trường model của Interactions API. Nhờ đó, cùng một request có thể chạy trên cả hai model.

2. Lưu golden prompts

Tạo 10–20 prompt đại diện cho workload thực tế:

• Một lượt trò chuyện ngắn.
• Structured output.
• Function calling hai lượt với mock tool.
• Input PDF.
• Input video.

Mỗi prompt nên là một request trong test scenario.

3. Thêm assertions

Mỗi request nên có ít nhất ba assertion:

1. HTTP status là 200 và response khớp JSON schema. Với structured output, hãy kiểm tra trực tiếp các trường mà ứng dụng sẽ parse.
2. usageMetadata.thoughtsTokenCount thấp hơn trần của route, ví dụ 8.000 token cho route low. Assertion này giúp phát hiện cấu hình âm thầm quay về medium.
3. usageMetadata.totalTokenCount thấp hơn ngân sách của route ở Bước 7.

Với scenario function calling, thêm assertion đảm bảo call_id gửi lại khớp với id từ function_call ở lượt trước.

4. Chạy song song hai model

Sao chép scenario thành hai bản:

• Bản A: MODEL=gemini-3.7-flash.
• Bản B: MODEL=gemini-3.8-flash.

Chạy cả hai để so sánh:

• Trạng thái đạt/không đạt.
• Nội dung response.
• Token theo từng prompt.
• Số lượt gọi công cụ.

Báo cáo kiểm thử của Apidog hiển thị kết quả assertions trong cùng một giao diện, thay vì buộc bạn tái tạo số liệu từ log.

5. Lên lịch kiểm thử

Biến scenario Gemini 3.8 Flash thành scheduled run để kiểm tra giới hạn token hằng ngày trong giai đoạn triển khai. Xem hướng dẫn lên lịch API test.

Nếu muốn làm theo trong ứng dụng, hãy tải Apidog và import các đoạn curl ở trên.

Khôi phục bằng configuration flag

Vì Gemini 3.7 Flash vẫn được hỗ trợ đầy đủ và có cùng mức giá, việc rollback khá đơn giản: giữ model ID trong configuration thay vì hard-code trong application.

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

Ba quy tắc để flag an toàn

• Dùng cùng request format trên cả hai model. Các thay đổi ở mục 1–6—không dùng minimal, bỏ sampling keys, dùng thinking_level thay thinking_budget, bỏ candidate_count, gửi call_id + name, giữ signature—đều hợp lệ trên Gemini 3.7 Flash. Khi rollback, bạn không cần một code path thứ hai.
• Triển khai theo từng route. Chuyển các route low trước vì chênh lệch token nhỏ hơn; chuyển agent loop sau cùng, khi scenario song song đã ổn định trong vài ngày.
• Theo dõi token, không chỉ lỗi. Việc rollback có thể xuất phát từ chi phí hoặc độ trễ tăng, chứ không chỉ từ lỗi 4xx. Hãy đưa các token-limit assertion vào hệ thống cảnh báo.

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

Gemini 3.8 Flash có đắt hơn Gemini 3.7 Flash không?

Không đắt hơn theo mỗi token. Cả hai có giá $0,75 input / $3,75 output trên 1 triệu token đến ngày 31/12/2026, sau đó tăng lên $1,50 / $7,50 từ ngày 01/01/2027.

Tính theo mỗi tác vụ, Gemini 3.8 Flash dùng nhiều token hơn theo thiết kế. Artificial Analysis đo được nhiều hơn khoảng 30% trên benchmark của họ ở mức tư duy cao.

Nếu giữ thinking_level: "minimal" thì sao?

Request sẽ thất bại với lỗi xác thực trên Gemini 3.8 Flash. Hãy đổi thành low. Xem hướng dẫn về các mức độ thinking để biết cách chọn và đo từng mức.

Có bắt buộc chuyển sang Interactions API không?

Không. generateContent được xem là API cũ nhưng vẫn được hỗ trợ đầy đủ và chưa có ngày ngừng hoạt động. Gemini 3.8 Flash hoạt động trên cả hai API.

Interactions API cung cấp trạng thái hội thoại phía server qua previous_interaction_id, giúp giảm công việc quản lý thinking signature ở mục 6.

Gemini 3.7 Flash có bị ngừng hỗ trợ không?

Chưa. Google cho biết model này “vẫn được hỗ trợ đầy đủ” và chưa công bố ngày ngừng hỗ trợ. Đây là lý do configuration flag rollback vẫn khả thi.

Có thể giữ temperature đã tinh chỉnh cho Gemini 3.7 Flash không?

Google khuyến nghị để temperature mặc định 1.0 trên mọi model Gemini 3. Nếu đang override giá trị này trên Gemini 3.7 Flash, hãy xóa override và chạy lại benchmark. Với output xác định hình dạng, hãy dùng structured output thay vì temperature thấp.

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

Bản thân thay đổi code khá nhỏ:

• Một lần đổi model ID.
• Bốn lần xóa hoặc đổi tên cấu hình.
• Hai trường trong tool loop.
• Một lần audit thinking signature.

Phần tốn thời gian là chứng minh ngân sách token ổn định trên từng route. Hãy:

1. Lưu golden prompts.
2. Thêm schema assertions và token limits.
3. Chạy Gemini 3.7 và 3.8 Flash song song.
4. Chờ số liệu ổn định.
5. Bật configuration flag từng route một.
6. Rollback route có hồi quy mà không cần đổi code.

Cách tiếp cận này cho phép giữ lại các route đã cải thiện, đồng thời vẫn có đường lui an toàn cho những workload chưa phù hợp.

Tài liệu tham khảo

• Có gì mới trong Gemini 3.8 Flash
• Apidog
• Gemini 3.8 Flash là gì
• Giá Gemini API
• Bài đăng ra mắt Gemini 3.8 Flash
• So sánh Gemini 3.8 Flash và Gemini 3.7 Flash
• Hướng dẫn API Gemini 3.8 Flash
• Hướng dẫn API Gemini 3.7 Flash
• Tài liệu về thinking
• Các mức độ thinking cho Gemini 3.8 Flash
• Tài liệu function calling
• Function calling với Gemini 3.8 Flash
• Artificial Analysis
• Phân tích giá Gemini 3.8 Flash
• Trang model Gemini 3.8 Flash
• Hướng dẫn lên lịch API test
• Tải Apidog