Tài liệu tham khảo API này mô tả các API tiêu chuẩn, API truyền phát trực tiếp và API theo thời gian thực mà bạn có thể dùng để tương tác với các mô hình Gemini. Bạn có thể sử dụng REST API trong mọi môi trường hỗ trợ các yêu cầu HTTP. Hãy tham khảo Hướng dẫn bắt đầu nhanh để biết cách bắt đầu với lệnh gọi API đầu tiên. Nếu bạn đang tìm tài liệu tham khảo cho các thư viện và SDK dành riêng cho ngôn ngữ của chúng tôi, hãy chuyển đến đường liên kết cho ngôn ngữ đó trong trình đơn điều hướng bên trái ở mục Tài liệu tham khảo về SDK.
Điểm cuối chính
Gemini API được sắp xếp theo các điểm cuối chính sau:
- Tạo nội dung tiêu chuẩn (
generateContent): Một điểm cuối REST tiêu chuẩn xử lý yêu cầu của bạn và trả về toàn bộ phản hồi của mô hình trong một gói duy nhất. Điều này phù hợp nhất với các tác vụ không tương tác mà bạn có thể chờ toàn bộ kết quả. - Tạo nội dung phát trực tuyến (
streamGenerateContent): Sử dụng Sự kiện do máy chủ gửi (SSE) để gửi các đoạn phản hồi cho bạn khi chúng được tạo. Điều này mang lại trải nghiệm nhanh hơn và giàu tính tương tác hơn cho các ứng dụng như chatbot. - Live API (
BidiGenerateContent): Một API dựa trên WebSocket có trạng thái để phát trực tuyến hai chiều, được thiết kế cho các trường hợp sử dụng đàm thoại theo thời gian thực. - Chế độ hàng loạt (
batchGenerateContent): Một điểm cuối REST tiêu chuẩn để gửi hàng loạt yêu cầugenerateContent. - Nhúng (
embedContent): Một điểm cuối REST tiêu chuẩn tạo ra vectơ nhúng văn bản từContentđầu vào. - Gen Media API: Các điểm cuối để tạo nội dung nghe nhìn bằng các mô hình chuyên biệt của chúng tôi, chẳng hạn như Imagen để tạo hình ảnh và Veo để tạo video.
Gemini cũng có sẵn những chức năng này mà bạn có thể truy cập bằng
generateContentAPI. - API nền tảng: Các điểm cuối tiện ích hỗ trợ các chức năng cốt lõi như tải tệp lên và đếm mã thông báo.
Xác thực
Tất cả các yêu cầu gửi đến Gemini API đều phải có tiêu đề x-goog-api-key kèm theo khoá API của bạn. Tạo một khoá chỉ bằng vài cú nhấp chuột trong Google AI Studio.
Sau đây là một yêu cầu mẫu có khoá API trong tiêu đề:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works in a few words"
}
]
}
]
}'
Để biết hướng dẫn về cách truyền khoá đến API bằng Gemini SDK, hãy xem hướng dẫn Sử dụng khoá API Gemini.
Tạo nội dung
Đây là điểm cuối trung tâm để gửi câu lệnh đến mô hình. Có 2 điểm cuối để tạo nội dung, điểm khác biệt chính là cách bạn nhận phản hồi:
generateContent(REST): Nhận một yêu cầu và cung cấp một phản hồi duy nhất sau khi mô hình hoàn tất toàn bộ quá trình tạo.streamGenerateContent(SSE): Nhận chính xác yêu cầu, nhưng mô hình sẽ truyền trực tuyến các phần phản hồi khi chúng được tạo. Điều này giúp cải thiện trải nghiệm người dùng cho các ứng dụng tương tác vì cho phép bạn hiển thị ngay kết quả một phần.
Cấu trúc nội dung yêu cầu
Nội dung yêu cầu là một đối tượng JSON giống hệt nhau đối với cả chế độ tiêu chuẩn và chế độ truyền phát trực tiếp, đồng thời được tạo từ một số đối tượng cốt lõi:
- Đối tượng
Content: Đại diện cho một lượt trong cuộc trò chuyện. - Đối tượng
Part: Một phần dữ liệu trong lượtContent(chẳng hạn như văn bản hoặc hình ảnh). inline_data(Blob): Vùng chứa cho các byte nội dung nghe nhìn thô và loại MIME của chúng.
Ở cấp cao nhất, phần nội dung yêu cầu chứa một đối tượng contents, đây là danh sách các đối tượng Content, mỗi đối tượng đại diện cho lượt trong cuộc trò chuyện. Trong hầu hết các trường hợp, để tạo văn bản cơ bản, bạn sẽ có một đối tượng Content duy nhất, nhưng nếu muốn duy trì nhật ký trò chuyện, bạn có thể sử dụng nhiều đối tượng Content.
Sau đây là nội dung yêu cầu generateContent điển hình:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
// A list of Part objects goes here
]
},
{
"role": "model",
"parts": [
// A list of Part objects goes here
]
}
]
}'
Cấu trúc nội dung phản hồi
Nội dung phản hồi tương tự cho cả chế độ phát trực tuyến và chế độ tiêu chuẩn, ngoại trừ những điểm sau:
- Chế độ tiêu chuẩn: Nội dung phản hồi chứa một phiên bản của
GenerateContentResponse. - Chế độ truyền phát trực tiếp: Nội dung phản hồi chứa một luồng các thực thể
GenerateContentResponse.
Nhìn chung, phần nội dung phản hồi chứa một đối tượng candidates, là danh sách các đối tượng Candidate. Đối tượng Candidate chứa một đối tượng Content có phản hồi được tạo và trả về từ mô hình.
Yêu cầu ví dụ
Các ví dụ sau đây cho thấy cách các thành phần này kết hợp với nhau cho nhiều loại yêu cầu.
Câu lệnh chỉ có văn bản
Một câu lệnh đơn giản dạng văn bản bao gồm một mảng contents có một đối tượng Content. Đến lượt mảng parts của đối tượng đó chứa một đối tượng Part duy nhất có trường text.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works in a single paragraph."
}
]
}
]
}'
Câu lệnh đa phương thức (văn bản và hình ảnh)
Để cung cấp cả văn bản và hình ảnh trong một câu lệnh, mảng parts phải chứa hai đối tượng Part: một cho văn bản và một cho hình ảnh inline_data.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
}
},
{"text": "What is in this picture?"},
]
}]
}'
Cuộc trò chuyện nhiều lượt (chat)
Để tạo một cuộc trò chuyện có nhiều lượt, bạn hãy xác định mảng contents bằng nhiều đối tượng Content. API sẽ sử dụng toàn bộ nhật ký này làm ngữ cảnh cho phản hồi tiếp theo. role cho mỗi đối tượng Content phải thay đổi giữa user và model.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Hello." }
]
},
{
"role": "model",
"parts": [
{ "text": "Hello! How can I help you today?" }
]
},
{
"role": "user",
"parts": [
{ "text": "Please write a four-line poem about the ocean." }
]
}
]
}'
Những điểm chính cần ghi nhớ
Contentlà phong bì: Đây là vùng chứa cấp cao nhất cho một lượt tương tác trong tin nhắn, cho dù đó là từ người dùng hay mô hình.Partcho phép đa phương thức: Sử dụng nhiều đối tượngParttrong một đối tượngContentđể kết hợp nhiều loại dữ liệu (văn bản, hình ảnh, URI video, v.v.).- Chọn phương thức dữ liệu:
- Đối với nội dung nghe nhìn nhỏ, được nhúng trực tiếp (như hầu hết hình ảnh), hãy sử dụng
Partvớiinline_data. - Đối với các tệp lớn hơn hoặc tệp mà bạn muốn sử dụng lại trên nhiều yêu cầu, hãy sử dụng File API để tải tệp lên và tham chiếu tệp đó bằng phần
file_data.
- Đối với nội dung nghe nhìn nhỏ, được nhúng trực tiếp (như hầu hết hình ảnh), hãy sử dụng
- Quản lý nhật ký trò chuyện: Đối với các ứng dụng trò chuyện sử dụng REST API, hãy tạo mảng
contentsbằng cách thêm các đối tượngContentcho mỗi lượt, luân phiên giữa các vai trò"user"và"model". Nếu bạn đang sử dụng một SDK, hãy tham khảo tài liệu SDK để biết cách quản lý nhật ký trò chuyện được đề xuất.
Ví dụ về phản hồi
Các ví dụ sau đây cho thấy cách các thành phần này kết hợp với nhau cho nhiều loại yêu cầu.
Câu trả lời chỉ bằng văn bản
Phản hồi văn bản đơn giản bao gồm một mảng candidates có một hoặc nhiều đối tượng content chứa phản hồi của mô hình.
Sau đây là ví dụ về một phản hồi chuẩn:
{
"candidates": [
{
"content": {
"parts": [
{
"text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 1
}
],
}
Sau đây là chuỗi các phản hồi truyền trực tuyến. Mỗi phản hồi đều chứa một responseId liên kết toàn bộ phản hồi với nhau:
{
"candidates": [
{
"content": {
"parts": [
{
"text": "The image displays"
}
],
"role": "model"
},
"index": 0
}
],
"usageMetadata": {
"promptTokenCount": ...
},
"modelVersion": "gemini-2.5-flash-lite",
"responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}
...
{
"candidates": [
{
"content": {
"parts": [
{
"text": " the following materials:\n\n* **Wood:** The accordion and the violin are primarily"
}
],
"role": "model"
},
"index": 0
}
],
"usageMetadata": {
"promptTokenCount": ...
}
"modelVersion": "gemini-2.5-flash-lite",
"responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}
Live API (BidiGenerateContent) WebSockets API
Live API cung cấp một API dựa trên WebSocket có trạng thái để truyền phát trực tiếp hai chiều nhằm hỗ trợ các trường hợp sử dụng truyền phát trực tiếp theo thời gian thực. Bạn có thể xem hướng dẫn về Live API và tài liệu tham khảo về Live API để biết thêm thông tin chi tiết.
Mô hình chuyên biệt
Ngoài nhóm mô hình của Gemini, Gemini API còn cung cấp các điểm cuối cho các mô hình chuyên biệt như Imagen, Lyria và các mô hình nhúng. Bạn có thể xem các hướng dẫn này trong phần Mô hình.
Platform API
Các điểm cuối còn lại cho phép sử dụng thêm các chức năng với các điểm cuối chính đã mô tả cho đến nay. Hãy xem các chủ đề Chế độ hàng loạt và File API trong phần Hướng dẫn để tìm hiểu thêm.
Bước tiếp theo
Nếu bạn mới bắt đầu, hãy tham khảo các hướng dẫn sau đây để hiểu rõ mô hình lập trình Gemini API:
Bạn cũng có thể xem các hướng dẫn về chức năng để tìm hiểu về các tính năng của Gemini API và xem ví dụ về mã: