使用 Chat Completions API 呼叫 Gemini
以下範例說明如何傳送非串流要求:
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \ -d '{ "model": "google/${MODEL_ID}", "messages": [{ "role": "user", "content": "Write a story about a magic backpack." }] }'
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Agent Platform Python API 參考文件。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
下列範例說明如何使用 Chat Completions API,將串流要求傳送至 Gemini 模型:
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \ -d '{ "model": "google/${MODEL_ID}", "stream": true, "messages": [{ "role": "user", "content": "Write a story about a magic backpack." }] }'
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Agent Platform Python API 參考文件。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
在 Gemini Enterprise Agent Platform 中,將提示和圖片傳送至 Gemini API
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Agent Platform Python API 參考文件。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
使用 Chat Completions API 呼叫自行部署的模型
以下範例說明如何傳送非串流要求:
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \ -d '{ "messages": [{ "role": "user", "content": "Write a story about a magic backpack." }] }'
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Agent Platform Python API 參考文件。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
下列範例說明如何使用 Chat Completions API,將串流要求傳送至自行部署的模型:
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \ -d '{ "stream": true, "messages": [{ "role": "user", "content": "Write a story about a magic backpack." }] }'
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Agent Platform Python API 參考文件。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
extra_body 個樣本
您可以透過 SDK 或 REST API 傳遞 extra_body。
新增「thought_tag_marker」
{
...,
"extra_body": {
"google": {
...,
"thought_tag_marker": "..."
}
}
}
使用 SDK 新增 extra_body
client.chat.completions.create(
...,
extra_body = {
'extra_body': { 'google': { ... } }
},
)
extra_content 個樣本
您可以直接使用 REST API 填入這個欄位。
extra_content 字串 content
{
"messages": [
{ "role": "...", "content": "...", "extra_content": { "google": { ... } } }
]
}
每則訊息 extra_content
{
"messages": [
{
"role": "...",
"content": [
{ "type": "...", ..., "extra_content": { "google": { ... } } }
]
}
}
每次工具呼叫 extra_content
{
"messages": [
{
"role": "...",
"tool_calls": [
{
...,
"extra_content": { "google": { ... } }
}
]
}
]
}
curl 要求範例
您可以直接使用這些 curl 要求,不必透過 SDK。
透過 thinking_config 支付 extra_body 費用
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
-d '{ \
"model": "google/gemini-2.5-flash-preview-04-17", \
"messages": [ \
{ "role": "user", \
"content": [ \
{ "type": "text", \
"text": "Are there any primes number of the form n*ceil(log(n))" \
}] }], \
"extra_body": { \
"google": { \
"thinking_config": { \
"include_thoughts": true, "thinking_budget": 10000 \
}, \
"thought_tag_marker": "think" } }, \
"stream": true }'
使用stream_function_call_arguments
要求範例:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
-d '{
"model": "google/gemini-3.1-pro-preview", \
"messages": [ \
{ "role": "user", "content": "What is the weather like in Boston and New Delhi today?" } ], \
"tools": [ \
{ \
"type": "function", \
"function": { \
"name": "get_current_weather", \
"description": "Get the current weather in a given location", \
"parameters": { \
"type": "object", \
"properties": { \
"location": { \
"type": "string", \
"description": "The city and state, e.g. San Francisco, CA" \
}, \
"unit": { \
"type": "string", \
"enum": [ \
"celsius", \
"fahrenheit" \
] \
} \
}, \
"required": [ \
"location", \
"unit" \
] \
} \
} \
} \
], \
"extra_body": { \
"google": { \
"stream_function_call_arguments": true \
} \
}, \
"stream": true \
}'
回覆範例:
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"extra_content":{"google":{"thought_signature":"..."}},"function":{"arguments":"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"{\"location\":\"Boston, MA","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":",\"unit\":\"celsius","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"}","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"{\"location\":\"New Delhi, India","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":",\"unit\":\"celsius","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}
data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"}","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"finish_reason":"tool_calls","index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":"","usage":{"completion_tokens":45,"completion_tokens_details":{"reasoning_tokens":504},"extra_properties":{"google":{"traffic_type":"PROVISIONED_THROUGHPUT"}},"prompt_tokens":27,"total_tokens":576}}
data: [DONE]
圖像生成
為確保與 OpenAI 回應格式相容,回應的 audio 欄位會明確填入 extra_content.google.mime_type,指出結果的 MIME 類型。
要求範例:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
-d '{"model":"google/gemini-3-pro-image-preview", "messages":[{ "role": "user", "content": "Generate an image of a cat." }], "modalities": ["image"] }'
回應範例:
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"audio": {
"data": "<BASE64_BYTES>",
"extra_content": {
"google": {
"mime_type": "image/png"
}
}
},
"content": null,
"extra_content": {
"google": {
"thought_signature": "..."
}
},
"role": "assistant"
}
}
],
"created": 1770850692,
"id": "hAmNaZb8BZOX4_UPlNXoEA",
"model": "google/gemini-3-pro-image-preview",
"object": "chat.completion",
"system_fingerprint": "",
"usage": {
"completion_tokens": 1120,
"completion_tokens_details": {
"reasoning_tokens": 251
},
"extra_properties": {
"google": {
"traffic_type": "PROVISIONED_THROUGHPUT"
}
},
"prompt_tokens": 7,
"total_tokens": 1378
}
}
多模態要求
Chat Completions API 支援多種多模態輸入內容,包括音訊和影片。
使用 image_url 傳遞圖片資料
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
-d '{ \
"model": "google/gemini-2.0-flash-001", \
"messages": [{ "role": "user", "content": [ \
{ "type": "text", "text": "Describe this image" }, \
{ "type": "image_url", "image_url": "gs://cloud-samples-data/generative-ai/image/scones.jpg" }] }] }'
使用 input_audio 傳入音訊資料
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
-d '{ \
"model": "google/gemini-2.0-flash-001", \
"messages": [ \
{ "role": "user", \
"content": [ \
{ "type": "text", "text": "Describe this: " }, \
{ "type": "input_audio", "input_audio": { \
"format": "audio/mp3", \
"data": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3" } }] }] }'
多模態函式回覆
要求範例:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
-d '{ \
"model": "google/gemini-3.1-pro-preview", \
"messages": [ \
{ "role": "user", "content": "Show me the green shirt I ordered last month." }, \
{ \
"role": "assistant", \
"tool_calls": [ \
{ \
"extra_content": { \
"google": { \
"thought_signature": "<THOUGHT_SIGNATURE>" \
} \
}, \
"function": { \
"arguments": "{\"item_name\":\"green shirt\"}", \
"name": "get_image" \
}, \
"id": "function-call-a350228d-0283-4792-8bfa-40da064fb959", \
"type": "function" \
} \
] \
}, \
{ \
"role": "tool", \
"tool_call_id": "function-call-a350228d-0283-4792-8bfa-40da064fb959", \
"content": "{\"image_ref\":{\"$ref\":\"dress.jpg\"}}", \
"extra_content": { \
"google": { \
"parts": [ \
{ \
"file_data": { \
"mime_type": "image/jpg", \
"display_name": "dress.jpg", \
"file_uri": "gs://cloud-samples-data/generative-ai/image/dress.jpg" \
} \
} \
] \
} \
} \
} \
], \
"tools": [ \
{ \
"type": "function", \
"function": { \
"name": "get_image", \
"description": "Retrieves the image file reference for a specific order item.", \
"parameters": { \
"type": "object", \
"properties": { \
"item_name": { \
"type": "string", \
"description": "The name or description of the item ordered (e.g., 'green shirt')." \
} \
}, \
"required": [ \
"item_name" \
] \
} \
} \
} \
] \
}'
回應範例:
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Here is the image of the green shirt you ordered.",
"role": "assistant"
}
}
],
"created": 1770852204,
"id": "bA-NacCPKoae_9MPsNCn6Qc",
"model": "google/gemini-3.1-pro-preview",
"object": "chat.completion",
"system_fingerprint": "",
"usage": {
"completion_tokens": 16,
"extra_properties": {
"google": {
"traffic_type": "ON_DEMAND"
}
},
"prompt_tokens": 1139,
"total_tokens": 1155
}
}
結構化輸出內容
您可以使用 response_format 參數取得結構化輸出內容。
使用 SDK 的範例
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
completion = client.beta.chat.completions.parse(
model="google/gemini-2.5-flash-preview-04-17",
messages=[
{"role": "system", "content": "Extract the event information."},
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
],
response_format=CalendarEvent,
)
print(completion.choices[0].message.parsed)
在 OpenAI 相容模式中使用全域端點
下列範例說明如何在 OpenAI 相容模式中使用全域端點:
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions\ -d '{ \ "model": "google/gemini-2.0-flash-001", \ "messages": [ \ {"role": "user", \ "content": "Hello World" \ }] \ }'
後續步驟
- 請參閱呼叫 Inference API 的範例,瞭解如何使用與 OpenAI 相容的語法。
- 請參閱使用 OpenAI 相容語法呼叫 Function Calling API 的範例。
- 進一步瞭解 Gemini API。
- 進一步瞭解如何從 Azure OpenAI 遷移至 Gemini API。