88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Chat

Đị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/null

Trò 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/null

Gọ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 | head

Xử 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/null

Hướ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/*}:generateContent

Luồng tạo nội dung

POST https://88api.ai/v1beta/{model=models/*}:streamGenerateContent

Phương thức xác thực

Bao gồm khóa API trong URL yêu cầu:

?key=$API_KEY

Trong đó $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ảnLoạiBắt buộcMô tả
partsmảngvângCác phần nội dung được sắp xếp hợp thành một tin nhắn duy nhất
rolechuỗikhôngNgườ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ảnLoạiBắt buộcMô tả
textchuỗikhôngNội dung văn bản thuần túy
inlineDatađối tượngkhôngDữ liệu byte phương tiện nội tuyến
fileDatađối tượngkhôngTham chiếu URI tới tệp đã tải lên
functionCallđối tượngkhôngYêu cầu gọi hàm
functionResponseđối tượngkhôngPhản hồi cuộc gọi chức năng
executableCodeđối tượngkhôngMã thực thi
codeExecutionResultđối tượngkhôngKết quả thực thi mã

InlineData object properties:

Bất động sảnLoạiBắt buộcMô tả
mimeTypechuỗivângLoại MIME phương tiện
datachuỗivângDữ liệu phương tiện được mã hóa Base64

FileData object properties:

Bất động sảnLoạiBắt buộcMô tả
mimeTypechuỗivângLoại tệp MIME
fileUrichuỗivângURI 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ảnLoạiBắt buộcMô tả
functionDeclarationsmảngkhôngDanh sách khai báo hàm tùy chọn
codeExecutionđối tượngkhôngCho phép mô hình thực thi mã

FunctionDeclaration object properties:

Bất động sảnLoạiBắt buộcMô tả
namechuỗivângTên chức năng
descriptionchuỗikhôngMô tả chức năng
parametersđối tượngkhôngTham số hàm, ở định dạng Lược đồ JSON

FunctionCall object properties:

Bất động sảnLoạiBắt buộcMô tả
namechuỗivângTên hàm cần gọi
argsđối tượngkhôngCặp khóa-giá trị của đối số hàm

FunctionResponse object properties:

Bất động sảnLoạiBắt buộcMô tả
namechuỗivângTên hàm được gọi
responseđối tượngvângDữ liệu phản hồi của lệnh gọi hàm

ExecutableCode object properties:

Bất động sảnLoạiBắt buộcMô tả
languageliệt kêvângNgôn ngữ lập trình của mã
codechuỗivângMã để thực thi

CodeExecutionResult object properties:

Bất động sảnLoạiBắt buộcMô tả
outcomeliệt kêvângTrạng thái kết quả thực thi mã
outputchuỗikhôngNội dung đầu ra của quá trình thực thi mã

CodeExecution object properties:

Bất động sảnLoạiBắt buộcMô 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ảnLoạiBắt buộcMô tả
functionCallingConfigđối tượngkhôngCấu hình gọi hàm

FunctionCallingConfig object properties:

Bất động sảnLoạiBắt buộcMô tả
modeliệt kêkhôngChỉ định chế độ gọi hàm
allowedFunctionNamesmảngkhôngDanh 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ông
  • AUTO: Model tự động quyết định khi nào gọi một hàm
  • ANY: Model phải gọi một hàm
  • NONE: 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ảnLoạiBắt buộcMô tả
categoryliệt kêvângHạng mục an toàn
thresholdliệt kêvângNgưỡng chặn

HarmCategory enum values:

  • HARM_CATEGORY_HARASSMENT: Nội dung quấy rối
  • HARM_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àng
  • HARM_CATEGORY_DANGEROUS_CONTENT: Nội dung nguy hiểm
  • HARM_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ẤP
  • BLOCK_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ÌNH
  • BLOCK_NONE: Cho phép tất cả nội dung
  • OFF: Tắt bộ lọc an toàn

Complete HarmBlockThreshold enum values:

  • HARM_BLOCK_THRESHOLD_UNSPECIFIED: Ngưỡng chưa xác định
  • BLOCK_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ÌNH
  • BLOCK_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ảnLoạiBắt buộcMô tả
stopSequencesmảngkhôngTập hợp các chuỗi ký tự để dừng tạo (tối đa 5)
responseMimeTypechuỗikhôngLoại MIME của văn bản ứng viên được tạo
responseSchemađối tượngkhôngLược đồ đầu ra của văn bản ứng viên được tạo
responseModalitiesmảngkhôngPhương thức phản hồi được yêu cầu
candidateCountsố nguyênkhôngSố lượng câu trả lời được tạo để trả về
maxOutputTokenssố nguyênkhôngSố lượng mã thông báo tối đa trong câu trả lời của ứng viên
temperaturesốkhôngKiểm soát tính ngẫu nhiên của đầu ra, phạm vi [0,0, 2,0]
topPsốkhôngXá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
topKsố nguyênkhôngSố lượng mã thông báo tối đa cần xem xét trong quá trình lấy mẫu
seedsố nguyênkhôngSeed dùng để giải mã
presencePenaltysốkhôngHình phạt có mặt
frequencyPenaltysốkhôngTần suất phạt
responseLogprobsbooleankhôngCó xuất kết quả logprobs trong phản hồi hay không
logprobssố nguyênkhôngSố lượng logprobs hàng đầu được trả về
enableEnhancedCivicAnswersbooleankhôngCho phép trả lời dịch vụ công dân nâng cao
speechConfigđối tượngkhôngCấu hình tạo giọng nói
thinkingConfigđối tượngkhôngCấu hình chức năng tư duy
mediaResolutionliệ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ản
  • application/json: Phản hồi JSON
  • text/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ản
  • IMAGE: Cho biết model sẽ trả về hình ảnh
  • AUDIO: Cho biết model sẽ trả về âm thanh

Schema object properties:

Bất động sảnLoạiBắt buộcMô tả
typeliệt kêvângKiểu dữ liệu
descriptionchuỗikhôngMô tả trường
enummảngkhôngDanh sách các giá trị enum (khi loại là chuỗi)
examplebất kỳkhôngGiá trị mẫu
nullablebooleankhôngLiệu nó có thể là null
formatchuỗikhôngĐịnh dạng chuỗi (ví dụ: ngày, giờ)
itemsđối tượngkhôngLược đồ cho các mục mảng (khi kiểu là mảng)
propertiesđối tượngkhôngLược đồ cho thuộc tính đối tượng (khi loại là đối tượng)
requiredmảngkhôngDanh sách tên thuộc tính bắt buộc
minimumsốkhôngGiá trị tối thiểu cho số
maximumsốkhôngGiá trị tối đa cho số
minItemssố nguyênkhôngĐộ dài tối thiểu cho mảng
maxItemssố nguyênkhôngĐộ dài tối đa cho mảng
minLengthsố nguyênkhôngĐộ dài tối thiểu cho chuỗi
maxLengthsố nguyênkhôngĐộ dài tối đa cho chuỗi

Type enum values:

  • TYPE_UNSPECIFIED: Loại không xác định
  • STRING: Kiểu chuỗi
  • NUMBER: Kiểu số
  • INTEGER: Kiểu số nguyên
  • BOOLEAN: Kiểu Boolean
  • ARRAY: Kiểu mảng
  • OBJECT: Loại đối tượng

Supported programming languages (ExecutableCode):

  • LANGUAGE_UNSPECIFIED: Ngôn ngữ không xác định
  • PYTHON: Ngôn ngữ lập trình Python

Code execution result enum (Outcome):

  • OUTCOME_UNSPECIFIED: Kết quả không xác định
  • OUTCOME_OK: Thực thi mã thành công
  • OUTCOME_FAILED: Thực thi mã không thành công
  • OUTCOME_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ảnLoạiMô tả
contentđối tượngNội dung được tạo được mô hình trả về
finishReasonliệt kêLý do mô hình ngừng tạo token
safetyRatingsmảngDanh sách xếp hạng an toàn cho câu trả lời của ứng viên
citationMetadatađối tượngThông tin tham khảo cho ứng viên được tạo
tokenCountsố nguyênSố lượng mã thông báo cho ứng cử viên này
groundingAttributionsmảngThô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ượngSiêu dữ liệu tham chiếu cho đối tượng ứng cử viên
avgLogprobssốĐiểm xác suất log trung bình của ứng viên
logprobsResultđối tượngGhi 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ượngSiêu dữ liệu liên quan đến công cụ truy xuất ngữ cảnh URL
urlContextMetadatađối tượngSiêu dữ liệu liên quan đến công cụ truy xuất ngữ cảnh URL
indexsố nguyênDanh 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ình
  • MAX_TOKENS: Đã đạt đến giới hạn token tối đa được chỉ định trong yêu cầu
  • SAFETY: Trả lời nội dung thí sinh được đánh dấu vì lý do an toàn
  • RECITATION: Nội dung thí sinh trả lời được đánh dấu vì lý do đọc thuộc lòng
  • LANGUAGE: 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ân
  • BLOCKLIST: Hoạt động tạo token bị dừng do nội dung chứa các từ bị cấm
  • PROHIBITED_CONTENT: Hoạt động tạo token bị dừng do nội dung có thể chứa nội dung bị cấm
  • SPII: 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ảm
  • MALFORMED_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ảnLoạiMô tả
blockReasonliệt kêLý do chặn lời nhắc
safetyRatingsmả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ụng
  • SAFETY: Hệ thống bị chặn nhắc nhở vì lý do an toàn
  • OTHER: Lời nhắc bị chặn không rõ nguyên nhân
  • BLOCKLIST: 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ặn
  • PROHIBITED_CONTENT: Hệ thống đã chặn lời nhắc này vì nó chứa nội dung bị cấm
  • IMAGE_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ảnLoạiMô tả
promptTokenCountsố nguyênSố lượng mã thông báo trong lời nhắc
cachedContentTokenCountsố nguyênSố lượng mã thông báo trong phần được lưu trong bộ nhớ cache của lời nhắc
candidatesTokenCountsố nguyênTổ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
totalTokenCountsố nguyênTổng số mã thông báo cho yêu cầu tạo
toolUsePromptTokenCountsố nguyênSố mã thông báo trong lời nhắc sử dụng công cụ
thoughtsTokenCountsố nguyênSố lượng mã thông báo cho suy nghĩ của mô hình tư duy
promptTokensDetailsmảngDanh sách các phương thức được xử lý trong yêu cầu đầu vào
candidatesTokensDetailsmảngDanh sách các phương thức được trả về trong phản hồi
cacheTokensDetailsmảngDanh 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
toolUsePromptTokensDetailsmảngDanh 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ảnLoạiMô tả
categoryliệt kêHạng mục đánh giá này
probabilityliệt kêXác suất có hại cho nội dung này
blockedbooleanLiệ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ấp
  • MEDIUM: Phương tiện xác suất có hại
  • HIGH: Xác suất có hại cao

Siêu dữ liệu trích dẫn

CitationMetadata object properties:

Tài sảnLoạiMô tả
citationSourcesmảngNguồn tham khảo cho các câu trả lời cụ thể

CitationSource object properties:

Tài sảnLoạiMô tả
startIndexsố nguyênChỉ mục bắt đầu của phân đoạn phản hồi được quy cho nguồn này
endIndexsố nguyênChỉ mục cuối cùng của thuộc tính (độc quyền)
urichuỗiURI được gán cho phần văn bản từ nguồn này
licensechuỗiGiấ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ảnLoạiMô tả
groundingChunksmảngDanh 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
groundingSupportsmảngDanh sách hỗ trợ nối đất
webSearchQueriesmảngTruy 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ượngSiê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ảnLoạiMô tả
sourceIdđối tượngMã định danh của nguồn đóng góp cho sự phân bổ này
contentđối tượngNội dung của nguồn đóng góp cho sự ghi nhận này

AttributionSourceId object properties:

Bất động sảnLoạiMô tả
groundingPassageđối tượngMã định danh của đoạn được nhúng
semanticRetrieverChunkđối tượngMã định danh của Chunk được trích xuất bởi Semantic Retriever

GroundingPassageId object properties:

Bất động sảnLoạiMô tả
passageIdchuỗiID của đoạn khớp với GroundingPassage.id từ GeneAnswerRequest
partIndexsố nguyênChỉ mục của phần trong GroundingPassage.content

SemanticRetrieverChunk object properties:

Bất động sảnLoạiMô tả
sourcechuỗiTên nguồn khớp với SemanticRetrieverConfig.source từ yêu cầu
chunkchuỗiTên của Chunk chứa văn bản được gán

SearchEntryPoint object properties:

Tài sảnLoạiMô tả
renderedContentchuỗiĐoạn mã nội dung web có thể nhúng vào trang web hoặc ứng dụng WebView
sdkBlobchuỗiJSON đượ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ảnLoạiMô tả
partIndexsố nguyênChỉ mục của đối tượng Part bên trong đối tượng Content cha của nó
startIndexsố nguyênChỉ mục bắt đầu của phần đã cho tính bằng byte
endIndexsố nguyênChỉ mục cuối của đoạn đã cho tính bằng byte
textchuỗiVăn bản tương ứng với đoạn trong phản hồi

RetrievalMetadata object properties:

Bất động sảnLoạiMô tả
googleSearchDynamicRetrievalScoresốĐ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ảnLoạiMô tả
webđối tượngĐoạn nối đất từ ​​web

Web object properties:

Bất động sảnLoạiMô tả
urichuỗiTham chiếu URI cho đoạn
titlechuỗiTiêu đề của khối dữ liệu

GroundingSupport object properties:

Bất động sảnLoạiMô tả
groundingChunkIndicesmảngDanh 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
confidenceScoresmả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ượngPhâ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úy
  • IMAGE: 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ảnLoạiMô tả
modalityliệt kêPhương thức liên quan đến số lượng mã thông báo này
tokenCountsố nguyênSố 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ảnLoạiMô tả
includeThoughtsbooleanCó nên đưa nội dung tư duy vào đáp án
thinkingBudgetsố nguyênSố 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ảnLoạiMô tả
voiceConfigđối tượngCấu hình cho đầu ra giọng nói đơn
multiSpeakerVoiceConfigđối tượngCấu hình cài đặt nhiều loa
languageCodechuỗiMã ngôn ngữ để tổng hợp giọng nói

VoiceConfig object properties:

Bất động sảnLoạiMô tả
prebuiltVoiceConfigđối tượngCấu hình cho giọng nói dựng sẵn để sử dụng

PrebuiltVoiceConfig object properties:

Bất động sảnLoạiMô tả
voiceNamechuỗiTên của giọng nói dựng sẵn để sử dụng

MultiSpeakerVoiceConfig object properties:

Bất động sảnLoạiMô tả
speakerVoiceConfigsmảngTất cả giọng nói của loa được kích hoạt

SpeakerVoiceConfig object properties:

Bất động sảnLoạiMô tả
speakerchuỗiTên diễn giả sử dụng
voiceConfigđối tượngCấ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ật
  • ko-KR: tiếng Hàn
  • fr-FR: tiếng Pháp
  • de-DE: tiếng Đức
  • es-ES: tiếng Tây Ban Nha
  • pt-BR: Bồ Đào Nha (Brazil)
  • hi-IN: Tiếng Hindi
  • ar-XA: tiếng Ả Rập
  • it-IT: Ý
  • tr-TR: tiếng Thổ Nhĩ Kỳ
  • vi-VN: Tiếng Việt
  • th-TH: Thái
  • ru-RU: tiếng Nga
  • pl-PL: tiếng Ba Lan
  • nl-NL: tiếng Hà Lan

Kết quả logprobs

LogprobsResult object properties:

Bất động sảnLoạiMô tả
topCandidatesmảngMảng ứng viên được sắp xếp theo log xác suất giảm dần
chosenCandidatesmảngMả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ảnLoạiMô tả
candidatesmảngThí sinh sắp xếp theo log xác suất giảm dần

Candidate (Logprobs) object properties:

Tài sảnLoạiMô tả
tokenchuỗiGiá trị chuỗi mã thông báo cho ứng viên
tokenIdsố nguyênGiá trị ID mã thông báo cho ứng viên
logProbabilitysốĐă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ảnLoạiMô tả
urlRetrievalContextsmảngDanh sách bối cảnh truy xuất URL

UrlRetrievalContext object properties:

Tài sảnLoạiMô tả
retrievedUrlchuỗiURL được công cụ lấy ra

UrlContextMetadata object properties:

Bất động sảnLoạiMô tả
urlMetadatamảngDanh sách ngữ cảnh URL

UrlMetadata object properties:

Tài sảnLoạiMô tả
retrievedUrlchuỗiURL được công cụ lấy ra
urlRetrievalStatusliệt kêTrạng thái truy xuất URL

UrlRetrievalStatus enum values:

  • URL_RETRIEVAL_STATUS_SUCCESS: Truy xuất URL thành công
  • URL_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ỉ định
  • HARM_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ĩu
  • HARM_CATEGORY_VIOLENCE: PaLM – Kịch bản mô tả bạo lực đối với cá nhân hoặc nhóm
  • HARM_CATEGORY_SEXUAL: PaLM - Đề cập đến hành vi tình dục hoặc nội dung tục tĩu khác
  • HARM_CATEGORY_MEDICAL: PaLM - Quảng bá lời khuyên y tế chưa được xác minh
  • HARM_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ại
  • HARM_CATEGORY_HARASSMENT: Song Tử – Nội dung quấy rối
  • HARM_CATEGORY_HATE_SPEECH: Song Tử – Lời nói căm thù và nội dung
  • HARM_CATEGORY_SEXUALLY_EXPLICIT: Song Tử – Nội dung khiêu dâm rõ ràng
  • HARM_CATEGORY_DANGEROUS_CONTENT: Song Tử – Nội dung nguy hiểm
  • HARM_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 định
  • NEGLIGIBLE: Xác suất có hại không đáng kể
  • LOW: Xác suất có hại thấp
  • MEDIUM: Phương tiện xác suất có hại
  • HIGH: Xác suất có hại cao

Modality enum values:

  • MODALITY_UNSPECIFIED: Phương thức không được chỉ định
  • TEXT: Văn bản thuần túy
  • IMAGE: Hình ảnh
  • VIDEO: Video
  • AUDIO: Âm thanh
  • DOCUMENT: Tài liệu, ví dụ: PDF

MediaResolution enum values:

  • MEDIA_RESOLUTION_UNSPECIFIED: Độ phân giải media chưa được thiết lập
  • MEDIA_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ụng
  • URL_RETRIEVAL_STATUS_SUCCESS: Truy xuất URL thành công
  • URL_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ỗiMô tả
400Lỗi định dạng yêu cầu hoặc tham số không hợp lệ
401Khóa API không hợp lệ hoặc bị thiếu
403Không đủ quyền hoặc giới hạn hạn ngạch
429Tần suất yêu cầu quá cao
500Lỗi nội bộ máy chủ

Giải thích chi tiết về mã lỗi

Mã LỗiTrạng tháiMô tảGiải pháp
400INVALID_ARGUMENTTham số yêu cầu không hợp lệ hoặc lỗi định dạngKiểm tra định dạng tham số yêu cầu và các trường bắt buộc
400FAILED_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
401UNAUTHENTICATEDKhóa API không hợp lệ, bị thiếu hoặc đã hết hạnKiểm tra tính hợp lệ và định dạng của khóa API
403PERMISSION_DENIEDKhông đủ quyền hoặc hết hạn ngạchKiểm tra quyền khóa API hoặc hạn ngạch nâng cấp
404NOT_FOUNDMô hình hoặc tài nguyên được chỉ định không tồn tạiXác minh tên mô hình và đường dẫn tài nguyên
413PAYLOAD_TOO_LARGENội dung yêu cầu quá lớnGiảm kích thước nội dung đầu vào hoặc xử lý theo đợt
429RESOURCE_EXHAUSTEDĐã vượt quá tần suất yêu cầu hoặc không đủ hạn mứcGiảm tần suất yêu cầu hoặc chờ thiết lập lại hạn ngạch
500INTERNALLỗ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ợ
503UNAVAILABLEDịch vụ tạm thời không cóĐợi một khoảng thời gian và thử lại
504DEADLINE_EXCEEDEDYê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"
          }
        ]
      }
    ]
  }
}