文字生成

當 Gemini API 收到文字、圖片、影片和音訊做為輸入內容時，便可產生文字輸出內容。

本指南將說明如何使用 generateContent 和 streamGenerateContent 方法產生文字。如要瞭解如何使用 Gemini 的視覺和音訊功能，請參閱「Vision」和「音訊」指南。

使用純文字輸入內容產生文字

使用 Gemini API 產生文字最簡單的方法，就是為模型提供單一純文字輸入內容，如以下範例所示：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/nulltext_generation.sh

在這種情況下，「說明 AI 運作方式」提示不會包含任何輸出範例、系統指示或格式資訊。這是一種零樣本方法。在某些用途上，單拍或少拍提示可能會產生更符合使用者期待的輸出內容。在某些情況下，您可能還需要提供系統操作說明，協助模型瞭解任務或遵循特定規範。

使用文字和圖片輸入內容來生成文字

Gemini API 支援結合文字和媒體檔案的多模態輸入內容。以下範例說明如何根據文字和圖片輸入內容產生文字：

# Use a temporary file to hold the base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"

# Use a temporary file to hold the 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://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/nulltext_generation.sh

與文字提示一樣，多模態提示也可能涉及各種方法和精進項目。視這個範例的輸出結果而定，您可能需要在提示中加入步驟，或在指示中提供更具體的說明。詳情請參閱「檔案提示策略」。

產生文字串流

根據預設，模型會在完成整個文字產生程序後傳回回應。您可以不等待整個結果，改用串流處理部分結果，藉此加快互動速度。

以下範例說明如何使用 streamGenerateContent 方法實作串流，從純文字輸入提示產生文字。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse&key=${GOOGLE_API_KEY}" \
        -H 'Content-Type: application/json' \
        --no-buffer \
        -d '{ "contents":[{"parts":[{"text": "Write a story about a magic backpack."}]}]}'text_generation.sh

建構互動式聊天

您可以使用 Gemini SDK 收集多輪問題和回覆，讓使用者逐步取得答案，或針對多重問題尋求協助。這個 SDK 功能提供一個介面，可追蹤對話記錄，但幕後會使用相同的 generateContent 方法建立回應。

以下程式碼範例顯示基本即時通訊實作方式：

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_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"chat.sh

啟用聊天串流功能

你也可以搭配即時通訊使用串流功能，如以下範例所示：

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?alt=sse&key=$GOOGLE_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"chat.sh

設定文字產生

您傳送至模型的每個提示都含有參數，用來控制模型生成回覆的方式，您可以使用 GenerationConfig 設定這些參數。如果您未設定參數，模型會使用預設選項，這些選項可能因模型而異。

以下範例說明如何設定幾個可用的選項。

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "contents": [{
            "parts":[
                {"text": "Write a story about a magic backpack."}
            ]
        }],
        "safetySettings": [
            {
                "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
                "threshold": "BLOCK_ONLY_HIGH"
            }
        ],
        "generationConfig": {
            "stopSequences": [
                "Title"
            ],
            "temperature": 1.0,
            "maxOutputTokens": 800,
            "topP": 0.8,
            "topK": 10
        }
    }'  2> /dev/null | grep "text"configure_model_parameters.sh

stopSequences 會指定一組字元序列 (最多 5 個)，用於停止產生輸出內容。如果已指定，API 會在 stop_sequence 首次出現時停止。這個停止序列不會包含在回應中。

temperature 會控制輸出的隨機程度。如要取得更多創意回覆，請使用較高的值；如要取得較多確定性回覆，請使用較低的值。值的範圍為 [0.0, 2.0]。

maxOutputTokens 會設定候選項中可納入的符記數量上限。

topP 會影響模型選取輸出符記的方式。模型會按照可能性最高到最低的順序選取符記，直到所選符記的可能性總和等於 topP 值。預設的 topP 值為 0.95。

topK 會影響模型選取輸出符記的方式。如果 topK 設為 1，代表所選詞元是模型詞彙表的所有詞元中可能性最高者。如果 topK 設為 3，則代表模型會依據溫度參數，從可能性最高的 3 個詞元中選取下一個詞元。接著進一步根據 topP 篩選符記，最後依 temperature 選出最終符記。

新增系統指示

系統指示可讓您根據特定需求和用途，引導模型的行為。

提供模型系統指示時，您會向模型提供額外脈絡資訊，讓模型瞭解任務、生成更符合需求的回應，並在與使用者互動時全程遵守特定指引。您也可以設定系統指示，以便指定產品層級行為，並與使用者提供的提示分開。

您可以在初始化模型時設定系統指令：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_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"}}}'system_instruction.sh

如需使用系統指令的互動式端對端範例，請參閱系統指令 Colab。

後續步驟

瞭解 Gemini API 的基本概念後，您可以嘗試以下操作：

視覺理解：瞭解如何使用 Gemini 的原生視覺理解功能處理圖片和影片。
音訊理解：瞭解如何使用 Gemini 的原生音訊理解功能處理音訊檔案。