Định dạng trò chuyện Google Gemini (Tạo nội dung)
Tài liệu chính thức
📝 Giới thiệu
API Google Gemini hỗ trợ tạo nội dung bằng cách sử dụng hình ảnh, âm thanh, mã, công cụ, v.v. Khi có thông tin đầu vào, generateContentRequest sẽ tạo ra các phản hồi mô hình. Hỗ trợ tạo văn bản, hiểu hình ảnh, xử lý âm thanh, ngữ cảnh dài, thực thi mã, lược đồ JSON, gọi hàm và nhiều tính năng khác.
💡 Yêu cầu Ví dụ
Trò chuyện bằng văn bản cơ bản ✅
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[{"text": "Write a story about a magic backpack."}]
}]
}' 2> /dev/nullTrò chuyện phân tích hình ảnh ✅
# Use temporary file to save base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
# Use temporary file to save JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT
cat > "$TEMP_JSON" `<< EOF
{
"contents": [{
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
]
}]
}
EOF
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2>` /dev/nullGọi hàm ✅
cat > tools.json `<< EOF
{
"function_declarations": [
{
"name": "enable_lights",
"description": "Turn on the lighting system."
},
{
"name": "set_light_color",
"description": "Set the light color. Lights must be enabled for this to work.",
"parameters": {
"type": "object",
"properties": {
"rgb_hex": {
"type": "string",
"description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
}
},
"required": [
"rgb_hex"
]
}
},
{
"name": "stop_lights",
"description": "Turn off the lighting system."
}
]
}
EOF
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d @<(echo '
{
"system_instruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(cat tools.json)'],
"tool_config": {
"function_calling_config": {"mode": "auto"}
},
"contents": {
"role": "user",
"parts": {
"text": "Turn on the lights please."
}
}
}
') 2>`/dev/null |sed -n '/"content"/,/"finishReason"/p'Phản hồi lược đồ JSON ✅
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{
"parts":[
{"text": "List 5 popular cookie recipes"}
]
}],
"generationConfig": {
"response_mime_type": "application/json",
"response_schema": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"recipe_name": {"type":"STRING"},
}
}
}
}
}' 2> /dev/null | headXử lý âm thanh 🟡
Giới hạn tải lên tệp
Chỉ hỗ trợ upload âm thanh qua inline_data ở định dạng base64, không hỗ trợ
hỗ trợ file_data.file_uri hoặc API tệp.
# Use File API to upload audio data to API request
# Use base64 inline_data to upload audio data to API request
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Please describe this audio file."},
{"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"###Xử lý video 🟡
Giới hạn tải lên tệp
Chỉ hỗ trợ upload video qua inline_data ở định dạng base64, không hỗ trợ
hỗ trợ file_data.file_uri hoặc API tệp.
# Use File API to upload video data to API request
# Use base64 inline_data to upload video data to API request
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Transcribe the audio from this video and provide visual descriptions."},
{"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"Xử lý PDF 🟡
Giới hạn tải lên tệp
Các tập tin PDF chỉ có thể được tải lên dưới dạng base64 đến inline_data. file_data.file_uri
và API tệp không được hỗ trợ.
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# Upload a PDF to the API request with base64 inline_data
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")
echo $MIME_TYPE
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Can you add a few more lines to this poem?"},
{"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"Hộp thoại trò chuyện ✅
curl https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{"role":"user",
"parts":[{
"text": "Hello"}]},
{"role": "model",
"parts":[{
"text": "Great to meet you. What would you like to know?"}]},
{"role":"user",
"parts":[{
"text": "I have two dogs in my house. How many paws are in my house?"}]},
]
}' 2> /dev/null | grep "text"Phản hồi trực tuyến ✅
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"contents": [{
"parts": [{"text": "Write a story about a magic backpack"}]
}]
}'Thực thi mã ✅
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "Calculate the Fibonacci Sequence10item"}]
}],
"tools": [{
"codeExecution": {}
}]
}'Cấu hình thế hệ ✅
curl https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Explain how AI works"}
]
}],
"generationConfig": {
"stopSequences": [
"Title"
],
"temperature": 1.0,
"maxOutputTokens": 800,
"topP": 0.8,
"topK": 10
}
}' 2> /dev/null | grep "text"Cài đặt an toàn ✅
echo '{
"safetySettings": [
{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
],
"contents": [{
"parts":[{
"text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d @request.json 2> /dev/nullHướng dẫn hệ thống ✅
curl "https://88api.ai/v1beta/models/gemini-2.0-flash:generateContent?key=$API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
"parts": {
"text": "Hello there"}}}'📮 Yêu cầu
Điểm cuối
Tạo nội dung
POST https://88api.ai/v1beta/{model=models/*}:generateContentLuồng tạo nội dung
POST https://88api.ai/v1beta/{model=models/*}:streamGenerateContentPhương thức xác thực
Bao gồm khóa API trong URL yêu cầu:
?key=$API_KEYTrong đó $API_KEY là khóa Google AI API của bạn.
Tham số đường dẫn
model
- Kiểu: chuỗi
- Bắt buộc: có
Tên của mô hình để tạo số lần hoàn thành.
Định dạng: models/{model}, ví dụ: models/gemini-2.0-flash
Thông số nội dung yêu cầu
contents
- Kiểu: mảng
- Bắt buộc: có
Nội dung cuộc trò chuyện hiện tại với người mẫu. Đối với truy vấn một lượt, đây là một phiên bản duy nhất. Đối với các truy vấn nhiều lượt giống như trò chuyện, đây là trường lặp lại chứa lịch sử cuộc trò chuyện và yêu cầu mới nhất.
Content object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
parts | mảng | vâng | Các phần nội dung được sắp xếp hợp thành một tin nhắn duy nhất |
role | chuỗi | không | Người sản xuất nội dung trong cuộc trò chuyện. user, model, function, hoặc tool |
Part object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
text | chuỗi | không | Nội dung văn bản thuần túy |
inlineData | đối tượng | không | Dữ liệu byte phương tiện nội tuyến |
fileData | đối tượng | không | Tham chiếu URI tới tệp đã tải lên |
functionCall | đối tượng | không | Yêu cầu gọi hàm |
functionResponse | đối tượng | không | Phản hồi cuộc gọi chức năng |
executableCode | đối tượng | không | Mã thực thi |
codeExecutionResult | đối tượng | không | Kết quả thực thi mã |
InlineData object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
mimeType | chuỗi | vâng | Loại MIME phương tiện |
data | chuỗi | vâng | Dữ liệu phương tiện được mã hóa Base64 |
FileData object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
mimeType | chuỗi | vâng | Loại tệp MIME |
fileUri | chuỗi | vâng | URI tệp |
tools
- Kiểu: mảng
- Bắt buộc: không
Danh sách các công cụ mà mô hình có thể sử dụng để tạo phản hồi tiếp theo. Các công cụ được hỗ trợ bao gồm các chức năng và thực thi mã.
Tool object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
functionDeclarations | mảng | không | Danh sách khai báo hàm tùy chọn |
codeExecution | đối tượng | không | Cho phép mô hình thực thi mã |
FunctionDeclaration object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | chuỗi | vâng | Tên chức năng |
description | chuỗi | không | Mô tả chức năng |
parameters | đối tượng | không | Tham số hàm, ở định dạng Lược đồ JSON |
FunctionCall object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | chuỗi | vâng | Tên hàm cần gọi |
args | đối tượng | không | Cặp khóa-giá trị của đối số hàm |
FunctionResponse object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | chuỗi | vâng | Tên hàm được gọi |
response | đối tượng | vâng | Dữ liệu phản hồi của lệnh gọi hàm |
ExecutableCode object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
language | liệt kê | vâng | Ngôn ngữ lập trình của mã |
code | chuỗi | vâng | Mã để thực thi |
CodeExecutionResult object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
outcome | liệt kê | vâng | Trạng thái kết quả thực thi mã |
output | chuỗi | không | Nội dung đầu ra của quá trình thực thi mã |
CodeExecution object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
| Đối tượng trống | - | Đối tượng cấu hình trống để cho phép thực thi mã |
toolConfig
- Loại: đối tượng
- Bắt buộc: không
Cấu hình công cụ cho bất kỳ công cụ nào được chỉ định trong yêu cầu.
ToolConfig object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
functionCallingConfig | đối tượng | không | Cấu hình gọi hàm |
FunctionCallingConfig object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
mode | liệt kê | không | Chỉ định chế độ gọi hàm |
allowedFunctionNames | mảng | không | Danh sách tên hàm được phép gọi |
FunctionCallingMode enum values:
MODE_UNSPECIFIED: Chế độ mặc định, model quyết định có gọi hàm hay khôngAUTO: Model tự động quyết định khi nào gọi một hàmANY: Model phải gọi một hàmNONE: Model không gọi được hàm
safetySettings
- Kiểu: mảng
- Bắt buộc: không
Danh sách các trường hợp Cài đặt An toàn để lọc nội dung không an toàn.
SafetySetting object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
category | liệt kê | vâng | Hạng mục an toàn |
threshold | liệt kê | vâng | Ngưỡng chặn |
HarmCategory enum values:
HARM_CATEGORY_HARASSMENT: Nội dung quấy rốiHARM_CATEGORY_HATE_SPEECH: Lời nói và nội dung căm thùHARM_CATEGORY_SEXUALLY_EXPLICIT: Nội dung khiêu dâm rõ ràngHARM_CATEGORY_DANGEROUS_CONTENT: Nội dung nguy hiểmHARM_CATEGORY_CIVIC_INTEGRITY: Nội dung có thể được sử dụng để làm suy yếu sự liêm chính của công dân
HarmBlockThreshold enum values:
BLOCK_LOW_AND_ABOVE: Cho phép xuất bản nội dung có số điểm KHÔNG ĐÁNG GIÁBLOCK_MEDIUM_AND_ABOVE: Cho phép xuất bản nội dung có điểm KHÔNG ĐÁNG GIÁ và THẤPBLOCK_ONLY_HIGH: Cho phép xuất bản nội dung có mức độ rủi ro TUYỆT VỜI, THẤP và TRUNG BÌNHBLOCK_NONE: Cho phép tất cả nội dungOFF: Tắt bộ lọc an toàn
Complete HarmBlockThreshold enum values:
HARM_BLOCK_THRESHOLD_UNSPECIFIED: Ngưỡng chưa xác địnhBLOCK_LOW_AND_ABOVE: Chặn nội dung có hại với xác suất ở mức trung bình trở lên, chỉ cho phép nội dung ở mức độ KHÔNG THỂBLOCK_MEDIUM_AND_ABOVE: Chặn nội dung có hại với xác suất ở mức trung bình trở lên, cho phép nội dung ở mức độ THẤP và KHÔNG THỂBLOCK_ONLY_HIGH: Chỉ chặn nội dung có hại với xác suất cao, cho phép nội dung ở mức độ KHÔNG THỂ, THẤP và TRUNG BÌNHBLOCK_NONE: Không chặn bất kỳ nội dung nào, cho phép mọi cấp độOFF: Tắt hoàn toàn các bộ lọc an toàn
systemInstruction
- Loại: đối tượng (Nội dung)
- Bắt buộc: không
Hướng dẫn hệ thống do nhà phát triển đặt ra. Hiện tại chỉ hỗ trợ văn bản.
generationConfig
- Loại: đối tượng
- Bắt buộc: không
Tùy chọn cấu hình đầu ra và tạo mô hình.
GenerationConfig object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
stopSequences | mảng | không | Tập hợp các chuỗi ký tự để dừng tạo (tối đa 5) |
responseMimeType | chuỗi | không | Loại MIME của văn bản ứng viên được tạo |
responseSchema | đối tượng | không | Lược đồ đầu ra của văn bản ứng viên được tạo |
responseModalities | mảng | không | Phương thức phản hồi được yêu cầu |
candidateCount | số nguyên | không | Số lượng câu trả lời được tạo để trả về |
maxOutputTokens | số nguyên | không | Số lượng mã thông báo tối đa trong câu trả lời của ứng viên |
temperature | số | không | Kiểm soát tính ngẫu nhiên của đầu ra, phạm vi [0,0, 2,0] |
topP | số | không | Xác suất tích lũy giới hạn trên của mã thông báo cần xem xét trong quá trình lấy mẫu |
topK | số nguyên | không | Số lượng mã thông báo tối đa cần xem xét trong quá trình lấy mẫu |
seed | số nguyên | không | Seed dùng để giải mã |
presencePenalty | số | không | Hình phạt có mặt |
frequencyPenalty | số | không | Tần suất phạt |
responseLogprobs | boolean | không | Có xuất kết quả logprobs trong phản hồi hay không |
logprobs | số nguyên | không | Số lượng logprobs hàng đầu được trả về |
enableEnhancedCivicAnswers | boolean | không | Cho phép trả lời dịch vụ công dân nâng cao |
speechConfig | đối tượng | không | Cấu hình tạo giọng nói |
thinkingConfig | đối tượng | không | Cấu hình chức năng tư duy |
mediaResolution | liệt kê | không | Độ phân giải phương tiện được chỉ định |
Supported MIME types:
text/plain: (mặc định) Xuất văn bảnapplication/json: Phản hồi JSONtext/x.enum: ENUM dưới dạng phản hồi chuỗi
Modality enum values:
TEXT: Cho biết model nên trả về văn bảnIMAGE: Cho biết model sẽ trả về hình ảnhAUDIO: Cho biết model sẽ trả về âm thanh
Schema object properties:
| Bất động sản | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
type | liệt kê | vâng | Kiểu dữ liệu |
description | chuỗi | không | Mô tả trường |
enum | mảng | không | Danh sách các giá trị enum (khi loại là chuỗi) |
example | bất kỳ | không | Giá trị mẫu |
nullable | boolean | không | Liệu nó có thể là null |
format | chuỗi | không | Định dạng chuỗi (ví dụ: ngày, giờ) |
items | đối tượng | không | Lược đồ cho các mục mảng (khi kiểu là mảng) |
properties | đối tượng | không | Lược đồ cho thuộc tính đối tượng (khi loại là đối tượng) |
required | mảng | không | Danh sách tên thuộc tính bắt buộc |
minimum | số | không | Giá trị tối thiểu cho số |
maximum | số | không | Giá trị tối đa cho số |
minItems | số nguyên | không | Độ dài tối thiểu cho mảng |
maxItems | số nguyên | không | Độ dài tối đa cho mảng |
minLength | số nguyên | không | Độ dài tối thiểu cho chuỗi |
maxLength | số nguyên | không | Độ dài tối đa cho chuỗi |
Type enum values:
TYPE_UNSPECIFIED: Loại không xác địnhSTRING: Kiểu chuỗiNUMBER: Kiểu sốINTEGER: Kiểu số nguyênBOOLEAN: Kiểu BooleanARRAY: Kiểu mảngOBJECT: Loại đối tượng
Supported programming languages (ExecutableCode):
LANGUAGE_UNSPECIFIED: Ngôn ngữ không xác địnhPYTHON: Ngôn ngữ lập trình Python
Code execution result enum (Outcome):
OUTCOME_UNSPECIFIED: Kết quả không xác địnhOUTCOME_OK: Thực thi mã thành côngOUTCOME_FAILED: Thực thi mã không thành côngOUTCOME_DEADLINE_EXCEEDED: Hết thời gian thực thi mã
cachedContent
- Kiểu: chuỗi
- Bắt buộc: không
Tên của nội dung được lưu trong bộ nhớ đệm, được dùng làm ngữ cảnh để đưa ra dự đoán. Định dạng: cachedContents/{cachedContent}
📥 Phản hồi
Tạo phản hồi nội dung
Câu trả lời từ các mô hình hỗ trợ nhiều câu trả lời ứng viên. Hệ thống báo cáo xếp hạng an toàn và lọc nội dung cho lời nhắc và từng ứng viên.
candidates
- Kiểu: mảng
- Mô tả: Danh sách các câu trả lời thí sinh từ mô hình
Candidate object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
content | đối tượng | Nội dung được tạo được mô hình trả về |
finishReason | liệt kê | Lý do mô hình ngừng tạo token |
safetyRatings | mảng | Danh sách xếp hạng an toàn cho câu trả lời của ứng viên |
citationMetadata | đối tượng | Thông tin tham khảo cho ứng viên được tạo |
tokenCount | số nguyên | Số lượng mã thông báo cho ứng cử viên này |
groundingAttributions | mảng | Thông tin về các nguồn góp phần tạo ra câu trả lời có căn cứ |
groundingMetadata | đối tượng | Siêu dữ liệu tham chiếu cho đối tượng ứng cử viên |
avgLogprobs | số | Điểm xác suất log trung bình của ứng viên |
logprobsResult | đối tượng | Ghi lại điểm xác suất cho mã thông báo câu trả lời và mã thông báo trước đó |
urlRetrievalMetadata | đối tượng | Siêu dữ liệu liên quan đến công cụ truy xuất ngữ cảnh URL |
urlContextMetadata | đối tượng | Siêu dữ liệu liên quan đến công cụ truy xuất ngữ cảnh URL |
index | số nguyên | Danh sách ứng viên trong danh sách ứng viên phản hồi |
FinishReason enum values:
STOP: Điểm dừng tự nhiên hoặc chuỗi dừng được cung cấp cho mô hìnhMAX_TOKENS: Đã đạt đến giới hạn token tối đa được chỉ định trong yêu cầuSAFETY: Trả lời nội dung thí sinh được đánh dấu vì lý do an toànRECITATION: Nội dung thí sinh trả lời được đánh dấu vì lý do đọc thuộc lòngLANGUAGE: Nội dung thí sinh trả lời bị đánh dấu sử dụng ngôn ngữ không được hỗ trợOTHER: Không rõ nguyên nhânBLOCKLIST: Hoạt động tạo token bị dừng do nội dung chứa các từ bị cấmPROHIBITED_CONTENT: Hoạt động tạo token bị dừng do nội dung có thể chứa nội dung bị cấmSPII: Hoạt động tạo token bị dừng do nội dung có thể chứa thông tin cá nhân nhạy cảmMALFORMED_FUNCTION_CALL: Lệnh gọi hàm do mô hình tạo không hợp lệIMAGE_SAFETY: Việc tạo mã thông báo bị dừng do hình ảnh được tạo vi phạm quy tắc an toàn
promptFeedback
- Loại: đối tượng
- Mô tả: Phản hồi nhanh chóng liên quan đến lọc nội dung
PromptFeedback object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
blockReason | liệt kê | Lý do chặn lời nhắc |
safetyRatings | mảng | Đánh giá an toàn cho lời nhắc |
BlockReason enum values:
BLOCK_REASON_UNSPECIFIED: Giá trị mặc định, giá trị này không được sử dụngSAFETY: Hệ thống bị chặn nhắc nhở vì lý do an toànOTHER: Lời nhắc bị chặn không rõ nguyên nhânBLOCKLIST: Hệ thống đã chặn lời nhắc này vì nó chứa các thuật ngữ trong danh sách chặnPROHIBITED_CONTENT: Hệ thống đã chặn lời nhắc này vì nó chứa nội dung bị cấmIMAGE_SAFETY: Hình ảnh ứng viên bị chặn do phát sinh nội dung không an toàn
usageMetadata
- Loại: đối tượng
- Mô tả: Siêu dữ liệu về việc sử dụng mã thông báo cho yêu cầu tạo
UsageMetadata object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
promptTokenCount | số nguyên | Số lượng mã thông báo trong lời nhắc |
cachedContentTokenCount | số nguyên | Số lượng mã thông báo trong phần được lưu trong bộ nhớ cache của lời nhắc |
candidatesTokenCount | số nguyên | Tổng số mã thông báo trong tất cả các câu trả lời của ứng viên được tạo |
totalTokenCount | số nguyên | Tổng số mã thông báo cho yêu cầu tạo |
toolUsePromptTokenCount | số nguyên | Số mã thông báo trong lời nhắc sử dụng công cụ |
thoughtsTokenCount | số nguyên | Số lượng mã thông báo cho suy nghĩ của mô hình tư duy |
promptTokensDetails | mảng | Danh sách các phương thức được xử lý trong yêu cầu đầu vào |
candidatesTokensDetails | mảng | Danh sách các phương thức được trả về trong phản hồi |
cacheTokensDetails | mảng | Danh sách các phương thức trong nội dung được lưu trong bộ nhớ đệm của yêu cầu đầu vào |
toolUsePromptTokensDetails | mảng | Danh sách các phương thức được xử lý để sử dụng công cụ trong phần đầu vào yêu cầu |
modelVersion
- Kiểu: chuỗi
- Mô tả: Phiên bản mẫu dùng để tạo đáp án
responseId
- Kiểu: chuỗi
- Mô tả: ID cho mỗi phản hồi
Ví dụ về phản hồi đầy đủ
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Hello!I am Gemini,one by Google Developed artificial intelligence assistant。I can help you answer your questions、provide information、Assistance with writing、Various tasks such as coding and programming。Please tell me what I can do for you!"
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE",
"blocked": false
}
],
"tokenCount": 47
}
],
"promptFeedback": {
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 47,
"totalTokenCount": 51,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 47
}
]
},
"modelVersion": "gemini-2.0-flash",
"responseId": "response-12345"
}🔧 Tính năng nâng cao
Xếp hạng an toàn
SafetyRating object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
category | liệt kê | Hạng mục đánh giá này |
probability | liệt kê | Xác suất có hại cho nội dung này |
blocked | boolean | Liệu nội dung này có bị chặn do xếp hạng này hay không |
HarmProbability enum values:
NEGLIGIBLE: Xác suất có hại không đáng kểLOW: Xác suất có hại thấpMEDIUM: Phương tiện xác suất có hạiHIGH: Xác suất có hại cao
Siêu dữ liệu trích dẫn
CitationMetadata object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
citationSources | mảng | Nguồn tham khảo cho các câu trả lời cụ thể |
CitationSource object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
startIndex | số nguyên | Chỉ mục bắt đầu của phân đoạn phản hồi được quy cho nguồn này |
endIndex | số nguyên | Chỉ mục cuối cùng của thuộc tính (độc quyền) |
uri | chuỗi | URI được gán cho phần văn bản từ nguồn này |
license | chuỗi | Giấy phép của dự án GitHub được quy cho đoạn nguồn |
Thực thi mã
Khi các công cụ thực thi mã được bật, mô hình có thể tạo và thực thi mã để giải quyết vấn đề.
Code execution example response:
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Let me calculate the Fibonacci sequence10item:"
},
{
"executableCode": {
"language": "PYTHON",
"code": "def fibonacci(n):\n if n <= 1:\n return n\n else:\n return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'No.10The term Fibonacci number is: {result}')"
}
},
{
"codeExecutionResult": {
"outcome": "OK",
"output": "No.10The term Fibonacci number is: 55"
}
},
{
"text": "So the Fibonacci sequence number10The item is55。"
}
],
"role": "model"
},
"finishReason": "STOP"
}
]
}Nối đất
GroundingMetadata object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
groundingChunks | mảng | Danh sách tài liệu tham khảo hỗ trợ được lấy từ các nguồn nối đất được chỉ định |
groundingSupports | mảng | Danh sách hỗ trợ nối đất |
webSearchQueries | mảng | Truy vấn tìm kiếm trên web cho các tìm kiếm trên web tiếp theo |
searchEntryPoint | đối tượng | Điểm truy cập tìm kiếm của Google cho các tìm kiếm trên web tiếp theo |
retrievalMetadata | đối tượng | Siêu dữ liệu liên quan đến việc truy xuất trong quy trình cơ sở |
GroundingAttribution object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
sourceId | đối tượng | Mã định danh của nguồn đóng góp cho sự phân bổ này |
content | đối tượng | Nội dung của nguồn đóng góp cho sự ghi nhận này |
AttributionSourceId object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
groundingPassage | đối tượng | Mã định danh của đoạn được nhúng |
semanticRetrieverChunk | đối tượng | Mã định danh của Chunk được trích xuất bởi Semantic Retriever |
GroundingPassageId object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
passageId | chuỗi | ID của đoạn khớp với GroundingPassage.id từ GeneAnswerRequest |
partIndex | số nguyên | Chỉ mục của phần trong GroundingPassage.content |
SemanticRetrieverChunk object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
source | chuỗi | Tên nguồn khớp với SemanticRetrieverConfig.source từ yêu cầu |
chunk | chuỗi | Tên của Chunk chứa văn bản được gán |
SearchEntryPoint object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
renderedContent | chuỗi | Đoạn mã nội dung web có thể nhúng vào trang web hoặc ứng dụng WebView |
sdkBlob | chuỗi | JSON được mã hóa Base64, biểu thị một loạt cụm từ tìm kiếm và bộ URL tìm kiếm |
Segment object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
partIndex | số nguyên | Chỉ mục của đối tượng Part bên trong đối tượng Content cha của nó |
startIndex | số nguyên | Chỉ mục bắt đầu của phần đã cho tính bằng byte |
endIndex | số nguyên | Chỉ mục cuối của đoạn đã cho tính bằng byte |
text | chuỗi | Văn bản tương ứng với đoạn trong phản hồi |
RetrievalMetadata object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
googleSearchDynamicRetrievalScore | số | Điểm xác suất của thông tin tìm kiếm trên Google giúp trả lời câu hỏi nằm trong khoảng [0,1] |
GroundingChunk object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
web | đối tượng | Đoạn nối đất từ web |
Web object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
uri | chuỗi | Tham chiếu URI cho đoạn |
title | chuỗi | Tiêu đề của khối dữ liệu |
GroundingSupport object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
groundingChunkIndices | mảng | Danh sách các chỉ mục, được sử dụng để chỉ định các trích dẫn liên quan đến khiếu nại bản quyền |
confidenceScores | mảng | Điểm tin cậy đối với tài liệu tham khảo hỗ trợ, trong khoảng 0-1 |
segment | đối tượng | Phân đoạn nội dung chứa yêu cầu hỗ trợ này |
Xử lý đa phương thức
API Gemini hỗ trợ xử lý nhiều phương thức đầu vào và đầu ra:
Supported input modalities:
TEXT: Văn bản thuần túyIMAGE: Hình ảnh (JPEG, PNG, WebP, HEIC, HEIF)AUDIO: Âm thanh (WAV, MP3, AIFF, AAC, OGG, FLAC)VIDEO: Video (MP4, MPEG, MOV, AVI, FLV, MPG, WEBM, WMV, 3GPP)DOCUMENT: Tài liệu (PDF)
ModalityTokenCount object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
modality | liệt kê | Phương thức liên quan đến số lượng mã thông báo này |
tokenCount | số nguyên | Số lượng mã thông báo |
MediaResolution enum values:
MEDIA_RESOLUTION_LOW: Độ phân giải thấp (64 token)MEDIA_RESOLUTION_MEDIUM: Độ phân giải trung bình (256 token)MEDIA_RESOLUTION_HIGH: Độ phân giải cao (256 token để chia tỷ lệ và định khung lại)
Chức năng tư duy
ThinkingConfig object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
includeThoughts | boolean | Có nên đưa nội dung tư duy vào đáp án |
thinkingBudget | số nguyên | Số lượng mã thông báo ý tưởng mà mô hình sẽ tạo ra |
Tạo giọng nói
SpeechConfig object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
voiceConfig | đối tượng | Cấu hình cho đầu ra giọng nói đơn |
multiSpeakerVoiceConfig | đối tượng | Cấu hình cài đặt nhiều loa |
languageCode | chuỗi | Mã ngôn ngữ để tổng hợp giọng nói |
VoiceConfig object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
prebuiltVoiceConfig | đối tượng | Cấu hình cho giọng nói dựng sẵn để sử dụng |
PrebuiltVoiceConfig object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
voiceName | chuỗi | Tên của giọng nói dựng sẵn để sử dụng |
MultiSpeakerVoiceConfig object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
speakerVoiceConfigs | mảng | Tất cả giọng nói của loa được kích hoạt |
SpeakerVoiceConfig object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
speaker | chuỗi | Tên diễn giả sử dụng |
voiceConfig | đối tượng | Cấu hình cho giọng nói sử dụng |
Supported language codes:
zh-CN: Tiếng Trung (Giản thể)en-US: Tiếng Anh (Mỹ)ja-JP: tiếng Nhậtko-KR: tiếng Hànfr-FR: tiếng Phápde-DE: tiếng Đứces-ES: tiếng Tây Ban Nhapt-BR: Bồ Đào Nha (Brazil)hi-IN: Tiếng Hindiar-XA: tiếng Ả Rậpit-IT: Ýtr-TR: tiếng Thổ Nhĩ Kỳvi-VN: Tiếng Việtth-TH: Tháiru-RU: tiếng Ngapl-PL: tiếng Ba Lannl-NL: tiếng Hà Lan
Kết quả logprobs
LogprobsResult object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
topCandidates | mảng | Mảng ứng viên được sắp xếp theo log xác suất giảm dần |
chosenCandidates | mảng | Mảng các ứng cử viên được chọn, không nhất thiết phải nằm trong topCandidates (độ dài bằng tổng số bước giải mã) |
TopCandidates object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
candidates | mảng | Thí sinh sắp xếp theo log xác suất giảm dần |
Candidate (Logprobs) object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
token | chuỗi | Giá trị chuỗi mã thông báo cho ứng viên |
tokenId | số nguyên | Giá trị ID mã thông báo cho ứng viên |
logProbability | số | Đăng nhập xác suất cho ứng viên |
Chức năng truy xuất URL
UrlRetrievalMetadata object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
urlRetrievalContexts | mảng | Danh sách bối cảnh truy xuất URL |
UrlRetrievalContext object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
retrievedUrl | chuỗi | URL được công cụ lấy ra |
UrlContextMetadata object properties:
| Bất động sản | Loại | Mô tả |
|---|---|---|
urlMetadata | mảng | Danh sách ngữ cảnh URL |
UrlMetadata object properties:
| Tài sản | Loại | Mô tả |
|---|---|---|
retrievedUrl | chuỗi | URL được công cụ lấy ra |
urlRetrievalStatus | liệt kê | Trạng thái truy xuất URL |
UrlRetrievalStatus enum values:
URL_RETRIEVAL_STATUS_SUCCESS: Truy xuất URL thành côngURL_RETRIEVAL_STATUS_ERROR: Truy xuất URL không thành công do có lỗi
Danh mục tác hại hoàn chỉnh
HarmCategory enum values:
HARM_CATEGORY_UNSPECIFIED: Danh mục không được chỉ địnhHARM_CATEGORY_DEROGATORY: PaLM - Nhận xét tiêu cực hoặc có hại nhắm mục tiêu danh tính và/hoặc thuộc tính được bảo vệHARM_CATEGORY_TOXICITY: PaLM – Nội dung thô lỗ, bất lịch sự hoặc tục tĩuHARM_CATEGORY_VIOLENCE: PaLM – Kịch bản mô tả bạo lực đối với cá nhân hoặc nhómHARM_CATEGORY_SEXUAL: PaLM - Đề cập đến hành vi tình dục hoặc nội dung tục tĩu khácHARM_CATEGORY_MEDICAL: PaLM - Quảng bá lời khuyên y tế chưa được xác minhHARM_CATEGORY_DANGEROUS: PaLM - Nội dung nguy hiểm thúc đẩy, khuyến khích hoặc tạo điều kiện cho hành vi có hạiHARM_CATEGORY_HARASSMENT: Song Tử – Nội dung quấy rốiHARM_CATEGORY_HATE_SPEECH: Song Tử – Lời nói căm thù và nội dungHARM_CATEGORY_SEXUALLY_EXPLICIT: Song Tử – Nội dung khiêu dâm rõ ràngHARM_CATEGORY_DANGEROUS_CONTENT: Song Tử – Nội dung nguy hiểmHARM_CATEGORY_CIVIC_INTEGRITY: Gemini - Nội dung có thể được sử dụng để làm suy yếu sự liêm chính của công dân
HarmProbability enum values:
HARM_PROBABILITY_UNSPECIFIED: Xác suất không xác địnhNEGLIGIBLE: Xác suất có hại không đáng kểLOW: Xác suất có hại thấpMEDIUM: Phương tiện xác suất có hạiHIGH: Xác suất có hại cao
Modality enum values:
MODALITY_UNSPECIFIED: Phương thức không được chỉ địnhTEXT: Văn bản thuần túyIMAGE: Hình ảnhVIDEO: VideoAUDIO: Âm thanhDOCUMENT: Tài liệu, ví dụ: PDF
MediaResolution enum values:
MEDIA_RESOLUTION_UNSPECIFIED: Độ phân giải media chưa được thiết lậpMEDIA_RESOLUTION_LOW: Độ phân giải phương tiện được đặt ở mức thấp (64 token)MEDIA_RESOLUTION_MEDIUM: Độ phân giải phương tiện được đặt ở mức trung bình (256 token)MEDIA_RESOLUTION_HIGH: Độ phân giải phương tiện được đặt ở mức cao (sử dụng 256 token để chia tỷ lệ và định khung lại)
UrlRetrievalStatus enum values:
URL_RETRIEVAL_STATUS_UNSPECIFIED: Giá trị mặc định, giá trị này không được sử dụngURL_RETRIEVAL_STATUS_SUCCESS: Truy xuất URL thành côngURL_RETRIEVAL_STATUS_ERROR: Truy xuất URL không thành công do có lỗi
🔍 Xử lý lỗi
Mã lỗi phổ biến
| Mã Lỗi | Mô tả |
|---|---|
400 | Lỗi định dạng yêu cầu hoặc tham số không hợp lệ |
401 | Khóa API không hợp lệ hoặc bị thiếu |
403 | Không đủ quyền hoặc giới hạn hạn ngạch |
429 | Tần suất yêu cầu quá cao |
500 | Lỗi nội bộ máy chủ |
Giải thích chi tiết về mã lỗi
| Mã Lỗi | Trạng thái | Mô tả | Giải pháp |
|---|---|---|---|
400 | INVALID_ARGUMENT | Tham số yêu cầu không hợp lệ hoặc lỗi định dạng | Kiểm tra định dạng tham số yêu cầu và các trường bắt buộc |
400 | FAILED_PRECONDITION | Điều kiện tiên quyết cho yêu cầu không được đáp ứng | Đảm bảo đáp ứng các điều kiện tiên quyết của lệnh gọi API |
401 | UNAUTHENTICATED | Khóa API không hợp lệ, bị thiếu hoặc đã hết hạn | Kiểm tra tính hợp lệ và định dạng của khóa API |
403 | PERMISSION_DENIED | Không đủ quyền hoặc hết hạn ngạch | Kiểm tra quyền khóa API hoặc hạn ngạch nâng cấp |
404 | NOT_FOUND | Mô hình hoặc tài nguyên được chỉ định không tồn tại | Xác minh tên mô hình và đường dẫn tài nguyên |
413 | PAYLOAD_TOO_LARGE | Nội dung yêu cầu quá lớn | Giảm kích thước nội dung đầu vào hoặc xử lý theo đợt |
429 | RESOURCE_EXHAUSTED | Đã vượt quá tần suất yêu cầu hoặc không đủ hạn mức | Giảm tần suất yêu cầu hoặc chờ thiết lập lại hạn ngạch |
500 | INTERNAL | Lỗi nội bộ máy chủ | Hãy thử lại yêu cầu, nếu liên tục liên hệ với bộ phận hỗ trợ |
503 | UNAVAILABLE | Dịch vụ tạm thời không có | Đợi một khoảng thời gian và thử lại |
504 | DEADLINE_EXCEEDED | Yêu cầu đã hết thời gian chờ | Giảm kích thước đầu vào hoặc thử lại yêu cầu |
Ví dụ về phản hồi lỗi
{
"error": {
"code": 400,
"message": "Invalid argument: contents",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "contents",
"description": "contents is required"
}
]
}
]
}
}