串流生成內容¶
POST https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent
由模型產生串流回應,輸入為 GenerateContentRequest。
參數¶
model:必填 string
模型 ID,例如 gemini-2.5-flash。組成資源名稱 models/{model}。
請求主體¶
model:必填 string
用於產生完成結果的 Model 名稱。格式:models/{model}。
contents:必填 Content array
與模型進行目前對話的內容。單輪查詢時為單一執行個體;多輪查詢(例如聊天)時,這是包含對話記錄與最新請求的重複欄位。
systemInstruction:Content
選填。開發人員設定的系統指令。目前僅支援文字。
tools:Tool array
選填。Tools 的清單,Model 可用於產生下一個回應。Tool 是一段程式碼,讓系統能與外部系統互動,在 Model 的知識與範圍之外執行某個動作或一組動作。支援的 Tool 為 Function 與 code_execution。詳情請參閱函式呼叫與程式碼執行指南。
**toolConfig**:`ToolConfig` 選填。請求中指定的任何 [`Tool`](/api-reference/generate-content/stream-generate-content/#Resource:Tool) 的工具設定。使用範例請參閱[函式呼叫指南](/docs/function-calling/#function_calling_modes)。
**functionCallingConfig**:`FunctionCallingConfig` 選填。函式呼叫設定。
**mode**:`string enum` 選填。指定函式呼叫的執行模式。若未指定,預設值為 AUTO。
可能的值: - `MODE_UNSPECIFIED`:未指定的函式呼叫模式。不應使用此值。 - `AUTO`:預設的模型行為,由模型決定要預測函式呼叫或自然語言回應。 - `ANY`:模型被強制一律只預測函式呼叫。若有設定「allowed_function_names」,預測的函式呼叫會限制在「allowed_function_names」中的任一個;否則預測的函式呼叫會是所提供「function_declarations」中的任一個。 - `NONE`:模型不會預測任何函式呼叫。模型行為與未傳入任何函式宣告時相同。 - `VALIDATED`:由模型決定要預測函式呼叫或自然語言回應,但會以受限解碼驗證函式呼叫。若有設定「allowed_function_names」,預測的函式呼叫會限制在「allowed_function_names」中的任一個;否則預測的函式呼叫會是所提供「function_declarations」中的任一個。**retrievalConfig**:`RetrievalConfig` 選填。擷取設定。
**latLng**:`LatLng` 選填。使用者的位置。
**latitude**:`number` 以度為單位的緯度。必須介於 [-90.0, +90.0] 範圍內。 **longitude**:`number` 以度為單位的經度。必須介於 [-180.0, +180.0] 範圍內。safetySettings:SafetySetting array
選填。用於封鎖不安全內容的專屬 SafetySetting 執行個體清單。此設定會強制套用於 GenerateContentRequest.contents 與 GenerateContentResponse.candidates。每個 SafetyCategory 類型不應有多於一個設定。API 會封鎖任何未達這些設定所定門檻的內容與回應。此清單會覆寫 safety_settings 中指定的每個 SafetyCategory 的預設設定。若清單中缺少某個 SafetySetting(針對給定的 SafetyCategory),API 會使用該類別的預設安全設定。支援的危害類別為 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY、HARM_CATEGORY_JAILBREAK。可用安全設定的詳細資訊請參閱指南。另請參閱安全指南,了解如何將安全考量納入您的 AI 應用程式。
**generationConfig**:`GenerationConfig` 選填。模型產生與輸出的設定選項。
**candidateCount**:`integer` 選填。要傳回的產生回應數量。若未設定,預設為 1。請注意,此設定不適用於前幾代模型(Gemini 1.0 系列)。 **stopSequences**:`string array` 選填。會停止輸出產生的字元序列集合(最多 5 個)。若指定,API 會在 `stop_sequence` 首次出現時停止。停止序列不會包含在回應中。 **maxOutputTokens**:`integer` 選填。回應候選中可包含的權杖數量上限。注意:預設值依模型而異,請參閱 `Model.output_token_limit` 屬性,該屬性屬於 `Model`,由 `getModel` 函式傳回。 **temperature**:`number` 選填。控制輸出的隨機程度。注意:預設值依模型而異,請參閱 `Model.temperature` 屬性,該屬性屬於 `Model`,由 `getModel` 函式傳回。值可介於 [0.0, 2.0]。此欄位在 Gemini 3.6 Flash 及更新的模型上不再支援,會被靜默忽略。 **topP**:`number` 選填。取樣時要考量的權杖累積機率上限。模型結合使用 Top-k 與 Top-p(nucleus)取樣。權杖會依其指派的機率排序,只考量最有可能的權杖。Top-k 取樣直接限制要考量的權杖數量上限,Nucleus 取樣則依累積機率限制權杖數量。注意:預設值依 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 及更新的模型上不再支援,會被靜默忽略。 **topK**:`integer` 選填。取樣時要考量的權杖數量上限。Gemini 模型使用 Top-p(nucleus)取樣,或 Top-k 與 nucleus 取樣的組合。Top-k 取樣考量機率最高的 `top_k` 個權杖集合。使用 nucleus 取樣執行的模型不允許設定 top_k。注意:預設值依 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 及更新的模型上不再支援,會被靜默忽略。 **seed**:`integer` 選填。解碼時使用的種子。若未設定,請求會使用隨機產生的種子。 **responseMimeType**:`string` 選填。產生的候選文字的 MIME 類型。支援的 MIME 類型為:`text/plain`:(預設)文字輸出。`application/json`:回應候選中的 JSON 回應。`text/x.enum`:回應候選中以字串形式表示的 ENUM 回應。所有支援的文字 MIME 類型清單請參閱[文件](/docs/file-input-methods/#text-file-types)。 **responseJsonSchema**:`object` 選填。內部細節。請改用 `responseJsonSchema`,不要使用此欄位。 **presencePenalty**:`number` 選填。若某個權杖已在回應中出現過,對下一個權杖的 logprobs 套用的存在懲罰。此懲罰是二元的開/關,不取決於權杖被使用的次數(第一次之後)。若要使用隨使用次數增加的懲罰,請使用 frequency_penalty。正值懲罰會降低使用已在回應中用過的權杖,擴大詞彙量;負值懲罰會鼓勵使用已在回應中用過的權杖,縮小詞彙量。 **frequencyPenalty**:`number` 選填。對下一個權杖的 logprobs 套用的頻率懲罰,會乘以每個權杖至今在回應中出現的次數。正值懲罰會依權杖被使用的次數比例降低其再次使用:權杖用得越多,模型就越難再次使用該權杖,進而擴大回應的詞彙量。注意:*負值*懲罰會鼓勵模型依權杖被使用的次數比例重複使用權杖。較小的負值會縮小回應的詞彙量;較大的負值會使模型開始重複某個常見權杖,直到達到 max_output_tokens 上限。 **responseLogprobs**:`boolean` 選填。若為 true,在回應中匯出 logprobs 結果。 **logprobs**:`integer` 選填。僅在 response_logprobs=True 時有效。此設定決定在每個解碼步驟要傳回的頂尖 logprobs 數量(包含所選候選),傳回於 Candidate.logprobs_result 中。數字必須介於 [0, 20] 範圍內。 **enableEnhancedCivicAnswers**:`boolean` 選填。啟用強化公民答覆。並非所有模型都提供此功能。**responseModalities**:`string enum array` 選填。請求的回應模態。表示模型可傳回、且回應中應出現的模態集合,必須與回應的模態完全相符。一個模型可能有多種支援的模態組合。若請求的模態不符合任何支援的組合,將傳回錯誤。空清單等同於僅請求文字。
可能的值: - `MODALITY_UNSPECIFIED`:預設值。 - `TEXT`:表示模型應傳回文字。 - `IMAGE`:表示模型應傳回圖片。 - `AUDIO`:表示模型應傳回音訊。**speechConfig**:`SpeechConfig` 選填。語音產生設定。
**voiceConfig**:`VoiceConfig` 單一語音輸出時使用的設定。
**voiceConfig**:`Union type` 要使用的說話者設定。
Union 欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**:`PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**:`string` 選填。要使用的預設語音名稱。**multiSpeakerVoiceConfig**:`MultiSpeakerVoiceConfig` 選填。多說話者設定的組態。與 voice_config 欄位互斥。
**speakerVoiceConfigs**:必填 `SpeakerVoiceConfig array` 所有已啟用的說話者語音。
**speaker**:必填 `string` 要使用的說話者名稱。應與提示詞中的名稱相同。**voiceConfig**:必填 `VoiceConfig` 要使用的語音設定。
**voiceConfig**:`Union type` 要使用的說話者設定。
Union 欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**:`PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**:`string` 選填。要使用的預設語音名稱。**thinkingConfig**:`ThinkingConfig` 選填。思考功能的設定。若為不支援思考的模型設定此欄位,將傳回錯誤。
**includeThoughts**:`boolean` 表示是否要在回應中包含思考內容。若為 true,僅在有思考內容可用時才會傳回思考內容。 **thinkingBudget**:`integer` 模型應產生的思考權杖數量。**thinkingLevel**:`string enum` 選填。控制模型在產生回應之前,內部推理程序的最大深度。預設值依模型而異。詳情請參閱[思考等級指南](/docs/thinking/#thinking-levels)。建議用於 Gemini 3 或更新的模型;用於較早的模型會產生錯誤。
可能的值: - `THINKING_LEVEL_UNSPECIFIED`:預設值。 - `MINIMAL`:幾乎不思考。 - `LOW`:低思考等級。 - `MEDIUM`:中思考等級。 - `HIGH`:高思考等級。 - `XHIGH`:極高思考等級。**imageConfig**:`ImageConfig` 選填。圖片產生設定。若為不支援這些設定選項的模型設定此欄位,將傳回錯誤。
**aspectRatio**:`string` 選填。要產生的圖片的長寬比。支援的長寬比:`1:1`、`1:4`、`4:1`、`1:8`、`8:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9` 或 `21:9`。若未指定,模型會根據所提供的任何參考圖片選擇預設長寬比。 **imageSize**:`string` 選填。指定產生圖片的大小。支援的值為 `512`、`1K`、`2K`、`4K`。若未指定,模型會使用預設值 `1K`。**mediaResolution**:`string enum` 選填。若指定,將使用所指定的媒體解析度。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`:尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`:媒體解析度設為低(64 個權杖)。 - `MEDIA_RESOLUTION_MEDIUM`:媒體解析度設為中(256 個權杖)。 - `MEDIA_RESOLUTION_HIGH`:媒體解析度設為高(縮放重新取景,256 個權杖)。**responseFormat**:`ResponseFormatConfig` 選填。回應輸出格式的設定。允許以扁平結構為每種模態(文字、音訊、圖片)指定輸出設定。
**text**:`TextResponseFormat` 選填。文字輸出格式設定。
**mimeType**:`string enum` 選填。文字輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`:預設值。不使用此值。 - `APPLICATION_JSON`:JSON 輸出格式。 - `TEXT_PLAIN`:純文字輸出格式。**audio**:`AudioResponseFormat` 選填。音訊輸出格式設定。
**mimeType**:`string enum` 選填。音訊輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`:預設值。不使用此值。 - `AUDIO_MP3`:MP3 音訊格式。 - `AUDIO_OGG_OPUS`:OGG Opus 音訊格式。 - `AUDIO_L16`:原始 PCM(L16)音訊格式。 - `AUDIO_WAV`:WAV 音訊格式。 - `AUDIO_ALAW`:A-law 音訊格式。 - `AUDIO_MULAW`:Mu-law 音訊格式。**delivery**:`string enum` 選填。音訊輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`:預設值。不使用此值。 - `INLINE`:音訊資料在回應中以行內方式傳回。 - `URI`:音訊資料以 URI 形式傳回。**image**:`ImageResponseFormat` 選填。圖片輸出格式設定。
**mimeType**:`string enum` 選填。圖片輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`:預設值。不使用此值。 - `IMAGE_JPEG`:JPEG 圖片格式。**delivery**:`string enum` 選填。圖片輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`:預設值。不使用此值。 - `INLINE`:圖片資料在回應中以行內方式傳回。 - `URI`:圖片資料以 URI 形式傳回。**aspectRatio**:`string enum` 選填。圖片輸出的長寬比。
可能的值: - `ASPECT_RATIO_UNSPECIFIED`:預設值。不使用此值。 - `ASPECT_RATIO_ONE_BY_ONE`:1:1 長寬比。 - `ASPECT_RATIO_TWO_BY_THREE`:2:3 長寬比。 - `ASPECT_RATIO_THREE_BY_TWO`:3:2 長寬比。 - `ASPECT_RATIO_THREE_BY_FOUR`:3:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_THREE`:4:3 長寬比。 - `ASPECT_RATIO_FOUR_BY_FIVE`:4:5 長寬比。 - `ASPECT_RATIO_FIVE_BY_FOUR`:5:4 長寬比。 - `ASPECT_RATIO_NINE_BY_SIXTEEN`:9:16 長寬比。 - `ASPECT_RATIO_SIXTEEN_BY_NINE`:16:9 長寬比。 - `ASPECT_RATIO_TWENTY_ONE_BY_NINE`:21:9 長寬比。 - `ASPECT_RATIO_ONE_BY_EIGHT`:1:8 長寬比。 - `ASPECT_RATIO_EIGHT_BY_ONE`:8:1 長寬比。 - `ASPECT_RATIO_ONE_BY_FOUR`:1:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_ONE`:4:1 長寬比。**imageSize**:`string enum` 選填。圖片輸出的大小。
可能的值: - `IMAGE_SIZE_UNSPECIFIED`:預設值。不使用此值。 - `IMAGE_SIZE_FIVE_TWELVE`:512px 圖片大小。 - `IMAGE_SIZE_ONE_K`:1K 圖片大小。 - `IMAGE_SIZE_TWO_K`:2K 圖片大小。 - `IMAGE_SIZE_FOUR_K`:4K 圖片大小。**translationConfig**:`TranslationConfig` 選填。翻譯設定。
**targetLanguageCode**:必填 `string` 翻譯的目標語言。支援的值為 BCP-47 語言代碼(例如「en」、「es」、「fr」)。 **echoTargetLanguage**:`boolean` 選填。若為 true,當目標語言被說出時,模型會產生音訊,本質上是鸚鵡學舌般地複誦輸入。若為 false,則不會為目標語言產生音訊。**audioTranscriptionConfig**:`AudioTranscriptionConfig` 選填。音訊轉錄(語音辨識)設定。
**languageCodes**:`string array` 選填。BCP-47 語言代碼,提供音訊中出現語言的提示。若省略或為空,預設為自動語言偵測。 **customVocabulary**:`string array` 選填。自訂詞彙片語清單,讓語音辨識模型偏向辨識特定詞彙(產品名稱、專有名詞、專業術語)。 **wordTimestamp**:`boolean` 選填。設定逐字時間戳記的產生。 **diarization**:`boolean` 選填。設定說話者分離。 **sourceText**:`string` 選填。要透過語音指令編輯或改寫的來源文字。在 `SMART` 模式下提供時,模型會將音訊輸入與此文字比對,並在候選回應中發出完整的替代文字,而不是附加在其後。**mode**:`string enum` 選填。設定轉錄模式。支援的值:`VERBATIM`、`SMART`。若未指定,預設為 `VERBATIM` 轉錄。在 `SMART` 模式下,模型會執行不流暢內容移除(消除填充詞、重複與 false starts)、輕度文法清理、自動格式化(段落、項目符號、編號清單),以及小幅使用者編輯(行內自我修正)。時間戳記與說話者分離與 `SMART` 模式不相容。
可能的值: - `MODE_UNSPECIFIED`:未指定的轉錄模式。 - `VERBATIM`:逐字轉錄模式。 - `SMART`:智慧轉錄模式。cachedContent:string
選填。要用作預測上下文的已快取內容名稱。格式:cachedContents/{cachedContent}
**serviceTier**:[`ServiceTier`](/api-reference/generate-content/stream-generate-content/#Resource:ServiceTier) 選填。請求的服務層級。
可能的值: - `unspecified`:預設服務層級,即標準層級。 - `standard`:標準服務層級。 - `flex`:Flex 服務層級。 - `priority`:Priority 服務層級。store:boolean
選填。設定指定請求的記錄行為。若有設定,其優先順序高於專案層級的記錄設定。
continuationToken:string
選填。不透明的接續權杖,用於從先前的 GenerateContent 或 StreamGenerateContent 回應接續產生,該回應先前以 finish_reason 設為 CONTINUATION 而停止。請注意,在要求中提供接續權杖時,contents 為必填,且必須與初始請求的提示詞與對話記錄完全相同。
labels:object
選填。帶有使用者定義中繼資料的請求標籤。選填。標籤必須符合標準的統一 Cloud 標籤要求:
- 標籤鍵必須以字母開頭。
- 標籤鍵與值的長度不得超過 63 個字元(Unicode 碼位),且只能包含小寫字母、數字字元、底線與破折號。
- 允許使用國際字元。
用法:
- 來自彙總者的安全識別碼:使用鍵
safety_identifier(例如{"safety_identifier": "user_session_123"})
範例要求
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=${GEMINI_API_KEY}" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{ "contents":[{"parts":[{"text": "Write a story about a magic backpack."}]}]}'
from google import genai
client = genai.Client()
response = client.models.generate_content_stream(
model="gemini-3.8-flash",
contents="Write a story about a magic backpack.",
)
for chunk in response:
print(chunk.text)
print("_" * 80)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const response = await ai.models.generateContentStream({
model: 'gemini-3.8-flash',
contents: 'Write a story about a magic backpack.',
});
let text = '';
for await (const chunk of response) {
console.log(chunk.text);
text += chunk.text;
}
Client client = new Client();
ResponseStream<GenerateContentResponse> responseStream =
client.models.generateContentStream(
"gemini-3.8-flash", "Write a story about a magic backpack.", null);
StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
System.out.print(res.text());
response.append(res.text());
}
responseStream.close();
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
contents := []*genai.Content{
genai.NewContentFromText("Write a story about a magic backpack.", genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
ctx,
"gemini-3.8-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
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-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
from google import genai
import PIL.Image
client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content_stream(
model="gemini-3.8-flash",
contents=["Tell me about this instrument", organ],
)
for chunk in response:
print(chunk.text)
print("_" * 80)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const organ = await ai.files.upload({
file: path.join(media, 'organ.jpg'),
});
const response = await ai.models.generateContentStream({
model: 'gemini-3.8-flash',
contents: [
createUserContent([
'Tell me about this instrument',
createPartFromUri(organ.uri, organ.mimeType)
]),
],
});
let text = '';
for await (const chunk of response) {
console.log(chunk.text);
text += chunk.text;
}
Client client = new Client();
String path = media_path + "organ.jpg";
byte[] imageData = Files.readAllBytes(Paths.get(path));
Content content =
Content.fromParts(
Part.fromText("Tell me about this instrument."),
Part.fromBytes(imageData, "image/jpeg"));
ResponseStream<GenerateContentResponse> responseStream =
client.models.generateContentStream("gemini-3.8-flash", content, null);
StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
System.out.print(res.text());
response.append(res.text());
}
responseStream.close();
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "organ.jpg"),
&genai.UploadFileConfig{
MIMEType: "image/jpeg",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromText("Tell me about this instrument"),
genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
ctx,
"gemini-3.8-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Please describe this file."},
{"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
from google import genai
client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content_stream(
model="gemini-3.8-flash",
contents=["Give me a summary of this audio file.", sample_audio],
)
for chunk in response:
print(chunk.text)
print("_" * 80)
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "sample.mp3"),
&genai.UploadFileConfig{
MIMEType: "audio/mpeg",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromText("Give me a summary of this audio file."),
genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
for result, err := range client.Models.GenerateContentStream(
ctx,
"gemini-3.8-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
state=$(jq ".file.state" file_info.json)
echo state=$state
while [[ "($state)" = *"PROCESSING"* ]];
do
echo "Processing video..."
sleep 5
# Get the file of interest to check state
curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
state=$(jq ".file.state" file_info.json)
done
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Please describe this file."},
{"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
from google import genai
import time
client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")
# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
print("Processing video...")
print("File state:", myfile.state)
time.sleep(5)
myfile = client.files.get(name=myfile.name)
response = client.models.generate_content_stream(
model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
for chunk in response:
print(chunk.text)
print("_" * 80)
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
let video = await ai.files.upload({
file: path.join(media, 'Big_Buck_Bunny.mp4'),
});
// Poll until the video file is completely processed (state becomes ACTIVE).
while (!video.state || video.state.toString() !== 'ACTIVE') {
console.log('Processing video...');
console.log('File state: ', video.state);
await sleep(5000);
video = await ai.files.get({name: video.name});
}
const response = await ai.models.generateContentStream({
model: 'gemini-3.8-flash',
contents: [
createUserContent([
'Describe this video clip',
createPartFromUri(video.uri, video.mimeType),
]),
],
});
let text = '';
for await (const chunk of response) {
console.log(chunk.text);
text += chunk.text;
}
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
&genai.UploadFileConfig{
MIMEType: "video/mp4",
},
)
if err != nil {
log.Fatal(err)
}
// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
fmt.Println("Processing video...")
fmt.Println("File state:", file.State)
time.Sleep(5 * time.Second)
file, err = client.Files.Get(ctx, file.Name, nil)
if err != nil {
log.Fatal(err)
}
}
parts := []*genai.Part{
genai.NewPartFromText("Describe this video clip"),
genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
for result, err := range client.Models.GenerateContentStream(
ctx,
"gemini-3.8-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT
echo $MIME_TYPE
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri
# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Can you add a few more lines to this poem?"},
{"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
from google import genai
client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content_stream(
model="gemini-3.8-flash",
contents=["Give me a summary of this document:", sample_pdf],
)
for chunk in response:
print(chunk.text)
print("_" * 80)
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "test.pdf"),
&genai.UploadFileConfig{
MIMEType: "application/pdf",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromText("Give me a summary of this document:"),
genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
for result, err := range client.Models.GenerateContentStream(
ctx,
"gemini-3.8-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse&key=$GEMINI_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"
from google import genai
from google.genai import types
client = genai.Client()
chat = client.chats.create(
model="gemini-3.8-flash",
history=[
types.Content(role="user", parts=[types.Part(text="Hello")]),
types.Content(
role="model",
parts=[
types.Part(
text="Great to meet you. What would you like to know?"
)
],
),
],
)
response = chat.send_message_stream(message="I have 2 dogs in my house.")
for chunk in response:
print(chunk.text)
print("_" * 80)
response = chat.send_message_stream(
message="How many paws are in my house?"
)
for chunk in response:
print(chunk.text)
print("_" * 80)
print(chat.get_history())
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const chat = ai.chats.create({
model: 'gemini-3.8-flash',
history: [
{
role: 'user',
parts: [{text: 'Hello'}],
},
{
role: 'model',
parts: [{text: 'Great to meet you. What would you like to know?'}],
},
],
});
console.log('Streaming response for first message:');
const stream1 = await chat.sendMessageStream({
message: 'I have 2 dogs in my house.',
});
for await (const chunk of stream1) {
console.log(chunk.text);
console.log('_'.repeat(80));
}
console.log('Streaming response for second message:');
const stream2 = await chat.sendMessageStream({
message: 'How many paws are in my house?',
});
for await (const chunk of stream2) {
console.log(chunk.text);
console.log('_'.repeat(80));
}
console.log(chat.getHistory());
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GEMINI_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
history := []*genai.Content{
genai.NewContentFromText("Hello", genai.RoleUser),
genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
}
chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
log.Fatal(err)
}
for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "I have 2 dogs in my house."}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(chunk.Text())
fmt.Println(strings.Repeat("_", 64))
}
for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(chunk.Text())
fmt.Println(strings.Repeat("_", 64))
}
fmt.Println(chat.History(false))
回應¶
candidates:Candidate array
來自模型的候選回應。
**promptFeedback**:`PromptFeedback` 傳回與內容篩選器相關的提示詞回饋。
**blockReason**:`string enum` 選填。若有設定,表示提示詞遭到封鎖,不會傳回任何候選。請改寫提示詞。
可能的值: - `BLOCK_REASON_UNSPECIFIED`:預設值。不使用此值。 - `SAFETY`:提示詞因安全理由遭到封鎖。請查看 `safety_ratings`,了解是哪個安全類別造成封鎖。 - `OTHER`:提示詞因未知理由遭到封鎖。 - `BLOCKLIST`:提示詞因包含術語封鎖清單中的詞彙而遭到封鎖。 - `PROHIBITED_CONTENT`:提示詞因含有禁止內容而遭到封鎖。 - `IMAGE_SAFETY`:候選因不安全的圖片產生內容而遭到封鎖。**usageMetadata**:`UsageMetadata` 僅供輸出。產生請求的權杖用量中繼資料。
**promptTokenCount**:`integer` 提示詞中的權杖數量。當有設定 `cached_content` 時,這仍然是有效的提示詞總大小,也就是包含快取內容中的權杖數量。 **cachedContentTokenCount**:`integer` 提示詞中已快取部分的權杖數量(即快取內容)。 **candidatesTokenCount**:`integer` 所有產生的回應候選的權杖總數。 **toolUsePromptTokenCount**:`integer` 僅供輸出。工具使用提示詞中存在的權杖數量。 **thoughtsTokenCount**:`integer` 僅供輸出。思考模型的思考權杖數量。 **totalTokenCount**:`integer` 產生請求的權杖總數(提示詞 + 工具使用提示詞 + 思考 + 回應候選)。 **promptTokensDetails**:[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content/#Resource:ModalityTokenCount) `array` 僅供輸出。請求輸入中處理的模態清單。 **cacheTokensDetails**:[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content/#Resource:ModalityTokenCount) `array` 僅供輸出。請求輸入中快取內容的模態清單。 **candidatesTokensDetails**:[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content/#Resource:ModalityTokenCount) `array` 僅供輸出。回應中傳回的模態清單。 **toolUsePromptTokensDetails**:[`ModalityTokenCount`](/api-reference/generate-content/stream-generate-content/#Resource:ModalityTokenCount) `array` 僅供輸出。工具使用請求輸入中處理的模態清單。**serviceTier**:[`ServiceTier`](/api-reference/generate-content/stream-generate-content/#Resource:ServiceTier) 僅供輸出。請求的服務層級。
可能的值: - `unspecified`:預設服務層級,即標準層級。 - `standard`:標準服務層級。 - `flex`:Flex 服務層級。 - `priority`:Priority 服務層級。modelVersion:string
僅供輸出。用於產生回應的模型版本。
responseId:string
僅供輸出。response_id 用於識別每個回應。
**modelStatus**:`ModelStatus` 僅供輸出。此模型目前的模型狀態。
**modelStage**:`ModelStage` 底層模型的階段。
可能的值: - `MODEL_STAGE_UNSPECIFIED`:未指定的模型階段。 - `EXPERIMENTAL`:此階段的模型僅供實驗用途。 - `PREVIEW`:此階段的模型比實驗模型更成熟。 - `STABLE`:此階段的模型被視為穩定,可用於正式環境。 - `LEGACY`:若模型處於此階段,表示該模型在不久的將來將走向淘汰。只有現有客戶能使用此模型。 - `RETIRED`:此階段的模型已退役,無法使用。資料模型¶
Candidate¶
由模型產生的回應候選。
屬性:
index:integer
僅供輸出。候選在回應候選清單中的索引。
content:Content
僅供輸出。模型傳回的產生內容。
**finishReason**:`string enum` 選填。僅供輸出。模型停止產生權杖的原因。若為空,表示模型尚未停止產生權杖。
可能的值: - `FINISH_REASON_UNSPECIFIED`:預設值。不使用此值。 - `STOP`:模型的自然停止點或所提供的停止序列。 - `MAX_TOKENS`:已達到請求中指定的權杖數量上限。 - `SAFETY`:回應候選內容因安全理由被標記。 - `RECITATION`:回應候選內容因複誦理由被標記。 - `LANGUAGE`:回應候選內容因使用不支援的語言而被標記。 - `OTHER`:未知原因。 - `BLOCKLIST`:權杖產生因內容含有禁用詞彙而停止。 - `PROHIBITED_CONTENT`:權杖產生因可能含有禁止內容而停止。 - `SPII`:權杖產生因內容可能含有敏感個人識別資訊(SPII)而停止。 - `MALFORMED_FUNCTION_CALL`:模型產生的函式呼叫無效。 - `IMAGE_SAFETY`:權杖產生因產生的圖片含有安全違規而停止。 - `IMAGE_PROHIBITED_CONTENT`:圖片產生因產生的圖片含有其他禁止內容而停止。 - `IMAGE_OTHER`:圖片產生因其他雜項問題而停止。 - `NO_IMAGE`:預期模型會產生圖片,但未產生任何圖片。 - `IMAGE_RECITATION`:圖片產生因複誦而停止。 - `UNEXPECTED_TOOL_CALL`:模型產生了工具呼叫,但請求中未啟用任何工具。 - `TOO_MANY_TOOL_CALLS`:模型連續呼叫過多工具,因此系統結束執行。 - `MISSING_THOUGHT_SIGNATURE`:請求中至少缺少一個思考簽章。 - `MALFORMED_RESPONSE`:因回應格式錯誤而結束。 - `ESCALATION`:請求遭到升級規則篩除。 - `PUP_LIMITED_DISABLED`:表示權杖產生因使用者帳號違反禁止使用政策(PUP)而受限或停用而停止。 - `CONTINUATION`:權杖產生因回應達到單次請求的權杖上限而停止,但產生尚未完成。可透過後續請求使用傳回的 `continuation_token` 接續模型回應。請注意,`max_output_tokens` 在各次接續跳轉之間是累計的,必須單調遞增或省略。finishMessage:string
選填。僅供輸出。詳述模型停止產生權杖的原因。僅在有設定 finish_reason 時才會填入。
safetyRatings:SafetyRating array
回應候選的安全性評分清單。每個類別最多有一個評分。
citationMetadata:CitationMetadata
僅供輸出。模型產生候選的引用資訊。此欄位可能為 content 中包含的任何文字填入複誦資訊。這些是從基礎 LLM 訓練資料中的受版權保護素材「複誦」而來的段落。
tokenCount:integer
僅供輸出。此候選的權杖數量。
**groundingAttributions**:`GroundingAttribution array` 僅供輸出。為接地答覆提供貢獻的來源歸屬資訊。此欄位會為 `GenerateAnswer` 呼叫填入。
**sourceId**:`AttributionSourceId` 僅供輸出。為此歸屬提供貢獻的來源識別碼。
**source**:`Union type`
Union 欄位 `source` 只能是下列其中之一:**groundingPassage**:`GroundingPassageId` 行內段落的識別碼。
**passageId**:`string` 僅供輸出。與 `GenerateAnswerRequest` 的 `GroundingPassage.id` 相符的段落 ID。 **partIndex**:`integer` 僅供輸出。`GenerateAnswerRequest` 的 `GroundingPassage.content` 中該部分的索引。**semanticRetrieverChunk**:`SemanticRetrieverChunk` 透過 Semantic Retriever 擷取的 `Chunk` 的識別碼。
**source**:`string` 僅供輸出。與請求的 `SemanticRetrieverConfig.source` 相符的來源名稱。範例:`corpora/123` 或 `corpora/123/documents/abc` **chunk**:`string` 僅供輸出。包含歸屬文字的 `Chunk` 名稱。範例:`corpora/123/documents/abc/chunks/xyz`**groundingMetadata**:`GroundingMetadata` 僅供輸出。候選的接地中繼資料。此欄位會為 `GenerateContent` 呼叫填入。
**searchEntryPoint**:`SearchEntryPoint` 選填。後續網路搜尋的 Google 搜尋入口。
**renderedContent**:`string` 選填。可嵌入網頁或應用程式 webview 的網頁內容片段。 **sdkBlob**:`string` 選填。Base64 編碼的 JSON,表示 tuple 陣列。**groundingChunks**:`GroundingChunk array` 從指定接地來源擷取的支援參考清單。串流時,此處僅包含先前回應的接地中繼資料中尚未包含的接地區塊。
**chunkType**:`Union type` 區塊類型。
Union 欄位 `chunkType` 只能是下列其中之一:**web**:`Web` 來自網路的接地區塊。
**uri**:`string` 僅供輸出。區塊的 URI 參考。 **title**:`string` 僅供輸出。區塊的標題。**image**:`Image` 選填。來自圖片搜尋的接地區塊。
**sourceUri**:`string` 用於歸屬的網頁 URI。 **imageUri**:`string` 圖片資產 URL。 **title**:`string` 圖片所在網頁的標題。 **domain**:`string` 圖片所在網頁的根網域,例如「example.com」。**retrievedContext**:`RetrievedContext` 選填。來自檔案搜尋工具擷取內容的接地區塊。
**uri**:`string` 選填。語意擷取文件的 URI 參考。 **title**:`string` 選填。文件的標題。 **text**:`string` 選填。區塊的文字。 **fileSearchStore**:`string` 選填。包含該文件的 `FileSearchStore` 名稱。範例:`fileSearchStores/123`**customMetadata**:`GroundingChunkCustomMetadata array` 選填。使用者提供的擷取內容中繼資料。
**value**:`Union type` 中繼資料的值。可以是字串、字串清單或數字。
Union 欄位 `value` 只能是下列其中之一: **stringValue**:`string` 選填。中繼資料的字串值。**stringListValue**:`GroundingChunkStringList` 選填。中繼資料的字串值清單。
**values**:`string array` 清單的字串值。**maps**:`Maps` 選填。來自 Google Maps 的接地區塊。
**uri**:`string` 地點的 URI 參考。 **title**:`string` 地點的標題。 **text**:`string` 地點答覆的文字說明。 **placeId**:`string` 地點的 ID,格式為 `places/{place_id}`。使用者可使用此 ID 查詢該地點。**placeAnswerSources**:`PlaceAnswerSources` 提供 Google Maps 中指定地點特色相關答覆的來源。
**reviewSnippets**:`ReviewSnippet array` 用於產生 Google Maps 中指定地點特色相關答覆的評論片段。
**reviewId**:`string` 評論片段的 ID。 **googleMapsUri**:`string` 對應到 Google Maps 上使用者評論的連結。 **title**:`string` 評論的標題。**groundingSupports**:`GoogleAiGenerativelanguageV1betaGroundingSupport array` 接地支援清單。
**segment**:`GoogleAiGenerativelanguageV1betaSegment` 此支援所屬內容的區段。
**partIndex**:`integer` Part 物件在其父 Content 物件中的索引。 **startIndex**:`integer` 在指定 Part 中的起始索引,以位元組為單位。從 Part 開頭起算的偏移量,包含起始位置,從零開始。 **endIndex**:`integer` 在指定 Part 中的結束索引,以位元組為單位。從 Part 開頭起算的偏移量,不含結束位置,從零開始。 **text**:`string` 回應中對應到該區段的文字。**retrievalMetadata**:`RetrievalMetadata` 與接地流程中擷取相關的中繼資料。
**googleSearchDynamicRetrievalScore**:`number` 選填。分數表示來自 Google 搜尋的資訊能幫助回答提示詞的可能性。分數範圍為 [0, 1],0 表示可能性最低,1 表示可能性最高。此分數僅在啟用 Google 搜尋接地與動態擷取時才會填入。它會與門檻比較,以決定是否觸發 Google 搜尋。avgLogprobs:number
僅供輸出。候選的平均對數機率分數。
**logprobsResult**:`LogprobsResult` 僅供輸出。回應權杖與頂尖權杖的對數概似分數
**logProbabilitySum**:`number` 所有權杖的對數機率總和。**topCandidates**:`TopCandidates array` 長度 = 解碼步驟總數。
**candidates**:`LogprobsResultCandidate array` 依對數機率降冪排序。
**token**:`string` 候選的權杖字串值。 **tokenId**:`integer` 候選的權杖 ID 值。 **logProbability**:`number` 候選的對數機率。**chosenCandidates**:`LogprobsResultCandidate array` 長度 = 解碼步驟總數。所選候選可能在 top_candidates 中,也可能不在其中。
**token**:`string` 候選的權杖字串值。 **tokenId**:`integer` 候選的權杖 ID 值。 **logProbability**:`number` 候選的對數機率。**urlContextMetadata**:`UrlContextMetadata` 僅供輸出。與 URL 上下文擷取工具相關的中繼資料。
**urlMetadata**:`UrlMetadata array` URL 上下文清單。
**retrievedUrl**:`string` 工具擷取的 URL。**urlRetrievalStatus**:`string enum` URL 擷取的狀態。
可能的值: - `URL_RETRIEVAL_STATUS_UNSPECIFIED`:預設值。不使用此值。 - `URL_RETRIEVAL_STATUS_SUCCESS`:URL 擷取成功。 - `URL_RETRIEVAL_STATUS_ERROR`:URL 擷取因錯誤而失敗。 - `URL_RETRIEVAL_STATUS_PAYWALL`:URL 擷取因內容位於付費牆後而失敗。 - `URL_RETRIEVAL_STATUS_UNSAFE`:URL 擷取因內容不安全而失敗。continuationToken:string
當 finish_reason 為 CONTINUATION 時傳回的選填不透明接續權杖。用戶端可在後續的 GenerateContentRequest 中傳入此權杖,以接續產生。
CitationMetadata¶
一段內容的來源歸屬集合。
屬性:
**citationSources**:`CitationSource array` 特定回應的來源引用。
**startIndex**:`integer` 選填。歸屬於此來源的回應區段起始位置。索引表示區段的起始,以位元組為單位。 **endIndex**:`integer` 選填。歸屬區段的結束位置,不含結束點。 **uri**:`string` 選填。被歸屬為某段文字來源的 URI。 **license**:`string` 選填。被歸屬為區段來源的 GitHub 專案授權。程式碼引用需要提供授權資訊。HarmCategory¶
可能的值:
HARM_CATEGORY_UNSPECIFIED:未指定類別。HARM_CATEGORY_HARASSMENT:Gemini - 騷擾內容。HARM_CATEGORY_HATE_SPEECH:Gemini - 仇恨言論與內容。HARM_CATEGORY_SEXUALLY_EXPLICIT:Gemini - 性露骨內容。HARM_CATEGORY_DANGEROUS_CONTENT:Gemini - 危險內容。HARM_CATEGORY_JAILBREAK:Gemini - 嘗試繞過或顛覆模型安全準則的提示詞(越獄嘗試)。
ModalityTokenCount¶
表示單一模態的權杖計算資訊。
屬性:
**modality**:`GenerativeLanguageModality` 與此權杖數量相關聯的模態。
可能的值: - `MODALITY_UNSPECIFIED`:未指定的模態。 - `TEXT`:純文字。 - `IMAGE`:圖片。 - `VIDEO`:影片。 - `AUDIO`:音訊。 - `DOCUMENT`:文件,例如 PDF。tokenCount:integer
權杖數量。
SafetyRating¶
一段內容的安全性評分。
安全性評分包含一段內容的危害類別,以及該類別中的危害機率等級。內容會跨多個危害類別進行安全分類,危害分類的機率包含在此處。
屬性:
**category**:必填 [`HarmCategory`](/api-reference/generate-content/stream-generate-content/#Resource:HarmCategory) 此評分的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`:未指定類別。 - `HARM_CATEGORY_HARASSMENT`:**Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`:**Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`:**Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`:**Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`:**Gemini** - 嘗試繞過或顛覆模型安全準則的提示詞(越獄嘗試)。**probability**:必填 `string enum` 此內容的危害機率。
可能的值: - `HARM_PROBABILITY_UNSPECIFIED`:未指定機率。 - `NEGLIGIBLE`:內容不安全的可能性微乎其微。 - `LOW`:內容不安全的可能性低。 - `MEDIUM`:內容不安全的可能性中等。 - `HIGH`:內容不安全的可能性高。blocked:boolean
此內容是否因這項評分而遭到封鎖?
SafetySetting¶
安全設定,影響安全封鎖行為。
為某個類別傳入安全設定,會改變內容遭到封鎖的允許機率。
屬性:
**category**:必填 [`HarmCategory`](/api-reference/generate-content/stream-generate-content/#Resource:HarmCategory) 此設定的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`:未指定類別。 - `HARM_CATEGORY_HARASSMENT`:**Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`:**Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`:**Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`:**Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`:**Gemini** - 嘗試繞過或顛覆模型安全準則的提示詞(越獄嘗試)。**threshold**:必填 `string enum` 控制封鎖危害的機率門檻。
可能的值: - `HARM_BLOCK_THRESHOLD_UNSPECIFIED`:未指定門檻。 - `BLOCK_LOW_AND_ABOVE`:允許 NEGLIGIBLE 的內容。 - `BLOCK_MEDIUM_AND_ABOVE`:允許 NEGLIGIBLE 與 LOW 的內容。 - `BLOCK_ONLY_HIGH`:允許 NEGLIGIBLE、LOW 與 MEDIUM 的內容。 - `BLOCK_NONE`:允許所有內容。 - `OFF`:關閉安全篩選器。ServiceTier¶
可能的值:
unspecified:預設服務層級,即標準層級。standard:標準服務層級。flex:Flex 服務層級。priority:Priority 服務層級。
Content¶
包含訊息多部分內容的基礎結構化資料類型。
Content 包含一個 role 欄位,用於指定 Content 的產生者,以及一個 parts 欄位,包含構成訊息回合內容的多部分資料。
屬性:
**parts**:`Part array` 組成單一訊息的已排序 `Parts`。各部分可能有不同的 MIME 類型。
**data**:`Union type`
Union 欄位 `data` 只能是下列其中之一: **text**:`string` 行內文字。**inlineData**:`Blob` 行內媒體位元組。
**mimeType**:`string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png、image/jpeg、image/jpg、image/webp、image/heic、image/heif、image/gif、image/avif - 音訊:audio/*、video/audio/s16le、video/audio/wav - 影片:video/* - 文字:text/plain、text/html、text/css、text/javascript、text/x-typescript、text/csv、text/markdown、text/x-python、text/xml、text/rtf、video/text/timestamp - 應用程式:application/x-javascript、application/x-typescript、application/x-python-code、application/json、application/x-ipynb+json、application/rtf、application/pdf。其他上下文請參閱[支援的檔案格式](/docs/file-input-methods/#supported-content-types)。 **data**:`string` 媒體格式的原始位元組。 **displayName**:`string` 選填。指定用來向模型指稱此 blob 的名稱(例如「my_blob.png」)。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,用作 blob 參考識別碼。**functionCall**:`FunctionCall` 模型傳回的預測 `FunctionCall`,包含一個代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**:必填 `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與破折號,長度上限為 128。 **id**:`string` 選填。函式呼叫的唯一識別碼。若有填入,用戶端應執行該 `function_call`,並以相符的 `id` 傳回回應。 **args**:`object` 選填。JSON 物件格式的函式參數與值。**functionResponse**:`FunctionResponse` `FunctionCall` 的結果輸出,包含一個代表 `FunctionDeclaration.name` 的字串,以及一個包含函式任何輸出的結構化 JSON 物件,用作模型的上下文。
**name**:必填 `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與破折號,長度上限為 128。 **response**:必填 `object` JSON 物件格式的函式回應。呼叫者可使用任何符合函式語法的自選鍵來傳回函式輸出,例如「output」、「result」等。特別是,若函式呼叫執行失敗,回應可包含「error」鍵,將錯誤詳情傳回給模型。多媒體可透過包含單一「$ref」鍵的子物件納入,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體的 `FunctionResponsePart`。請參閱[多模態函式回應](/docs/function-calling/#multimodal)。 **id**:`string` 選填。此回應所對應的函式呼叫識別碼。由用戶端填入,以與對應的函式呼叫 `id` 相符。**parts**:`FunctionResponsePart array` 選填。組成函式回應的已排序 `Parts`。各部分可能有不同的 IANA MIME 類型。
**data**:`Union type` 函式回應部分的資料。
Union 欄位 `data` 只能是下列其中之一:**inlineData**:`FunctionResponseBlob` 行內媒體位元組。
**mimeType**:`string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。完整支援類型清單請參閱[支援的檔案格式](/docs/file-input-methods/#supported-content-types)。 **data**:`string` 媒體格式的原始位元組。 **displayName**:`string` 選填。blob 的顯示名稱。用於提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**:`FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**:必填 `string` URI。 **mimeType**:`string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。完整支援類型清單請參閱[多模態函式回應](/docs/function-calling/#multimodal)與[支援的檔案格式](/docs/file-input-methods/#supported-content-types)。 **displayName**:`string` 選填。檔案的顯示名稱。用於提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**:`string enum` 選填。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或 MIME 為影片的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`:預設為模型專屬的處理方式。 - `STATIC`:固定速率影格擷取。所有影格都放入上下文。 - `AGENTIC`:模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**:`string enum` 選填。指定回應在對話中應如何排程。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`:不使用此值。 - `SILENT`:僅將結果加入對話上下文,不中斷也不觸發產生。 - `WHEN_IDLE`:將結果加入對話上下文,並提示產生輸出,但不中斷進行中的產生。 - `INTERRUPT`:將結果加入對話上下文,中斷進行中的產生,並提示產生輸出。**fileData**:`FileData` 以 URI 為基礎的資料。
**fileUri**:必填 `string` URI。 **mimeType**:`string` 選填。來源資料的 IANA 標準 MIME 類型。 **displayName**:`string` 選填。指定用來向模型指稱此檔案的名稱(例如「my_file.pdf」)。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,用作檔案參考識別碼。**executableCode**:`ExecutableCode` 模型產生、供執行的程式碼。
**language**:必填 `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`:未指定的語言。不應使用此值。 - `PYTHON`:Python >= 3.10,可使用 numpy 與 simpy。Python 是預設語言。**codeExecutionResult**:`CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**:必填 `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`:未指定的狀態。不應使用此值。 - `OUTCOME_OK`:程式碼執行成功完成。`output` 包含 stdout(如有)。 - `OUTCOME_FAILED`:程式碼執行失敗。`output` 包含 stderr 與 stdout(如有)。 - `OUTCOME_DEADLINE_EXCEEDED`:程式碼執行時間過長,已被取消。可能有、也可能沒有部分 `output`。**toolCall**:`ToolCall` 伺服器端工具呼叫。當模型預測應在伺服器上執行的工具叫用時,會填入此欄位。預期用戶端會將此訊息回傳給 API。
**toolType**:必填 `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`:未指定的工具類型。 - `GOOGLE_SEARCH_WEB`:Google 搜尋工具,對應到 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`:圖片搜尋工具,對應到 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`:URL 上下文工具,對應到 Tool.url_context。 - `GOOGLE_MAPS`:Google Maps 工具,對應到 Tool.google_maps。 - `FILE_SEARCH`:檔案搜尋工具,對應到 Tool.file_search。 - `MEDIA_PROCESSING`:媒體處理工具類型(例如影片、音訊等),對應到用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**:`ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端以執行對應 `ToolCall` 的結果填入。
**toolType**:必填 `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`:未指定的工具類型。 - `GOOGLE_SEARCH_WEB`:Google 搜尋工具,對應到 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`:圖片搜尋工具,對應到 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`:URL 上下文工具,對應到 Tool.url_context。 - `GOOGLE_MAPS`:Google Maps 工具,對應到 Tool.google_maps。 - `FILE_SEARCH`:檔案搜尋工具,對應到 Tool.file_search。 - `MEDIA_PROCESSING`:媒體處理工具類型(例如影片、音訊等),對應到用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**:`Union type` 控制資料的額外前置處理。當存在 `inline_data` 或 `file_data` 時設定此項,以設定每個部分的靜態媒體前置處理。
Union 欄位 `metadata` 只能是下列其中之一:**videoMetadata**:`VideoMetadata` 選填。影片中繼資料。中繼資料僅應在影片資料以 inline_data 或 file_data 呈現時指定。
**startOffset**:`string` 選填。影片的起始偏移量。 **endOffset**:`string` 選填。影片的結束偏移量。 **fps**:`number` 選填。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**:`V1mainMediaResolution` 選填。輸入媒體的媒體解析度。
**value**:`Union type` 媒體解析度等級。
Union 欄位 `value` 只能是下列其中之一:**level**:`string enum` 用於指定媒體的權杖化品質。適用於 Gemini API 支援。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`:尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`:媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`:媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`:媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`:媒體解析度設為超高。**mediaProcessing**:`string enum` 選填。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或 MIME 為影片的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`:預設為模型專屬的處理方式。 - `STATIC`:固定速率影格擷取。所有影格都放入上下文。 - `AGENTIC`:模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**:`AudioTranscription` 選填。音訊(輸入或輸出)轉錄。僅在此 Part 包含音訊資料時才會設定。
**text**:必填 `string` 此音訊區段的轉錄文字。 **speakerLabel**:`string` 選填。識別此音訊區段說話者的標籤(例如「spk_1」、「spk_2」)。在有設定 diarization 時出現。**words**:`WordInfo array` 選填。詳細的逐字轉錄與時間詳情。在有設定 word_timestamp 時出現。
**word**:必填 `string` 單字的轉錄。 **startOffset**:`string` 選填。單字相對於音訊開頭的起始時間偏移量。 **endOffset**:`string` 選填。單字相對於音訊開頭的結束時間偏移量。**speechMetadata**:`SpeechMetadata` 選填。套用於文字部分的中繼資料,用於自訂其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**:`string` 選填。多說話者合成的選填說話者名稱。 **style**:`string` 選填。語音合成的選填風格指令。role:string
選填。內容的產生者。必須為「user」或「model」其中之一。設定此項對多輪對話很有用,否則可留空或不設定。
Schema¶
Schema 物件允許定義輸入與輸出資料類型。這些類型可以是物件,也可以是原始型別與陣列。表示 OpenAPI 3.0 架構物件的精選子集。
屬性:
**type**:必填 `Type` 資料類型。
可能的值: - `TYPE_UNSPECIFIED`:未指定,不應使用。 - `STRING`:字串類型。 - `NUMBER`:數字類型。 - `INTEGER`:整數類型。 - `BOOLEAN`:布林類型。 - `ARRAY`:陣列類型。 - `OBJECT`:物件類型。 - `NULL`:Null 類型。format:string
選填。資料的格式。允許任何值,但大多數值不會觸發任何特殊功能。
title:string
選填。架構的標題。
description:string
選填。參數的簡短說明。可包含使用範例。參數說明可使用 Markdown 格式。
nullable:boolean
選填。表示值是否可為 null。
enum:string array
選填。具有 enum 格式的 Type.STRING 元素的可能值。例如,我們可以將 Enum Direction 定義為:{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}
items:Schema
選填。Type.ARRAY 元素的架構。
maxItems:string
選填。Type.ARRAY 的元素數量上限。
minItems:string
選填。Type.ARRAY 的元素數量下限。
properties:object
選填。Type.OBJECT 的屬性。
required:string array
選填。Type.OBJECT 的必填屬性。
minProperties:string
選填。Type.OBJECT 的屬性數量下限。
maxProperties:string
選填。Type.OBJECT 的屬性數量上限。
minimum:number
選填。TYPE INTEGER 與 NUMBER 的架構欄位。Type.INTEGER 與 Type.NUMBER 的最小值。
maximum:number
選填。Type.INTEGER 與 Type.NUMBER 的最大值。
minLength:string
選填。TYPE STRING 的架構欄位。Type.STRING 的最小長度。
maxLength:string
選填。Type.STRING 的最大長度。
pattern:string
選填。Type.STRING 的模式,用於將字串限制為正規表示式。
example:object
選填。物件的範例。僅在物件為根物件時才會填入。
anyOf:Schema array
選填。值應對照清單中任一(一個或多個)子架構進行驗證。
propertyOrdering:string array
選填。屬性的順序。不是 Open API 規格中的標準欄位。用於決定回應中屬性的順序。
default:object
選填。欄位的預設值。依 JSON Schema,此欄位是供文件產生器使用,不影響驗證。因此在此納入並忽略,讓傳送帶有 default 欄位的架構的開發人員不會收到未知欄位錯誤。
Tool¶
模型可用於產生回應的工具詳情。
Tool 是一段程式碼,讓系統能與外部系統互動,在模型的知識與範圍之外執行某個動作或一組動作。
屬性: