Gemini Generate Content

使用 Gemini Content 與 Parts 結構建立文字、多模態、工具和程式碼執行回應。

Generate Content API 使用 Content 與 Parts 表達文字、多模態、函式呼叫和程式碼執行請求，並透過 Candidates、Usage Metadata 與安全性資訊傳回生成結果。請求使用 Bearer API Key 進行身分驗證；不同模型支援的輸入模態、工具和進階生成參數可能不同，請以目前帳戶可見模型及官方功能說明為準。

POST/v1beta/models/{model}:generateContent

使用 Gemini Content 與 Parts 結構生成文字、多模態、函式呼叫或程式碼執行回應。

授權

bearerAuth

授權Bearer <token>

在 Authorization Header 中使用 Bearer your-api-key。

傳遞位置: header

路徑參數

model*string

用於生成內容的模型 ID。路徑中會自動組成 models/{model}。

預設值"MODEL_ID"

請求主體

Gemini 使用 Content 與 Parts 表達文字、多模態輸入、工具和生成設定。

application/json

文字對話

使用 user 與 model Content 組織單輪或多輪文字對話。

contents[]: 依時間順序排列的對話內容。
parts[].text: 每則訊息中的文字內容。
role: 訊息產生者，常用值為 user 或 model。

application/json

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "你好！請介紹一下自己。"
        }
      ]
    }
  ]
}

使用 Content 與 text Part 組織單輪或多輪文字對話。

contents*array<>

依時間順序排列的文字 Content。每則訊息透過 parts[].text 提供內容。

項目數1 <= items

tools?array<>

模型可以使用的函式、程式碼執行、搜尋、URL Context、File Search、MCP 等工具。

toolConfig?

請求中工具的呼叫設定。

safetySettings?array<>

按安全類別設定內容封鎖門檻。

systemInstruction?

開發者設定的系統指令，目前僅支援文字內容。

generationConfig?

模型生成和輸出設定。

cachedContent?string

作為上下文使用的快取內容名稱，格式為 cachedContents/{cachedContent}。

serviceTier?ServiceTier

請求使用的服務層級。

可用值

"unspecified"
"standard"
"flex"
"priority"

store?boolean

控制目前請求的日誌記錄行為；設定後優先於項目級日誌設定。

回應主體

`application/json`

curl -X POST "https://example.com/v1beta/models/MODEL_ID:generateContent" \  -H "Content-Type: application/json" \  -d '{    "contents": [      {        "role": "user",        "parts": [          {            "text": "你好！請介紹一下自己。"          }        ]      }    ]  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "你好！我是一個 AI 助手，可以幫助你解答問題和完成任務。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        }
      ],
      "tokenCount": 24
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 24,
    "totalTokenCount": 32,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 8
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 24
      }
    ]
  },
  "modelVersion": "MODEL_ID",
  "responseId": "response-example"
}

Google Gemini Generate Content 官方文件檢視上游協議定義與最新欄位變更。

授權

路徑參數

請求主體

回應主體

200application/json

400application/json

401application/json

403application/json

404application/json

413application/json

429application/json

500application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`