Hướng Dẫn Sử Dụng Google Gemini 3 API: Khám Phá Sức Mạnh AI Cho Người Mới Bắt Đầu

Nếu bạn đã theo dõi các phát triển AI trong năm 2025, bạn có thể đã nghe rất nhiều về Google Gemini 3, mô hình AI đa phương thức thế hệ tiếp theo được thiết kế để cạnh tranh (và đôi khi vượt trội) GPT-5. Cho dù bạn là kỹ sư phần mềm, người sáng lập startup, người đam mê AI, hay chỉ đơn giản là người tò mò về những gì Gemini 3 có thể làm, việc học cách làm việc với API Google Gemini 3 sẽ mở ra cánh cửa để xây dựng các ứng dụng thông minh hơn và năng động hơn rất nhiều. Nhưng thành thật mà nói; tài liệu của Google có thể hơi khó hiểu nếu bạn mới bắt đầu. Vì vậy, trong hướng dẫn này, chúng tôi sẽ phân tích mọi thứ một cách rõ ràng, thân thiện và dễ hiểu cho người mới bắt đầu.

💡

Nếu bạn muốn một cách dễ dàng, trực quan, không cần viết mã để kiểm tra các điểm cuối API REST của Gemini 3, hãy sử dụng Apidog. Bạn có thể tải xuống Apidog miễn phí, và nó cho phép bạn thiết kế, gỡ lỗi và kiểm tra các lệnh gọi API mà không cần viết toàn bộ script. Vì hướng dẫn này bao gồm các ví dụ về API REST, bạn sẽ thấy Apidog cực kỳ tiện dụng khi thử nghiệm.

nút

Giờ đây, hãy cùng khai phá sức mạnh của mô hình AI tiên tiến nhất của Google!

Google Gemini 3 là gì?

Google Gemini 3 là mô hình mới nhất trong dòng sản phẩm AI đa phương thức của Google. Không giống như các mô hình trước đó, Gemini 3 được tối ưu hóa cho:

lập luận và giải quyết vấn đề
đầu vào/đầu ra đa phương thức (văn bản, hình ảnh, âm thanh, nhúng video)
sử dụng công cụ và quy trình làm việc tác nhân
suy luận nhanh với các điểm cuối độ trễ thấp
chuyển đổi mô hình động tùy thuộc vào tác vụ của bạn

Nhưng điểm nổi bật lớn nhất là đây:

Gemini 3 giới thiệu hai “chế độ tư duy” chính:

Tham số thinking_level kiểm soát độ sâu tối đa của quá trình lập luận nội bộ của mô hình trước khi nó đưa ra phản hồi. Gemini 3 coi các cấp độ này là các mức cho phép tương đối cho việc tư duy chứ không phải là sự đảm bảo nghiêm ngặt về token. Nếu thinking_level không được chỉ định, Gemini 3 Pro sẽ mặc định là high.

Tư duy Cao/Năng động: Tối đa hóa độ sâu lập luận. Mô hình có thể mất nhiều thời gian hơn đáng kể để tạo ra token đầu tiên, nhưng kết quả đầu ra sẽ được lập luận cẩn thận hơn.
Tư duy Thấp: Giảm thiểu độ trễ và chi phí. Tốt nhất cho việc tuân thủ hướng dẫn đơn giản, trò chuyện hoặc các ứng dụng thông lượng cao.

Nhiều người mới bắt đầu chưa biết điều này, nhưng việc chọn chế độ chính xác cải thiện đáng kể chất lượng đầu ra và giúp bạn kiểm soát chi phí của mình.

Chúng ta sẽ tìm hiểu cách chọn chế độ bằng API ngay sau đây.

Tại sao nên sử dụng API Gemini 3 thay vì công cụ giao diện người dùng?

Chắc chắn, bạn có thể sử dụng Gemini trong Google AI Studio. Nhưng nếu bạn muốn:

xây dựng ứng dụng
tự động hóa tác vụ
tích hợp mô hình vào quy trình làm việc
tạo chatbot
xử lý dữ liệu
đào tạo tác nhân
thực hiện các tác vụ đa phương thức

bạn sẽ cần API Gemini 3.

Hướng dẫn này tập trung vào API REST vì:

nó dễ dàng hơn cho người mới bắt đầu
không cần thư viện client
bạn có thể kiểm tra nhanh chóng trong Apidog hoặc Postman
nó hoạt động trong mọi môi trường backend

Cách API Gemini 3 hoạt động (Tổng quan đơn giản)

Mặc dù Gemini có các khả năng tiên tiến, bản thân API khá đơn giản.

Bạn gửi một yêu cầu POST tới…

<https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:generateContent?key=YOUR_API_KEY>

Bạn bao gồm JSON như:

lời nhắc văn bản
danh sách tin nhắn (tùy chọn)
cài đặt mô hình
cài đặt an toàn

Bạn nhận được…

văn bản đầu ra của mô hình
cấu trúc lập luận (đối với tư duy Cao/Năng động)
trích dẫn
siêu dữ liệu
đối tượng đa phương thức (nếu có)

Khi bạn hiểu cấu trúc này, mọi thứ khác sẽ trở nên dễ dàng hơn.

Bắt đầu: Các bước đầu tiên của bạn với API Gemini

Bước 1: Lấy khóa API của bạn

Hãy coi khóa API của bạn như một mật khẩu đặc biệt nói với Google, "Vâng, tôi được phép sử dụng Gemini." Dưới đây là cách lấy một khóa:

Truy cập Google AI Studio
Đăng nhập bằng tài khoản Google của bạn
Nhấp vào "Tạo khóa API" ở thanh bên trái
Đặt tên cho khóa của bạn và tạo nó
Sao chép và lưu khóa này ở nơi an toàn! Bạn sẽ không thể xem lại nó.

Quan trọng: Không bao giờ chia sẻ khóa API của bạn hoặc đưa nó vào các kho mã công khai. Hãy coi nó như mật khẩu của bạn.

Bước 2: Chọn Phương pháp của bạn

Bạn có thể tương tác với Gemini theo hai cách chính:

API REST: Phương pháp phổ biến. Hoạt động với bất kỳ ngôn ngữ lập trình nào có thể thực hiện yêu cầu HTTP. Chúng tôi sẽ tập trung vào phương pháp này.
SDK chính thức: Google cung cấp các thư viện tiện lợi cho Python, Node.js và các ngôn ngữ khác để xử lý các chi tiết HTTP cho bạn.

Vì chúng ta đang tập trung vào những điều cơ bản, chúng ta sẽ sử dụng phương pháp API REST, nó hoạt động ở mọi nơi và giúp bạn hiểu những gì đang xảy ra bên trong.

Hiểu các Chế độ tư duy của Gemini

Một trong những tính năng mạnh mẽ nhất của Gemini là khả năng hoạt động ở các "chế độ tư duy" khác nhau. Điều này không chỉ là tiếp thị mà nó thay đổi cơ bản cách mô hình xử lý yêu cầu của bạn.

Tư duy Thấp (Kẻ cuồng tốc)

Khi nào sử dụng: Đối với các tác vụ đơn giản, phản hồi nhanh và khi bạn đang tối ưu hóa tốc độ và chi phí.

Tốc độ: Phản hồi rất nhanh
Chi phí: Phải chăng hơn
Các trường hợp sử dụng: Hỏi đáp đơn giản, phân loại văn bản, tóm tắt cơ bản, dịch thuật trực tiếp

Ví dụ:

gemini-3-flash
gemini-3-mini

Hãy nghĩ về chế độ Tư duy Thấp như một cuộc trò chuyện nhanh với một người bạn hiểu biết, người đưa ra câu trả lời ngay lập tức.

Tư duy Cao/Năng động (Nhà phân tích chu đáo)

Khi nào sử dụng: Đối với lập luận phức tạp, các vấn đề nhiều bước và các tác vụ yêu cầu phân tích sâu sắc.

Tốc độ: Chậm hơn (nó "suy nghĩ" nhiều hơn trước khi phản hồi)
Chi phí: Đắt hơn
Các trường hợp sử dụng: Các bài toán phức tạp, lập luận logic, gỡ lỗi mã, viết sáng tạo, lập kế hoạch chiến lược

Tư duy Cao/Năng động giống như tham khảo ý kiến của một chuyên gia, người dành thời gian để xem xét mọi khía cạnh trước khi đưa ra câu trả lời có lý lẽ rõ ràng.

Ví dụ:

gemini-3-pro
gemini-3-pro-thinking

Những mô hình này cung cấp khả năng lập luận sâu sắc hơn, cửa sổ chú ý dài hơn và khả năng lập kế hoạch tốt hơn.

Điều tuyệt vời là bạn có thể chọn cả hai mô hình: Tư duy Cao/Năng động và Tư duy Thấp tùy thuộc vào nhu cầu cụ thể của bạn. Đối với hầu hết các ứng dụng đơn giản, Tư duy Thấp là hoàn hảo. Khi bạn cần lập luận sâu sắc hơn, hãy chuyển sang Tư duy Cao.

Theo nguyên tắc chung:

Loại tác vụ	Chế độ mô hình
Nghiên cứu	Tư duy Cao/Năng động
Toán/Logic	Tư duy Cao/Năng động
Tạo mã	Tư duy Cao/Năng động
Trò chuyện khách hàng	Tư duy Thấp
Tạo văn bản cơ bản	Tư duy Thấp
Trợ lý UI	Tư duy Thấp
Ứng dụng thời gian thực	Tư duy Thấp

Chúng tôi sẽ chỉ cho bạn cách chọn từng mô hình trong API REST.

Xây dựng lệnh gọi API REST Gemini 3 đầu tiên của bạn

Hãy bắt đầu với ví dụ đơn giản nhất có thể.

Điểm cuối (Endpoint)

POST <https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro:generateContent?key=YOUR_API_KEY>

Ví dụ thân yêu cầu (JSON)

{
  "contents": [
    { "role": "user",
      "parts": [{ "text": "Giải thích cách máy bay bay." }]
    }
  ]
}

Lệnh Curl mẫu

curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "Giải thích cách máy bay bay." }]
      }
    ]
  }' \\
"<https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro:generateContent?key=YOUR_API_KEY>"

Sử dụng Chế độ tư duy Cao/Năng động

Để kích hoạt chế độ lập luận, bạn phải sử dụng một mô hình hỗ trợ nó như gemini-3-pro-thinking.

Ví dụ API REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Tìm điều kiện chạy đua trong đoạn mã C++ đa luồng này: [mã ở đây]"}]
    }]
  }'

Khi sử dụng chế độ Tư duy Cao/Năng động, bạn thường sẽ nhận được:

cấu trúc chuỗi suy nghĩ (ẩn trừ khi được yêu cầu)
câu trả lời mạch lạc hơn
thời gian phản hồi chậm hơn
chi phí suy luận đắt hơn

Tôi khuyên bạn chỉ nên sử dụng chế độ này khi thực sự cần thiết, như lập luận dài dòng hoặc lập kế hoạch mã.

Sử dụng Chế độ tư duy Thấp

Các mô hình Tư duy Thấp được tối ưu hóa cho tốc độ và hoàn hảo cho:

tự động hoàn thành
tin nhắn ngắn
phản hồi UI
trợ lý nhỏ
các tính năng phụ của chatbot

Ví dụ API REST sử dụng “Flash”

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "AI hoạt động như thế nào?"}]
    }],
    "generationConfig": {
        thinkingConfig: {
          thinkingLevel: "low"
      }
    }
  }'

Các mô hình Tư duy Thấp có chi phí thấp hơn nhiều và trả về phản hồi gần như ngay lập tức.

Xử lý đầu vào đa phương thức (Hình ảnh, PDF, Âm thanh, Video)

Gemini 3 giới thiệu khả năng kiểm soát chi tiết quá trình xử lý hình ảnh đa phương thức thông qua tham số media_resolution. Độ phân giải cao hơn cải thiện khả năng đọc văn bản nhỏ hoặc nhận dạng chi tiết nhỏ của mô hình, nhưng làm tăng mức sử dụng token và độ trễ. Tham số media_resolution xác định số lượng token tối đa được phân bổ cho mỗi hình ảnh hoặc khung video đầu vào.

Bây giờ bạn có thể đặt độ phân giải thành media_resolution_low, media_resolution_medium, hoặc media_resolution_high cho từng phần phương tiện riêng lẻ hoặc toàn cầu (thông qua generation_config). Nếu không được chỉ định, mô hình sẽ sử dụng các giá trị mặc định tối ưu dựa trên loại phương tiện.

Gemini 3 hỗ trợ nhúng đa phương thức trên:

hình ảnh
âm thanh
khung video
tài liệu

Ví dụ để tải lên một hình ảnh (base64):

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "Hình ảnh này có gì?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Kiểm tra và Gỡ lỗi với Apidog

Trong khi các lệnh curl rất tốt cho các thử nghiệm nhanh, chúng trở nên cồng kềnh khi bạn phát triển một ứng dụng thực sự. Đây là lúc Apidog tỏa sáng.

Với Apidog, bạn có thể:

Lưu cấu hình API của bạn: Thiết lập điểm cuối Gemini và khóa API của bạn một lần, sau đó sử dụng lại nó trong tất cả các thử nghiệm của bạn.
Tạo mẫu yêu cầu: Lưu các loại lời nhắc khác nhau (bắt đầu cuộc trò chuyện, yêu cầu phân tích, viết sáng tạo) dưới dạng mẫu.
Kiểm tra các chế độ tư duy song song: Dễ dàng chuyển đổi giữa các chế độ Tư duy Thấp và Cao để so sánh phản hồi và hiệu suất.
Quản lý lịch sử cuộc trò chuyện: Sử dụng các biến môi trường của Apidog để duy trì ngữ cảnh cuộc trò chuyện trên nhiều yêu cầu.
Tự động hóa kiểm thử: Tạo các bộ kiểm thử để xác minh rằng tích hợp Gemini của bạn đang hoạt động chính xác.

nút

Dưới đây là cách bạn có thể thiết lập một yêu cầu Gemini trong Apidog:

Tạo một yêu cầu POST mới tới: https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key={{api_key}}
Thiết lập một biến môi trường api_key với khóa API thực tế của bạn
Trong phần thân, sử dụng JSON:

{
  "contents": [{
    "parts": [{
      "text": "{{prompt}}"
    }]
  }],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 800
  }
}

4. Đặt một biến môi trường khác prompt với bất cứ điều gì bạn muốn hỏi Gemini

Cách tiếp cận này giúp việc thử nghiệm nhanh hơn và có tổ chức hơn nhiều.

Các phương pháp hay nhất cho API Gemini

1. Xử lý lỗi một cách duyên dáng

Các lệnh gọi API có thể thất bại vì nhiều lý do. Luôn kiểm tra trạng thái phản hồi và xử lý lỗi một cách thích hợp. Bảng sau liệt kê các mã lỗi backend phổ biến mà bạn có thể gặp phải, cùng với giải thích về nguyên nhân và các bước khắc phục sự cố:

2. Quản lý chi phí của bạn

Việc sử dụng API Gemini được tính phí và tốn tiền (sau giới hạn miễn phí). Hãy ghi nhớ những mẹo này:

Bắt đầu với gói miễn phí để thử nghiệm
Sử dụng chế độ Tư duy Thấp khi có thể cho các tác vụ đơn giản
Đặt giới hạn maxOutputTokens hợp lý
Theo dõi mức sử dụng của bạn trong Google AI Studio

Token có thể là các ký tự đơn lẻ như z hoặc toàn bộ từ như cat. Các từ dài được chia thành nhiều token. Tập hợp tất cả các token được mô hình sử dụng được gọi là từ vựng, và quá trình chia văn bản thành các token được gọi là tokenization.

Khi tính phí được bật, chi phí của một lệnh gọi tới API Gemini được xác định một phần bởi số lượng token đầu vào và đầu ra, vì vậy biết cách đếm token có thể hữu ích.

3. Tạo lời nhắc tốt hơn

Chất lượng đầu ra của bạn phụ thuộc rất nhiều vào đầu vào của bạn. Dưới đây là một số mẹo về kỹ thuật nhắc:

Thay vì: "Viết về chó"

Hãy thử: "Viết một bài blog giáo dục dài 200 từ về lợi ích của việc nhận nuôi chó cứu hộ, được viết bằng giọng điệu thân thiện và khuyến khích cho những người nuôi thú cưng tiềm năng."

Thay vì: "Sửa mã này"

Hãy thử: "Vui lòng gỡ lỗi hàm Python này lẽ ra phải tính giai thừa nhưng lại trả về kết quả không chính xác cho đầu vào 5. Giải thích lỗi và cung cấp mã đã sửa."

4. Chọn mô hình phù hợp

Google cung cấp một số mô hình Gemini, mỗi mô hình có những điểm mạnh khác nhau. Xác minh rằng các tham số mô hình của bạn nằm trong các giá trị sau:

Bắt đầu với gemini-1.5-flash và chỉ nâng cấp nếu bạn cần khả năng lập luận cao hơn. Ngoài việc kiểm tra các giá trị tham số, hãy đảm bảo bạn đang sử dụng đúng phiên bản API (ví dụ: /v1 hoặc /v1beta) và mô hình hỗ trợ các tính năng bạn cần. Ví dụ: nếu một tính năng đang ở bản phát hành Beta, nó sẽ chỉ có sẵn trong phiên bản API /v1beta.

Kết luận: Hành trình AI của bạn bắt đầu

Bây giờ bạn đã có mọi thứ cần thiết để bắt đầu xây dựng với API Google Gemini. Bạn đã học cách lấy khóa API, thực hiện các yêu cầu cơ bản, hiểu các chế độ tư duy khác nhau và thậm chí đã thấy một số ví dụ nâng cao.

Hãy nhớ rằng làm việc với API AI là một quá trình lặp đi lặp lại. Bạn sẽ trở nên tốt hơn trong việc tạo lời nhắc và chọn cài đặt phù hợp bằng cách thực hành. Đừng ngại thử nghiệm, đó là cách bạn sẽ khám phá toàn bộ tiềm năng của những gì bạn có thể xây dựng.

Bước tiếp theo quan trọng nhất là bắt đầu thử nghiệm. Lấy các ví dụ trong hướng dẫn này, sửa đổi chúng, làm hỏng chúng và xem điều gì xảy ra. Cách tốt nhất để học là làm.

Đối với người mới bắt đầu, tôi đặc biệt khuyên bạn nên sử dụng Apidog làm công cụ kiểm thử API REST của bạn. Nó giúp bạn:

gỡ lỗi yêu cầu
lưu trữ các biến môi trường
chạy các bộ sưu tập
nhanh chóng so sánh kết quả của mô hình
chia sẻ các trường hợp kiểm thử API của bạn với đồng đội

Và vì nó miễn phí, không có bất kỳ nhược điểm nào.

nút