Blog

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

Hướng dẫn từng bước Flash API của Gemini 3.8: lấy khóa AI Studio, gọi API Interactions và generateContent cũ, đặt mức độ suy nghĩ, và kiểm tra trong Apidog.

Medy Evrard

3 tháng 9 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Google đã phát hành Gemini 3.8 Flash vào ngày 2 tháng 9 năm 2026, và ID mô hình API là chuỗi gemini-3.8-flash đơn giản, không có hậu tố xem trước. Nó giữ nguyên giá giới thiệu của 3.7 Flash 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 cho đến ngày 31 tháng 12 năm 2026, và Google mô tả nó là một mô hình “làm việc chăm chỉ hơn”: nó 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 sẽ thể hiện trên hóa đơn token của bạn.

Hướng dẫn này bao gồm toàn bộ quá trình để có được một tích hợp hoạt động: lấy khóa trong AI Studio, gửi yêu cầu đầu tiên thông qua Interactions API (API chính của Google cho Gemini 3.x hiện nay), phương thức generateContent cũ mà hầu hết mã hiện có vẫn sử dụng, vị trí đặt thinking_level trong mỗi loại, cách truyền dữ liệu (streaming) và cách đọc thoughtsTokenCount để chi phí suy nghĩ không bao giờ làm bạn bất ngờ. Mỗi cuộc gọi đều là HTTP thuần túy với JSON, vì vậy bạn có thể xây dựng và kiểm tra từng cuộc gọi trong Apidog trước khi đưa vào mã ứng dụng.

nút

Để có cái nhìn tổng quan về mô hình, các điểm chuẩn và những thay đổi, hãy bắt đầu với Gemini 3.8 Flash là gì. Bài đăng ra mắt của Google có khung chính thức.

Tổng quan về API Gemini 3.8 Flash

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 (chỉ đầu ra văn bản)
Mức độ suy nghĩ low (thấp), medium (trung bình - mặc định), high (cao); minimal (tối thiểu) sẽ trả về lỗi
Giá (giới thiệu đến hết 31/12/2026) 0,75 đô la / 3,75 đô la cho mỗi 1 triệu token; 1,50 đô la / 7,50 đô la từ ngày 1 tháng 1 năm 2027

Hai chi tiết nổi bật trước khi bạn viết mã. Mức độ suy nghĩ mặc định là medium (trung bình), không phải high (cao) như trên Gemini 3 Pro. Và các token suy nghĩ được tính phí theo tỷ lệ đầu ra trên trang giá chính thức, vì vậy mức độ bạn chọn là một quyết định về chi phí cũng như về chất lượng. Phân tích giá đi sâu vào các con số cho từng tác vụ.

Bước 1: Lấy khóa API trong AI Studio

Mở Google AI Studio, đăng nhập bằng tài khoản Google và tạo khóa API từ trang khóa. Khóa này hoạt động ngay lập tức trên gói miễn phí, với các giới hạn tốc độ và lưu ý rằng Google nói dữ liệu gói miễn phí “được sử dụng để cải thiện sản phẩm của chúng tôi”. Liên kết một tài khoản thanh toán để chuyển sang Bậc 1 cho các giới hạn sản xuất.

Xuất khóa thay vì dán trực tiếp vào mã:

export GEMINI_API_KEY="AIza..."

SDK Python chính thức đọc GEMINI_API_KEY từ biến môi trường, vì vậy genai.Client() không cần đối số. Cài đặt nó bằng pip install google-genai.

Bước 2: Cuộc gọi đầu tiên của bạn với Interactions API

Google hiện coi Interactions API là cách chính để gọi các mô hình Gemini 3.x. Yêu cầu là một đối tượng JSON: mô hình, một input (đầu vào), và một generation_config tùy chọn nơi đặt thinking_level (mức độ suy nghĩ).

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"}
  }'

Phản hồi là một danh sách các bước thực thi thay vì một tin nhắn duy nhất. Các suy nghĩ của mô hình và các lệnh gọi công cụ xuất hiện dưới dạng các bước, và bước cuối cùng là model_output, chứa văn bản. Trong Python, SDK sẽ làm phẳng điều này cho bạn:

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)

Bỏ qua temperature, top_p, và top_k. Hướng dẫn của Google cho mọi mô hình Gemini 3 là giữ temperature ở mức mặc định là 1.0, vì việc giảm nó “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ột mô hình cũ hơn, đó là dòng đầu tiên cần xóa.

Bước 3: Đa lượt với previous_interaction_id

Interactions API giữ trạng thái cuộc hội thoại trên máy chủ theo mặc định. Để tiếp tục một cuộc hội thoại, hãy gửi id của phản hồi trước đó dưới dạng previous_interaction_id cùng với chỉ đầu vào mới của người dùng. Bạn không cần gửi lại 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)

Nếu các quy tắc tuân thủ của bạn cấm lưu trữ phía máy chủ, hãy đặt store: false. Đánh đổi là bạn phải tự quản lý trạng thái, bao gồm việc gửi lại các khối suy nghĩ và chữ ký suy nghĩ của mô hình chính xác như bạn đã nhận được chúng ở mỗi lượt. Đó là quy tắc tương tự gây khó khăn cho việc sử dụng công cụ, được đề cập trong hướng dẫn gọi hàm cho 3.8 Flash.

Bước 4: Đường dẫn generateContent cũ

Hầu hết mã Gemini trong sản xuất vẫn gọi generateContent. Google gọi nó là cũ (legacy), nhưng nó “vẫn được hỗ trợ đầy đủ” mà không có ngày ngừng hỗ trợ, vì vậy bạn không phải viết lại bất cứ điều gì hôm nay. Hướng dẫn API Gemini 3.7 Flash của chúng tôi chỉ đề cập đến đường dẫn này; hình dạng giống hệt nhau đối với 3.8 Flash, và cài đặt suy nghĩ nằm ở một vị trí khác so với trên Interactions.

Trong generateContent, cấp độ nằm dưới generationConfig.thinkingConfig.thinkingLevel, theo kiểu camelCase:

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

Mã Python tương đương sử dụng các đối tượng cấu hình có kiểu:

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)

Nếu bạn đang sử dụng một cấu hình đã dùng thinking_budget dưới dạng số nguyên, hãy thay thế nó bằng kiểu enum chuỗi. candidate_count cũng không còn trên Gemini 3 trở lên. Danh sách đầy đủ, với JSON trước và sau cho mỗi thay đổi, có trong hướng dẫn di chuyển từ 3.7 sang 3.8 Flash.

Dưới đây là cùng một tập hợp các mối quan tâm được đặt cạnh nhau, để bạn có thể chuyển đổi giữa hai API mà không cần đọc lại cả hai tài liệu:

Mối quan tâm Interactions API generateContent cũ
Mức độ suy nghĩ generation_config.thinking_level generationConfig.thinkingConfig.thinkingLevel
Trạng thái cuộc 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 (cùng giá trị, tên trường khác nhau)
Văn bản cuối cùng Bước model_output (output_text trong SDK) candidates[0].content.parts[].text
Chữ ký suy nghĩ Được xử lý cho bạn trừ khi store: false Gửi lại từng phần chính xác như đã nhận

Bước 5: Truyền dữ liệu (Streaming) và đọc chi phí suy nghĩ

Đối với giao diện trò chuyện, hãy thay đổi tên phương thức thành streamGenerateContent và thêm ?alt=sse để nhận các sự kiện được gửi từ máy chủ (server-sent events), mỗi sự kiện là một phần candidates chunk:

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

Dù có truyền dữ liệu hay không, mỗi phản hồi generateContent đều kết thúc bằng một đối tượng usageMetadata. Hãy đọc nó trong mỗi cuộc gọi:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount là con số cần theo dõi trên 3.8 Flash. Các token suy nghĩ được tính phí như token đầu ra với 3,75 đô la cho mỗi triệu trong giai đoạn giới thiệu, và Google nói rằng 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 nghìn token đầu ra cho mỗi tác vụ trong lần chạy chỉ mục ở mức high (cao), nhiều hơn 30% so với 3.7 Flash, điều này đã đẩy chi phí mỗi tác vụ từ 0,40 đô la lên 0,58 đô la với giá mỗi token không đổi. Các lần chạy medium (trung bình) và low (thấp) của họ có chi phí là 0,41 đô la và 0,24 đô la cho mỗi tác vụ. Hướng dẫn về các mức độ suy nghĩ biến những con số đó thành một chiến lược theo từng tuyến đường.

Để xem mô hình đã suy luận về điều gì, hãy thêm "includeThoughts": true bên trong thinkingConfig. Tóm tắt suy nghĩ sẽ trả về dưới dạng các phần được gắn cờ "thought": true; hãy bỏ qua những phần này khi bạn ghép nối câu trả lời hiển thị.

Các lỗi bạn có thể gặp trong giờ đầu tiên

thinking_level: "minimal" bị lỗi xác thực. Gemini 3.8 Flash chỉ hỗ trợ low (thấp), medium (trung bình) và high (cao). Gửi minimal (tối thiểu) sẽ trả về lỗi 400 INVALID_ARGUMENT với thông báo “Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.” (Mức độ suy nghĩ MINIMAL không được hỗ trợ cho mô hình này. Vui lòng thử lại với mức độ suy nghĩ khác.) (đã xác minh bằng một cuộc gọi trực tiếp vào ngày 3 tháng 9 năm 2026), và cách khắc phục là thay đổi một từ thành low (thấp). Các cấu hình 3.x cũ hơn và các đoạn mã sao chép là nguồn gốc thông thường của lỗi này.

Lỗi 429 có nghĩa là bạn đã đạt đến giới hạn của bậc, không phải lỗi. Trang giới hạn tốc độ giải thích các bậc: gói miễn phí bị giới hạn tốc độ, Bậc 1 được mở khóa khi bạn liên kết tài khoản thanh toán, Bậc 2 yêu cầu chi tiêu 100 đô la cộng thêm ba ngày, và Bậc 3 yêu cầu 1.000 đô la cộng thêm 30 ngày. Số lượng yêu cầu mỗi phút và token mỗi phút cho từng mô hình chỉ được hiển thị trên trang giới hạn tốc độ của AI Studio cho tài khoản của bạn, vì vậy hãy kiểm tra ở đó thay vì tin vào một con số từ bài đăng trên blog. Khi gặp lỗi 429, hãy tạm dừng và thử lại; nếu lặp lại lỗi 429 ở khối lượng thấp, hãy nâng cấp bậc. Đối với các công việc ngoại tuyến, Batch API là giải pháp tốt hơn: nó hoạt động với mức giảm giá 50% (0,375 đô la / 1,875 đô la cho mỗi triệu token trong thời gian giới thiệu) và có giới hạn token được xếp hàng đợi riêng là 3 triệu ở Bậc 1, 400 triệu ở Bậc 2 và 1 tỷ ở Bậc 3. Hướng dẫn chế độ hàng loạt Gemini hiển thị hình dạng yêu cầu.

Thiếu call_id trong kết quả hàm. Nếu bạn sử dụng công cụ, mỗi function_result (Interactions) phải mang cả call_id và name trên 3.8 Flash, và mỗi functionResponse cũ phải mang id và name khớp nhau. Bỏ qua một trong hai sẽ làm cho lượt gọi thất bại.

Kiểm tra cả hai điểm cuối trong Apidog trước khi triển khai

Khi cả hai yêu cầu hoạt động từ terminal, hãy chuyển chúng đến một nơi mà toàn bộ nhóm có thể chạy. Tải xuống Apidog, tạo một dự án và thêm hai điểm cuối trên làm yêu cầu đã lưu. Bốn thói quen sau đây sẽ mang lại lợi ích:

Apidog không chạy mô hình hay thay thế SDK. Nó cung cấp cho bạn một phiên bản đã lưu, có thể chia sẻ và có thể kiểm chứng của các cuộc gọi HTTP, đây là phần mà hầu hết các nhóm thường bỏ qua cho đến khi có điều gì đó xảy ra.

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

Điểm đến tiếp theo

Bây giờ bạn đã có hai đường dẫn gọi hoạt động, một mẫu đa lượt và một công cụ kiểm tra việc sử dụng token. Từ đây, hãy kết nối các công cụ với hướng dẫn gọi hàm, quyết định mức độ cho từng tuyến đường với bài viết về các mức độ suy nghĩ, và nếu bạn vẫn đang cân nhắc có nên chuyển đổi hay không, bài so sánh 3.8 vs 3.7 Flash sẽ trình bày các yếu tố đánh đổi. Hãy để kịch bản Apidog chạy để sự thay đổi chi phí sẽ xuất hiện dưới dạng một kiểm thử thất bại.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống