Gemini APIGoogle GenAITutorial

Hướng dẫn Gemini API 2026: từ request đầu tiên đến production

15 thg 8, 20261 phút đọc

Bạn mở tài liệu Gemini, và quyết định đầu tiên ập đến: AI Studio hay Vertex AI? Rồi quyết định thứ hai: dùng SDK nào? Rồi quyết định thứ ba: vì sao trang định giá liệt kê ba model Flash trong khi hướng dẫn bạn tìm được lại được viết cho Gemini 1.5?

Gemini là nền tảng AI được tài liệu hóa nhiều nhất nhưng lại có tình trạng hướng dẫn tệ nhất. Tài liệu chính thức rất đầy đủ nhưng rời rạc; hướng dẫn bên thứ ba thì hoặc là nội dung hời hợt kiểu “key miễn phí” hai phút, hoặc là nội dung cũ từ năm 2024 viết cho những model không còn tồn tại. Trong khi đó nền tảng phát triển rất nhanh — Gemini 3.7 Flash ra mắt với giá API giảm gần một nửa, và dòng Flash giờ dẫn đầu cả về nhịp độ phát hành so với model đầu bảng.

Hướng dẫn này là mảnh ghép còn thiếu ở giữa: một lộ trình duy nhất từ request đầu tiên đến production, trong Python và Node.js, bao quát sáu điểm khác biệt của Gemini — thinking budgets, context caching, Google Search grounding, structured output, multimodal gốc, và live API — cùng checklist production và những sai lầm tốn tiền thật. Đây là bài thứ ba trong loạt bài về nền tảng của chúng tôi, bên cạnh hướng dẫn OpenAI và hướng dẫn Claude.

Gemini API trong năm 2026 là gì

Điểm chính: Gemini là ba điểm vào, một họ model — và dòng Flash chính là nơi tập trung giá trị.

Ba cách để tiếp cận cùng các model:

AI Studio — điểm vào cho nhà phát triển. Free tier cho thử nghiệm, API keys và lộ trình nhanh nhất đến request đầu tiên. Bắt đầu từ đây.
Vertex AI — điểm vào cho doanh nghiệp. Governance, VPC, kiểm soát audit và quản lý quota theo dự án. Chuyển sang đây khi yêu cầu tuân thủ đòi hỏi.
Một endpoint hợp nhất — qua một gateway tương thích OpenAI, bạn có thể gọi Gemini bằng SDK mình đang dùng. Cùng các model, một đầu mối thanh toán.

Đội hình model 2026: Gemini 3.7 Flash là con ngựa thồ hiện tại — bản ra mắt giảm gần nửa giá API đưa nó về mức $0.75 mỗi triệu input tokens (kiểm tra mức giá hiện tại trên tài liệu tham khảo giá); Flash-Lite nằm dưới nó cho tác vụ đơn giản khối lượng lớn; tầng Pro nắm giữ trần chất lượng, với danh mục model theo dõi những gì khả dụng qua một endpoint. Cách tư duy hữu ích: Flash làm mặc định cho production, Pro cho tác vụ bạn đã đo được khoảng cách chất lượng, Lite cho tác vụ bạn chưa đo.

Vì sao Gemini xứng đáng một vị trí trong stack của bạn

Điểm chính: bốn lợi thế cấu trúc — free tier, giá cache, multimodal gốc và grounding — khiến Gemini trở thành đối trọng về chi phí và năng lực với OpenAI và Anthropic.

Free tier là thật. Hạn mức miễn phí của AI Studio đủ cho prototyping và đánh giá mà không cần thẻ. Đó không phải chú thích marketing; đó là cách bạn benchmark Gemini với nhà cung cấp hiện tại trước khi cam kết bất cứ điều gì.
Context caching ở mức ~0.1×. Cached input tokens được tính phí khoảng một phần mười mức giá input chuẩn — cùng mẫu mà caching của mọi nhà cung cấp tuân theo, với cơ chế caching trong tài liệu của chúng tôi.
Multimodal gốc. Input hình ảnh và âm thanh được hỗ trợ đầy đủ, không phải add-on — một prompt tài liệu kèm biểu đồ hoạt động mà không cần pipeline vision riêng.
Google Search grounding. Truy xuất kết quả tìm kiếm trực tiếp kèm trích dẫn là một tính năng nền tảng, không phải một dự án tích hợp.

Không điểm nào trong số này là “model tốt nhất”. Cả bốn kết hợp lại khiến Gemini trở thành nhà cung cấp thứ hai mạnh nhất trong hầu hết stack — và bài so sánh bốn nhà cung cấp của chúng tôi đã cho thấy vì sao “nhà cung cấp thứ hai” là một chiến lược, không phải lời xúc phạm.

Cách gọi request đầu tiên: Python & Node.js

Điểm chính: request đầu tiên chỉ mất năm phút — các thói quen vận hành production xung quanh nó mới là nội dung hướng dẫn.

Python, dùng Google GenAI SDK chính thức:

from google import genai

client = genai.Client(api_key="YOUR_AI_STUDIO_KEY")
response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Explain why caching cuts token costs, in one sentence.",
)
print(response.text)

Node.js, cùng cấu trúc:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
  model: "gemini-3.7-flash",
  contents: "Explain why caching cuts token costs, in one sentence.",
});
console.log(response.text);

Đã dùng OpenAI SDK? Endpoint tương thích chấp nhận các lệnh gọi tương tự chỉ với một thay đổi base_url — đó cũng là cách một gateway hợp nhất mở ra Gemini (quickstart cho thấy mẫu này). Thói quen vận hành production nên đi kèm request đầu tiên của bạn: log các trường usage từ ngày đầu tiên. usage_metadata (prompt tokens, candidates tokens, cached tokens) là nền tảng hạch toán chi phí của bạn — cùng thói quen mà mọi sổ tay observability đều bắt đầu.

Cách dùng sáu điểm khác biệt của Gemini

Điểm chính: sáu tính năng tách Gemini khỏi “một chat API khác” — mỗi tính năng là một cấu hình, không phải một dự án.

Thinking budget. Các model thinking của Gemini phân bổ reasoning tokens trước khi trả lời, và thinking tokens bị tính phí. Đặt một ngân sách tường minh cho production; mặc định thì ổn cho khám phá, nhưng đắt cho phân loại. Tác vụ đơn giản nên chạy trên đường non-thinking.
Context caching. Cache các prefix prompt ổn định (system prompts, mẫu tài liệu) và trả ~0.1× khi trúng cache. Cache key chính là prefix token chính xác — bất kỳ thay đổi nào của prefix đều trượt cache hoàn toàn, đó là lý do #1 của các báo cáo “caching không hoạt động”. Cấu hình là một cờ trên content, không phải một API riêng (hình dạng SDK tính đến giữa năm 2026; kiểm tra lại với tài liệu chính thức khi bạn ghim phiên bản SDK):

from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_AI_STUDIO_KEY")

# 1) Create the cache once, tied to your stable system prompt
cache = client.caches.create(
    model="gemini-3.7-flash",
    config=types.CreateCachedContentConfig(
        display_name="support-template",
        system_instruction="You are a support assistant for Acme.",
        contents=[types.Content(role="user",
                                parts=[types.Part.from_text(text="REPEATED_BOILERPLATE")])],
        ttl="3600s",
    ),
)

# 2) Reference it by resource name on every call
resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Refund policy, please.",
    config=types.GenerateContentConfig(cached_content=cache.name),
)

Google Search grounding. Bật grounding cho các truy vấn nhạy cảm thời gian và nhận trích dẫn kèm câu trả lời — mẫu grounding chung được bao quát ở nơi khác trong loạt bài này. Theo dõi khoản mục chi phí grounding; nó tách biệt với chi phí generation.

resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="What is the current limit for...?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)
# resp.candidates[0].grounding_metadata holds the citations

Structured output. Ràng buộc một JSON schema và Gemini sẽ tôn trọng nó — với một quy tắc cứng: giữ temperature ở mặc định khi dùng schema binding, vì thay đổi nó sẽ phá vỡ cam kết. Đó chính là cái bẫy mà hướng dẫn structured output của chúng tôi ghi lại.

resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Extract the invoice total and currency.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=types.Schema(
            type=types.Type.OBJECT,
            properties={
                "total": types.Schema(type=types.Type.NUMBER),
                "currency": types.Schema(type=types.Type.STRING),
            },
            required=["total", "currency"],
        ),
        temperature=1.0,  # default — do not change with schema binding
    ),
)

Multimodal gốc. Input hình ảnh và âm thanh chạy trên cùng một bề mặt API — một ảnh chụp màn hình, một biểu đồ, một đoạn ghi âm, tất cả chỉ qua một đối số contents.
Live/audio API. Hội thoại âm thanh thời gian thực tồn tại trên bề mặt riêng của nền tảng; hãy kiểm tra khả dụng hiện tại và hỗ trợ theo khu vực trước khi thiết kế kiến trúc quanh nó (và hãy nhớ năng lực của endpoint là thứ nó vốn có — hãy xác minh, đừng giả định).

Cách đưa Gemini vào production

Điểm chính: lộ trình production là quota, kiểm soát chi phí, eval và keys — theo đúng thứ tự đó.

Quotas và giới hạn. AI Studio và Vertex có các mức rate limit mặc định khác nhau; một khối lượng công việc production cần yêu cầu tăng quota trước tuần ra mắt, không phải sau lần 429 đầu tiên. Sổ tay xử lý rate limit chuẩn — exponential backoff, retry nhận biết header, fallback đa nhà cung cấp — áp dụng nguyên vẹn.
Kiểm soát chi phí. Ba đòn bẩy, tất cả đều là cấu hình: cache các prefix ổn định, định tuyến tác vụ dễ sang Flash-Lite, và đặt cảnh báo chi tiêu trên dashboard. Sự kết hợp thường cắt giảm 60-80% hóa đơn Gemini chưa tối ưu — cùng bộ chiến lược mà mọi sổ tay tối ưu chi phí xếp hạng.
Eval trước khi ra mắt. Một bộ eval cố định với cổng pass/fail bắt được hồi quy mà “model cảm giác ổn” bỏ lọt. Kỷ luật eval kiểu CI không phụ thuộc nhà cung cấp — chạy nó với Gemini trước khi chuyển đổi, không phải sau.
Keys và bảo mật. Keys của AI Studio được phạm vi theo dự án; hãy đối xử với chúng như mọi credential — chỉ backend, xoay vòng, không bao giờ trong client code. Checklist bảo mật API key chuẩn áp dụng đầy đủ.

Những sai lầm phổ biến khiến bạn tốn thời gian và tokens

Điểm chính: bốn sai lầm đặc thù của Gemini — tất cả đều được ghi lại trong các diễn đàn nhà cung cấp, tất cả đều tránh được.

Cái bẫy temperature. Thay đổi temperature với structured output ràng buộc schema sẽ âm thầm phá vỡ cam kết đầu ra. Luôn để mặc định, cho mọi lệnh gọi structured.
Thinking tokens không ngân sách. Đường thinking bị tính phí; một khối lượng phân loại bật thinking sẽ trả tiền cho suy luận nó không cần. Đặt ngân sách theo từng loại tác vụ.
Cache-key không ổn định. Nối timestamp hoặc đảo thứ tự các phần prompt sẽ giết chết cache hits. Thiết kế prefix prompt như một đơn vị ổn định; đo tỷ lệ hit như một metric.
Đi theo hướng dẫn năm 2024. Các hướng dẫn thời Gemini 1.5 mô tả tham số và model không còn tồn tại. Nếu hướng dẫn không nhắc đến model 3.x, đó là khảo cổ học — hãy kiểm tra tài liệu chính thức và ngày tháng của hướng dẫn này.

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

Gemini API có miễn phí không?

AI Studio có free tier cho thử nghiệm và prototyping, còn production tính phí theo token. Hạn mức miễn phí là thật và không cần thẻ — hãy dùng nó để đánh giá trước khi cam kết.

AI Studio hay Vertex AI — tôi nên dùng cái nào?

AI Studio cho prototyping và dự án cá nhân; Vertex AI cho governance doanh nghiệp, VPC và yêu cầu audit. Nếu bạn định tuyến qua một gateway hợp nhất, sự khác biệt gần như biến mất — một endpoint, cùng các model.

Context caching của Gemini có thực sự ~0.1× không?

Có — cached input tokens được tính phí khoảng một phần mười mức giá chuẩn. Điểm mấu chốt là độ ổn định của key: cache chỉ trúng trên prefix token chính xác, nên cấu trúc prompt ổn định là toàn bộ trò chơi.

Tôi có thể dùng OpenAI SDK với Gemini không?

Có — Google cung cấp một endpoint tương thích OpenAI, nên chỉ cần đổi base_url và code hiện có gần như chạy ngay. Một gateway hợp nhất mang lại cùng sự tương thích với một đầu mối thanh toán duy nhất.

Khi nào thinking mode đáng dùng?

Cho suy luận phức tạp, sinh code và tác vụ nhiều bước — được đo bằng bộ eval của bạn. Cho phân loại, trích xuất và bất cứ thứ gì có câu trả lời giới hạn, đường non-thinking nhanh hơn và rẻ hơn, thường với chất lượng tương đương.

Structured output của Gemini ổn định đến mức nào?

Ổn định khi bạn tuân theo hai quy tắc: ràng buộc schema và giữ temperature ở mặc định. Vi phạm một trong hai là bạn gặp tình trạng sai lệch âm thầm — cùng chế độ lỗi mà structured output của mọi nhà cung cấp đều có, được ghi lại trong bài so sánh JSON mode được liên kết ở trên.

Tóm tắt

Gemini API trong năm 2026 là một nền tảng Flash-first: giá giảm gần một nửa trên model Flash hiện tại, free tier thật sự, cơ chế kinh tế cache ~0.1×, multimodal gốc và grounding tích hợp sẵn — với sáu điểm khác biệt là các cấu hình, không phải dự án. Bắt đầu trong AI Studio, log usage từ request đầu tiên, ngân sách cho thinking tokens, giữ cache keys ổn định và eval trước khi chuyển đổi. Sau đó nó chỉ là một model xuất sắc nữa đứng sau endpoint hợp nhất của bạn.

Năm phút đến những Gemini tokens đầu tiên — không cần tài khoản Google Cloud. Nhận TokSpan API key của bạn và gọi Gemini bằng SDK bạn đang dùng; $5 tín dụng miễn phí đủ cho cả hướng dẫn.