DEV Community

Cover image for Hướng dẫn sử dụng API Gemini 3.8 Flash: API Tương tác, cấp độ tư duy và cuộc gọi API đầu tiên với Apidog
Sebastian Petrus
Sebastian Petrus

Posted on Originally published at apidog.com

Hướng dẫn sử dụng API Gemini 3.8 Flash: API Tương tác, cấp độ tư duy và cuộc gọi API đầu tiên với Apidog

Tích hợp Gemini 3.8 Flash API: Interactions, generateContent và kiểm soát chi phí suy nghĩ

Google đã phát hành Gemini 3.8 Flash vào ngày 2 tháng 9 năm 2026. ID mô hình API là gemini-3.8-flash, không có hậu tố xem trước. Trong thời gian giới thiệu đến hết ngày 31 tháng 12 năm 2026, giá vẫn là 0,75 đô la cho mỗi triệu token đầu vào và 3,75 đô la cho mỗi triệu token đầu ra.

Gemini 3.8 Flash được Google mô tả là mô hình “làm việc chăm chỉ hơn”: mô hình thực hiện nhiều bước suy luận hơn và gọi công cụ thường xuyên hơn trên các tác vụ phức tạp. Điều này có thể làm tăng số token và chi phí thực tế.

Dùng thử Apidog ngay hôm nay

Bài viết này hướng dẫn toàn bộ quy trình tích hợp:

  • Lấy API key trong AI Studio.
  • Gửi yêu cầu đầu tiên qua Interactions API.
  • Sử dụng generateContent, API cũ mà nhiều ứng dụng hiện có vẫn dùng.
  • Đặt thinking_level đúng vị trí trong từng API.
  • Sử dụng streaming.
  • Đọc thoughtsTokenCount để kiểm soát chi phí suy nghĩ.
  • Kiểm thử các request HTTP trong Apidog trước khi triển khai.

Để xem tổng quan về mô hình, benchmark và các thay đổi chính, hãy đọc bài Gemini 3.8 Flash là gì và bài đăng ra mắt chính thức của Google.

Tổng quan Gemini 3.8 Flash API

Mục Giá trị
ID mô hình gemini-3.8-flash
Điểm cuối chính POST /v1beta/interactions
Điểm cuối cũ POST /v1beta/models/gemini-3.8-flash:generateContent
Tiêu đề xác thực x-goog-api-key
Ngữ cảnh / đầu ra 1.048.576 token đầu vào / 65.536 token đầu ra
Đầu vào Văn bản, hình ảnh, video, âm thanh, PDF
Đầu ra Chỉ văn bản
Mức độ suy nghĩ low, medium mặc định, high
Mức minimal Không được hỗ trợ và sẽ trả về lỗi
Giá đến hết 31/12/2026 0,75 đô la / 3,75 đô la cho mỗi 1 triệu token
Giá từ 01/01/2027 1,50 đô la / 7,50 đô la cho mỗi 1 triệu token

Hai điểm cần nhớ trước khi viết mã:

  1. Mức suy nghĩ mặc định là medium, không phải high như trên Gemini 3 Pro.
  2. Token suy nghĩ được tính phí theo tỷ lệ token đầu ra. Vì vậy, lựa chọn mức suy nghĩ ảnh hưởng cả chất lượng lẫn chi phí. Xem thêm phân tích giá Gemini 3.8 Flash.

Bước 1: Lấy API key trong AI Studio

Mở Google AI Studio, đăng nhập bằng tài khoản Google và tạo API key từ trang quản lý khóa.

Khóa hoạt động ngay trên gói miễn phí, nhưng gói này có giới hạn tốc độ. Google cũng cho biết dữ liệu của gói miễn phí “được sử dụng để cải thiện sản phẩm của chúng tôi”. Để chuyển sang Bậc 1 và tăng giới hạn sản xuất, hãy liên kết tài khoản thanh toán.

Không dán khóa trực tiếp vào mã nguồn. Hãy lưu khóa dưới dạng biến môi trường:

export GEMINI_API_KEY="AIza..."
Enter fullscreen mode Exit fullscreen mode

SDK Python chính thức sẽ tự đọc GEMINI_API_KEY, nên genai.Client() không cần truyền thêm đối số.

Cài đặt SDK:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

Bước 2: Gửi request đầu tiên qua Interactions API

Google hiện xem Interactions API là cách chính để gọi các mô hình Gemini 3.x.

Request gồm:

  • model: ID mô hình.
  • input: nội dung đầu vào.
  • generation_config: tùy chọn, dùng để đặt thinking_level.

Gọi bằng cURL 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Giải thích HTTP caching trong 3 câu.",
    "generation_config": {"thinking_level": "medium"}
  }'
Enter fullscreen mode Exit fullscreen mode

Interactions API trả về danh sách các bước thực thi thay vì một tin nhắn duy nhất. Các bước suy nghĩ và gọi công cụ xuất hiện riêng, còn bước cuối cùng là model_output, chứa văn bản trả lời.

Gọi bằng Python

SDK sẽ làm phẳng cấu trúc này:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Giải thích HTTP caching trong 3 câu.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)
Enter fullscreen mode Exit fullscreen mode

Không giảm temperature

Đối với các mô hình Gemini 3, Google khuyến nghị giữ temperature ở giá trị mặc định 1.0. Việc giảm giá trị này “có thể gây ra vòng lặp hoặc hiệu suất suy giảm”.

Nếu bạn sao chép cấu hình từ mô hình cũ, hãy xóa các thiết lập như:

  • temperature
  • top_p
  • top_k

Bước 3: Xây dựng hội thoại nhiều lượt

Interactions API lưu trạng thái hội thoại trên máy chủ theo mặc định. Để tiếp tục một hội thoại, gửi previous_interaction_id cùng với input mới. Bạn không cần gửi lại toàn bộ lịch sử.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Bây giờ hãy đưa ra một ví dụ về tiêu đề Cache-Control.",
    previous_interaction_id=interaction.id,
)

print(follow_up.output_text)
Enter fullscreen mode Exit fullscreen mode

Nếu chính sách tuân thủ không cho phép lưu trạng thái phía máy chủ, hãy đặt:

{
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

Khi đó, ứng dụng phải tự quản lý trạng thái. Ở mỗi lượt, bạn cũng phải gửi lại chính xác các khối suy nghĩ và chữ ký suy nghĩ của mô hình như đã nhận được. Đây là một trong những điểm khiến việc sử dụng công cụ phức tạp hơn; xem thêm hướng dẫn function calling cho Gemini 3.8 Flash.

Bước 4: Sử dụng generateContent

Phần lớn mã Gemini đang chạy trong môi trường production vẫn sử dụng generateContent. Google gọi đây là API cũ nhưng vẫn “được hỗ trợ đầy đủ” và chưa công bố ngày ngừng hỗ trợ.

Bạn chưa bắt buộc phải viết lại ứng dụng hiện có. Hình dạng request tương tự hướng dẫn Gemini 3.7 Flash API, nhưng vị trí của cấu hình suy nghĩ khác với Interactions API.

Trong generateContent, thinkingLevel nằm tại:

generationConfig.thinkingConfig.thinkingLevel
Enter fullscreen mode Exit fullscreen mode

Gọi bằng cURL 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Giải thích HTTP caching trong 3 câu."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'
Enter fullscreen mode Exit fullscreen mode

Gọi bằng Python 

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Giải thích HTTP caching trong 3 câu.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)
Enter fullscreen mode Exit fullscreen mode

Nếu cấu hình cũ đang dùng thinking_budget dạng số nguyên, hãy thay thế bằng enum chuỗi:

low
medium
high
Enter fullscreen mode Exit fullscreen mode

Ngoài ra, candidate_count không còn được hỗ trợ từ Gemini 3 trở lên. Xem đầy đủ JSON trước và sau trong hướng dẫn di chuyển từ Gemini 3.7 sang 3.8 Flash.

So sánh hai API

Mối quan tâm Interactions API generateContent
Mức độ suy nghĩ generation_config.thinking_level generationConfig.thinkingConfig.thinkingLevel
Trạng thái hội thoại previous_interaction_id phía máy chủ Gửi lại toàn bộ mảng contents
Kết quả công cụ function_result với call_id + name functionResponse với id + name
Văn bản cuối cùng Bước model_output, hoặc output_text trong SDK candidates[0].content.parts[].text
Chữ ký suy nghĩ SDK xử lý, trừ khi store: false Phải gửi lại từng phần chính xác

Bước 5: Streaming và theo dõi chi phí suy nghĩ

Đối với giao diện trò chuyện, đổi tên phương thức thành streamGenerateContent và thêm ?alt=sse để nhận Server-Sent Events.

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-[REDACTED CREDENTIAL]INI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Liệt kê ba tiêu đề HTTP caching."}]}]}'
Enter fullscreen mode Exit fullscreen mode

Dù sử dụng streaming hay không, phản hồi generateContent đều kết thúc bằng usageMetadata. Hãy đọc trường này trong mọi request:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}
Enter fullscreen mode Exit fullscreen mode

Trường quan trọng nhất trên Gemini 3.8 Flash là thoughtsTokenCount.

Token suy nghĩ được tính phí như token đầu ra: 3,75 đô la cho mỗi triệu token trong giai đoạn giới thiệu. Google cũng cảnh báo mô hình “có thể sử dụng nhiều token hơn để tối đa hóa hiệu suất, đặc biệt ở mức độ nỗ lực cao hơn”.

Artificial Analysis đã đo được khoảng 48.000 token đầu ra cho mỗi tác vụ trong các lần chạy ở mức high, nhiều hơn 30% so với Gemini 3.7 Flash. Với cùng mức giá mỗi token, chi phí mỗi tác vụ tăng từ 0,40 đô la lên 0,58 đô la.

Chi phí được đo cho các mức khác:

  • medium: 0,41 đô la mỗi tác vụ.
  • low: 0,24 đô la mỗi tác vụ.

Bài Gemini 3.8 Flash thinking levels trình bày cách chọn mức suy nghĩ theo từng loại tác vụ.

Hiển thị tóm tắt suy nghĩ

Để xem mô hình đã suy luận về điều gì, thêm includeThoughts: true bên trong thinkingConfig:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "medium",
      "includeThoughts": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Tóm tắt suy nghĩ sẽ được trả về dưới dạng các phần có cờ:

{
  "thought": true
}
Enter fullscreen mode Exit fullscreen mode

Khi ghép nội dung hiển thị cho người dùng, hãy bỏ qua những phần này.

Các lỗi thường gặp

thinking_level: "minimal" trả về lỗi 400

Gemini 3.8 Flash chỉ hỗ trợ:

  • low
  • medium
  • high

Gửi minimal sẽ trả về lỗi 400 INVALID_ARGUMENT:

Thinking level MINIMAL is not supported for this model.
Please retry with other thinking level.
Enter fullscreen mode Exit fullscreen mode

Cách khắc phục là đổi minimal thành low:

{
  "thinking_level": "low"
}
Enter fullscreen mode Exit fullscreen mode

Lỗi này thường xuất hiện khi sao chép cấu hình từ các mô hình Gemini 3.x cũ hơn.

Lỗi 429

Lỗi 429 thường có nghĩa là bạn đã chạm giới hạn của bậc tài khoản, không nhất thiết là request sai.

Các bậc hiện có:

  • Gói miễn phí: giới hạn tốc độ thấp.
  • Bậc 1: mở khóa khi liên kết tài khoản thanh toán.
  • Bậc 2: yêu cầu chi tiêu từ 100 đô la và tài khoản hoạt động thêm ba ngày.
  • Bậc 3: yêu cầu chi tiêu từ 1.000 đô la và tài khoản hoạt động thêm 30 ngày.

Số request mỗi phút và token mỗi phút phụ thuộc mô hình và tài khoản. Hãy kiểm tra trực tiếp trang giới hạn tốc độ trong AI Studio thay vì dùng con số từ một bài blog.

Khi gặp lỗi 429:

  1. Tạm dừng và thử lại với backoff.
  2. Nếu lỗi tiếp tục xảy ra ở lưu lượng thấp, nâng cấp bậc tài khoản.
  3. Với công việc ngoại tuyến, cân nhắc Gemini Batch API.

Batch API được giảm giá 50% trong thời gian giới thiệu, còn 0,375 đô la / 1,875 đô la cho mỗi triệu token. Giới hạn token xếp hàng riêng là:

  • Bậc 1: 3 triệu token.
  • Bậc 2: 400 triệu token.
  • Bậc 3: 1 tỷ token.

Thiếu định danh trong kết quả hàm

Khi sử dụng công cụ:

  • function_result của Interactions API phải có cả call_id và name.
  • functionResponse của API cũ phải có cả id và name.
  • Các giá trị định danh phải khớp với function call tương ứng.

Thiếu một trong các trường này sẽ khiến lượt gọi thất bại.

Kiểm thử cả hai endpoint trong Apidog

Khi hai request hoạt động từ terminal, hãy chuyển chúng vào một nơi mà cả nhóm có thể chạy lại. Tải Apidog, tạo project và lưu cả hai endpoint dưới dạng request.

1. Tách API key khỏi request

Thêm biến môi trường:

GEMINI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Sau đó tham chiếu biến trong header:

x-goog-[REDACTED CREDENTIAL]
Enter fullscreen mode Exit fullscreen mode

Request đã lưu không chứa bí mật. Việc chuyển đổi giữa khóa miễn phí và khóa trả phí chỉ cần thay đổi môi trường.

2. Kiểm tra trạng thái và token sử dụng

Thêm assertion kiểm tra:

status == 200
Enter fullscreen mode Exit fullscreen mode

Sau đó thêm JSON path assertion để bảo đảm:

usageMetadata.thoughtsTokenCount
Enter fullscreen mode Exit fullscreen mode

nằm dưới ngưỡng bạn chọn cho mỗi prompt.

Ngưỡng này hoạt động như cảnh báo hồi quy chi phí. Nếu thay đổi prompt hoặc mô hình khiến số token suy nghĩ tăng bất thường, test sẽ thất bại trước khi hóa đơn tăng. Hướng dẫn kiểm thử SSE cũng bao gồm biến thể streaming; Apidog hiển thị luồng này dưới dạng các sự kiện đã hợp nhất.

3. So sánh cả ba mức suy nghĩ

Tạo ba bản sao của cùng một request với:

  • low
  • medium
  • high

So sánh thoughtsTokenCount và thời gian phản hồi cạnh nhau. Nhờ đó, bạn có số liệu thực tế cho prompt của mình thay vì chỉ dựa vào mức trung bình benchmark.

4. Lên lịch chạy test

Biến các request thành test scenario và chạy theo lịch. Khi giới hạn tốc độ, xác thực hoặc số token thay đổi, vấn đề sẽ xuất hiện trong báo cáo test thay vì production.

Xem cách lên lịch kiểm thử API trong Apidog.

Apidog không chạy mô hình và không thay thế SDK. Nó cung cấp một phiên bản HTTP request có thể lưu trữ, chia sẻ và kiểm chứng — phần thường bị bỏ qua cho đến khi có sự cố.

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

Dự án mới nên sử dụng endpoint nào?

Nên dùng Interactions API. Google gọi generateContent là API cũ nhưng vẫn hỗ trợ đầy đủ. Các tính năng mới thường xuất hiện trên Interactions trước, đồng thời trạng thái phía máy chủ giúp mã đa lượt ngắn gọn hơn.

Với dịch vụ hiện có, bạn có thể tiếp tục dùng generateContent cho đến khi có lý do cụ thể để di chuyển.

Có cần tài khoản trả phí để gọi Gemini 3.8 Flash không?

Không. API key AI Studio miễn phí vẫn hoạt động, nhưng đi kèm giới hạn tốc độ và điều khoản sử dụng dữ liệu của Google.

Xem hướng dẫn sử dụng Gemini 3.8 Flash miễn phí để biết gói miễn phí hỗ trợ và không hỗ trợ những gì. Lưu ý rằng ứng dụng Gemini có thể yêu cầu gói AI Pro hoặc Ultra để dùng Gemini 3.8 Flash.

Gemini 3.8 Flash có chậm hơn 3.7 Flash không?

Tính theo mỗi token thì không. Logan Kilpatrick của Google cho biết tốc độ gần như tương đương, còn Artificial Analysis đo được khoảng 300 token đầu ra mỗi giây.

Tính theo mỗi tác vụ, Gemini 3.8 Flash có thể mất nhiều thời gian hơn ở mức high: khoảng 2,5 phút so với 2,2 phút trong các lần chạy của Artificial Analysis. Nguyên nhân là mô hình tạo ra nhiều token hơn.

Có thể tiếp tục dùng Gemini 3.7 Flash không?

Có. 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ợ.

Nếu số token bổ sung của Gemini 3.8 Flash không mang lại lợi ích cho workload, tiếp tục dùng 3.7 Flash vẫn là lựa chọn hợp lý. Xem thêm bài so sánh Gemini 3.8 Flash và 3.7 Flash.

Gemini 3.8 Flash có hỗ trợ Live API hoặc tạo hình ảnh không?

Không. Mô hình chỉ xuất văn bản. Tạo âm thanh, tạo hình ảnh và Live API không được hỗ trợ.

Bước tiếp theo

Bạn hiện đã có:

  • Hai endpoint hoạt động.
  • Một mẫu hội thoại nhiều lượt.
  • Cấu hình cho cả Interactions API và generateContent.
  • Streaming qua SSE.
  • Cách theo dõi thoughtsTokenCount.
  • Bộ kiểm thử có thể chạy lại và lên lịch trong Apidog.

Tiếp theo, hãy kết nối công cụ theo hướng dẫn function calling, chọn mức suy nghĩ cho từng route và dùng script Apidog để phát hiện sớm các thay đổi chi phí.

Top comments (0)