Generating content  |  Gemini API  |  Google AI for Developers
التخطّي إلى المحتوى الرئيسي
/
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어
الحصول على مفتاح واجهة برمجة التطبيقات
كتاب الطبخ
منتدى
تسجيل الدخول
المستندات
مرجع واجهة برمجة التطبيقات
Gemini API
المستندات
مرجع واجهة برمجة التطبيقات
الحصول على مفتاح واجهة برمجة التطبيقات
كتاب الطبخ
منتدى
نظرة عامة
إصدارات واجهة برمجة التطبيقات
واجهات برمجة التطبيقات الأساسية
واجهة برمجة التطبيقات Interactions API
GenerateContent
واجهات برمجة التطبيقات في الوقت الفعلي
واجهة برمجة التطبيقات للبث المباشر
Live Music API
واجهات برمجة التطبيقات للنظام الأساسي
Model API
الوكلاء
الردّ التلقائي على الويب
Batch API
واجهة برمجة تطبيقات الملفات
الرموز المميزة
تخزين مؤقت
التضمينات
File Search API
متاجر البحث عن الملفات
المستندات
جميع الطرق
مراجع حِزم تطوير البرامج (SDK)
Python
Go
TypeScript
Java
C#
أصبحت Interactions API متاحة الآن للجميع. ننصحك باستخدام واجهة برمجة التطبيقات هذه للوصول إلى جميع أحدث الميزات والنماذج.
Google uses AI technology to translate content into your preferred language. AI translations can contain errors.
الصفحة الرئيسية
Gemini API
مرجع واجهة برمجة التطبيقات
إرسال ملاحظات
Generating content
تتيح Gemini API إنشاء المحتوى باستخدام الصور والمحتوى الصوتي والرموز البرمجية والأدوات وغير ذلك. للاطّلاع على تفاصيل حول كل ميزة من هذه الميزات، تابِع القراءة واطّلِع على نموذج الرمز البرمجي الذي يركّز على المهام، أو اقرأ الأدلة الشاملة.
إنشاء النصوص
النظر
الصوت
التضمينات
السياق الطويل
تنفيذ الرموز البرمجية
وضع JSON
استدعاء الدوال
تعليمات النظام
الطريقة: models.generateContent
نقطة النهاية
مَعلمات المسار
نص الطلب
تمثيل JSON
نص الاستجابة
نطاقات الأذونات
مثال على الطلب
Text
صورة
الصوت
الفيديو
PDF
Chat
ذاكرة التخزين المؤقت
النموذج المضبوط
وضع JSON
تنفيذ الرموز البرمجية
استدعاء الدوال
إعدادات الإنشاء
إعدادات الأمان
تعليمات النظام
ينشئ ردًا من النموذج بناءً على إدخال GenerateContentRequest. يُرجى الرجوع إلى دليل إنشاء النصوص للحصول على معلومات مفصّلة حول الاستخدام. تختلف إمكانات الإدخال بين النماذج، بما في ذلك النماذج المضبوطة. يُرجى الرجوع إلى دليل النماذج ودليل الضبط للاطّلاع على التفاصيل.
نقطة نهاية
post
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
مَعلمات المسار
model
string
الحقل مطلوب. اسم Model المطلوب استخدامه لإنشاء الإكمال
التنسيق: models/{model} ويكون بالتنسيق التالي: models/{model}.
نص الطلب
يتضمن نص الطلب بيانات بالبنية التالية:
الحقول
contents[]
object (Content)
الحقل مطلوب. محتوى المحادثة الحالية مع النموذج
بالنسبة إلى طلبات البحث ذات الدورة الواحدة، يكون هذا مثيلاً واحدًا. بالنسبة إلى الاستعلامات المتعددة الأدوار، مثل المحادثة، هذا حقل متكرّر يحتوي على سجلّ المحادثات وآخر طلب.
tools[]
object (Tool)
اختياريّ. قائمة Tools يمكن Model استخدامها لإنشاء الرد التالي
Tool هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع الأنظمة الخارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة Model. Tool المتاحة هي Function وcodeExecution. لمزيد من المعلومات، يُرجى الرجوع إلى دليلَي استدعاء الدوال وتنفيذ الرمز.
toolConfig
object (ToolConfig)
اختياريّ. إعدادات الأداة لأي Tool محدّدة في الطلب راجِع دليل استدعاء الدوال للاطّلاع على مثال على الاستخدام.
safetySettings[]
object (SafetySetting)
اختياريّ. قائمة بحالات SafetySetting الفريدة لحظر المحتوى غير الآمن
سيتم تطبيق هذا الشرط على GenerateContentRequest.contents وGenerateContentResponse.candidates. يجب ألا يكون هناك أكثر من إعداد واحد لكل نوع SafetyCategory. ستحظر واجهة برمجة التطبيقات أي محتوى وردود لا تستوفي الحدود التي تحدّدها هذه الإعدادات. تلغي هذه القائمة الإعدادات التلقائية لكل SafetyCategory محدّد في safetySettings. إذا لم يكن هناك SafetySetting لفئة SafetyCategory معيّنة مقدَّمة في القائمة، ستستخدِم واجهة برمجة التطبيقات إعدادات الأمان التلقائية لهذه الفئة. تتوفّر فئات الضرر HARM_CATEGORY_HATE_SPEECH وHARM_CATEGORY_SEXUALLY_EXPLICIT وHARM_CATEGORY_DANGEROUS_CONTENT وHARM_CATEGORY_HARASSMENT وHARM_CATEGORY_CIVIC_INTEGRITY. راجِع الدليل للحصول على معلومات تفصيلية حول إعدادات الأمان المتاحة. يمكنك أيضًا الرجوع إلى إرشادات الأمان للتعرّف على كيفية تضمين اعتبارات الأمان في تطبيقات الذكاء الاصطناعي.
systemInstruction
object (Content)
اختياريّ. يضع المطوّر تعليمات النظام. في الوقت الحالي، يمكن إدخال نص فقط.
generationConfig
object (GenerationConfig)
اختياريّ. خيارات الإعداد لإنشاء النماذج والمخرجات
cachedContent
string
اختياريّ. اسم المحتوى المخزَّن مؤقتًا لاستخدامه كسياق لعرض التوقّع التنسيق: cachedContents/{cachedContent}
serviceTier
enum (ServiceTier)
اختياريّ. فئة الخدمة للطلب
store
boolean
اختياريّ. تضبط هذه السمة سلوك التسجيل لطلب معيّن. في حال ضبطها، تكون لها الأولوية على إعدادات التسجيل على مستوى المشروع.
مثال على الطلب
نص
Python
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash", contents="Write a story about a magic backpack."
)
print(response.text)
text_generation.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: "Write a story about a magic backpack.",
});
console.log(response.text);
text_generation.js
Go
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),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
printResponse(response)
text_generation.go
محارة
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[{"text": "Write a story about a magic backpack."}]
}]
}' 2> /dev/null
text_generation.sh
جافا
Client client = new Client();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
"Write a story about a magic backpack.",
null);
System.out.println(response.text());
TextGeneration.java
صورة
Python
from google import genai
import PIL.Image
client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content(
model="gemini-3.5-flash", contents=["Tell me about this instrument", organ]
)
print(response.text)
text_generation.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: [
createUserContent([
"Tell me about this instrument",
createPartFromUri(organ.uri, organ.mimeType)
]),
],
});
console.log(response.text);
text_generation.js
Go
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),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
printResponse(response)
text_generation.go
محارة
# 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-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
text_generation.sh
جافا
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"));
GenerateContentResponse response = client.models.generateContent("gemini-3.5-flash", content, null);
System.out.println(response.text());
TextGeneration.java
الصوت
Python
from google import genai
client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=["Give me a summary of this audio file.", sample_audio],
)
print(response.text)
text_generation.py
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const audio = await ai.files.upload({
file: path.join(media, "sample.mp3"),
});
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: [
createUserContent([
"Give me a summary of this audio file.",
createPartFromUri(audio.uri, audio.mimeType),
]),
],
});
console.log(response.text);
text_generation.js
Go
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),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
printResponse(response)
text_generation.go
محارة
# 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-2.0-flash:generateContent?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
jq ".candidates[].content.parts[].text" response.json
text_generation.sh
فيديو
Python
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(
model="gemini-3.5-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{response.text=}")
text_generation.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: [
createUserContent([
"Describe this video clip",
createPartFromUri(video.uri, video.mimeType),
]),
],
});
console.log(response.text);
text_generation.js
Go
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),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
printResponse(response)
text_generation.go
محارة
# 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
# 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 "${tmp_header_file}" \
-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
name=$(jq ".file.name" file_info.json)
echo name=$name
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-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."},
{"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
text_generation.sh
PDF
Python
from google import genai
client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=["Give me a summary of this document:", sample_pdf],
)
print(f"{response.text=}")
text_generation.py
Go
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),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, nil)
if err != nil {
log.Fatal(err)
}
printResponse(response)
text_generation.go
محارة
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-2.0-flash:generateContent?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
jq ".candidates[].content.parts[].text" response.json
text_generation.sh
محادثة
Python
from google import genai
from google.genai import types
client = genai.Client()
# Pass initial history using the "history" argument
chat = client.chats.create(
model="gemini-3.5-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(message="I have 2 dogs in my house.")
print(response.text)
response = chat.send_message(message="How many paws are in my house?")
print(response.text)
chat.py
Node.js
// 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.5-flash",
history: [
{
role: "user",
parts: [{ text: "Hello" }],
},
{
role: "model",
parts: [{ text: "Great to meet you. What would you like to know?" }],
},
],
});
const response1 = await chat.sendMessage({
message: "I have 2 dogs in my house.",
});
console.log("Chat response 1:", response1.text);
const response2 = await chat.sendMessage({
message: "How many paws are in my house?",
});
console.log("Chat response 2:", response2.text);
chat.js
Go
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)
}
// Pass initial history using the History field.
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.5-flash", nil, history)
if err != nil {
log.Fatal(err)
}
firstResp, err := chat.SendMessage(ctx, genai.Part{Text: "I have 2 dogs in my house."})
if err != nil {
log.Fatal(err)
}
fmt.Println(firstResp.Text())
secondResp, err := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
if err != nil {
log.Fatal(err)
}
fmt.Println(secondResp.Text())
chat.go
محارة
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?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"
chat.sh
جافا
Client client = new Client();
Content userContent = Content.fromParts(Part.fromText("Hello"));
Content modelContent =
Content.builder()
.role("model")
.parts(
Collections.singletonList(
Part.fromText("Great to meet you. What would you like to know?")
)
).build();
Chat chat = client.chats.create(
"gemini-3.5-flash",
GenerateContentConfig.builder()
.systemInstruction(userContent)
.systemInstruction(modelContent)
.build()
);
GenerateContentResponse response1 = chat.sendMessage("I have 2 dogs in my house.");
System.out.println(response1.text());
GenerateContentResponse response2 = chat.sendMessage("How many paws are in my house?");
System.out.println(response2.text());
ChatSession.java
ذاكرة التخزين المؤقت
Python
from google import genai
from google.genai import types
client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.5-flash"
cache = client.caches.create(
model=model_name,
config=types.CreateCachedContentConfig(
contents=[document],
system_instruction="You are an expert analyzing transcripts.",
),
)
print(cache)
response = client.models.generate_content(
model=model_name,
contents="Please summarize this transcript",
config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
cache.py
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
file: filePath,
config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-3.5-flash";
const contents = [
createUserContent(createPartFromUri(document.uri, document.mimeType)),
];
const cache = await ai.caches.create({
model: modelName,
config: {
contents: contents,
systemInstruction: "You are an expert analyzing transcripts.",
},
});
console.log("Cache created:", cache);
const response = await ai.models.generateContent({
model: modelName,
contents: "Please summarize this transcript",
config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
cache.js
Go
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)
}
modelName := "gemini-3.5-flash"
document, err := client.Files.UploadFromPath(
ctx,
filepath.Join(getMedia(), "a11.txt"),
&genai.UploadFileConfig{
MIMEType : "text/plain",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
Contents: contents,
SystemInstruction: genai.NewContentFromText(
"You are an expert analyzing transcripts.", genai.RoleUser,
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)
// Use the cache for generating content.
response, err := client.Models.GenerateContent(
ctx,
modelName,
genai.Text("Please summarize this transcript"),
&genai.GenerateContentConfig{
CachedContent: cache.Name,
},
)
if err != nil {
log.Fatal(err)
}
printResponse(response)
cache.go
نموذج معدَّل
Python
# With Gemini 2 we're launching a new SDK. See the following doc for details.
# https://ai.google.dev/gemini-api/docs/migrate
README.md
وضع JSON
Python
from google import genai
from google.genai import types
from typing_extensions import TypedDict
class Recipe(TypedDict):
recipe_name: str
ingredients: list[str]
client = genai.Client()
result = client.models.generate_content(
model="gemini-3.5-flash",
contents="List a few popular cookie recipes.",
config=types.GenerateContentConfig(
response_mime_type="application/json", response_schema=list[Recipe]
),
)
print(result)
controlled_generation.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: "List a few popular cookie recipes.",
config: {
responseMimeType: "application/json",
responseSchema: {
type: "array",
items: {
type: "object",
properties: {
recipeName: { type: "string" },
ingredients: { type: "array", items: { type: "string" } },
},
required: ["recipeName", "ingredients"],
},
},
},
});
console.log(response.text);
controlled_generation.js
Go
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)
}
schema := &genai.Schema{
Type: genai.TypeArray,
Items: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"recipe_name": {Type: genai.TypeString},
"ingredients": {
Type:  genai.TypeArray,
Items: &genai.Schema{Type: genai.TypeString},
},
},
Required: []string{"recipe_name"},
},
}
config := &genai.GenerateContentConfig{
ResponseMIMEType: "application/json",
ResponseSchema:   schema,
}
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.5-flash",
genai.Text("List a few popular cookie recipes."),
config,
)
if err != nil {
log.Fatal(err)
}
printResponse(response)
controlled_generation.go
محارة
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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
controlled_generation.sh
جافا
Client client = new Client();
Schema recipeSchema = Schema.builder()
.type(Array.class.getSimpleName())
.items(Schema.builder()
.type(Object.class.getSimpleName())
.properties(
Map.of("recipe_name", Schema.builder()
.type(String.class.getSimpleName())
.build(),
"ingredients", Schema.builder()
.type(Array.class.getSimpleName())
.items(Schema.builder()
.type(String.class.getSimpleName())
.build())
.build())
)
.required(List.of("recipe_name", "ingredients"))
.build())
.build();
GenerateContentConfig config =
GenerateContentConfig.builder()
.responseMimeType("application/json")
.responseSchema(recipeSchema)
.build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
"List a few popular cookie recipes.",
config);
System.out.println(response.text());
ControlledGeneration.java
تنفيذ الرمز البرمجي
Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=(
"Write and execute code that calculates the sum of the first 50 prime numbers. "
"Ensure that only the executable code and its resulting output are generated."
),
)
# Each part may contain text, executable code, or an execution result.
for part in response.candidates[0].content.parts:
print(part, "\n")
print("-" * 80)
# The .text accessor concatenates the parts into a markdown-formatted text.
print("\n", response.text)
code_execution.py
Go
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)
}
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.5-flash",
genai.Text(
`Write and execute code that calculates the sum of the first 50 prime numbers.
Ensure that only the executable code and its resulting output are generated.`,
),
&genai.GenerateContentConfig{},
)
if err != nil {
log.Fatal(err)
}
// Print the response.
printResponse(response)
fmt.Println("--------------------------------------------------------------------------------")
fmt.Println(response.Text())
code_execution.go
جافا
Client client = new Client();
String prompt = """
Write and execute code that calculates the sum of the first 50 prime numbers.
Ensure that only the executable code and its resulting output are generated.
""";
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
prompt,
null);
for (Part part : response.candidates().get().getFirst().content().get().parts().get()) {
System.out.println(part + "\n");
}
System.out.println("-".repeat(80));
System.out.println(response.text());
CodeExecution.java
استدعاء الدوال
Python
from google import genai
from google.genai import types
client = genai.Client()
def add(a: float, b: float) -> float:
"""returns a + b."""
return a + b
def subtract(a: float, b: float) -> float:
"""returns a - b."""
return a - b
def multiply(a: float, b: float) -> float:
"""returns a * b."""
return a * b
def divide(a: float, b: float) -> float:
"""returns a / b."""
return a / b
# Create a chat session; function calling (via tools) is enabled in the config.
chat = client.chats.create(
model="gemini-3.5-flash",
config=types.GenerateContentConfig(tools=[add, subtract, multiply, divide]),
)
response = chat.send_message(
message="I have 57 cats, each owns 44 mittens, how many mittens is that in total?"
)
print(response.text)
function_calling.py
Go
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)
}
modelName := "gemini-3.5-flash"
// Create the function declarations for arithmetic operations.
addDeclaration := createArithmeticToolDeclaration("addNumbers", "Return the result of adding two numbers.")
subtractDeclaration := createArithmeticToolDeclaration("subtractNumbers", "Return the result of subtracting the second number from the first.")
multiplyDeclaration := createArithmeticToolDeclaration("multiplyNumbers", "Return the product of two numbers.")
divideDeclaration := createArithmeticToolDeclaration("divideNumbers", "Return the quotient of dividing the first number by the second.")
// Group the function declarations as a tool.
tools := []*genai.Tool{
{
FunctionDeclarations: []*genai.FunctionDeclaration{
addDeclaration,
subtractDeclaration,
multiplyDeclaration,
divideDeclaration,
},
},
}
// Create the content prompt.
contents := []*genai.Content{
genai.NewContentFromText(
"I have 57 cats, each owns 44 mittens, how many mittens is that in total?", genai.RoleUser,
),
}
// Set up the generate content configuration with function calling enabled.
config := &genai.GenerateContentConfig{
Tools: tools,
ToolConfig: &genai.ToolConfig{
FunctionCallingConfig: &genai.FunctionCallingConfig{
// The mode equivalent to FunctionCallingConfigMode.ANY in JS.
Mode: genai.FunctionCallingConfigModeAny,
},
},
}
genContentResp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
if err != nil {
log.Fatal(err)
}
// Assume the response includes a list of function calls.
if len(genContentResp.FunctionCalls()) == 0 {
log.Println("No function call returned from the AI.")
return nil
}
functionCall := genContentResp.FunctionCalls()[0]
log.Printf("Function call: %+v\n", functionCall)
// Marshal the Args map into JSON bytes.
argsMap, err := json.Marshal(functionCall.Args)
if err != nil {
log.Fatal(err)
}
// Unmarshal the JSON bytes into the ArithmeticArgs struct.
var args ArithmeticArgs
if err := json.Unmarshal(argsMap, &args); err != nil {
log.Fatal(err)
}
// Map the function name to the actual arithmetic function.
var result float64
switch functionCall.Name {
case "addNumbers":
result = add(args.FirstParam, args.SecondParam)
case "subtractNumbers":
result = subtract(args.FirstParam, args.SecondParam)
case "multiplyNumbers":
result = multiply(args.FirstParam, args.SecondParam)
case "divideNumbers":
result = divide(args.FirstParam, args.SecondParam)
default:
return fmt.Errorf("unimplemented function: %s", functionCall.Name)
}
log.Printf("Function result: %v\n", result)
// Prepare the final result message as content.
resultContents := []*genai.Content{
genai.NewContentFromText("The final result is " + fmt.Sprintf("%v", result), genai.RoleUser),
}
// Use GenerateContent to send the final result.
finalResponse, err := client.Models.GenerateContent(ctx, modelName, resultContents, &genai.GenerateContentConfig{})
if err != nil {
log.Fatal(err)
}
printResponse(finalResponse)
function_calling.go
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
/**
* The add function returns the sum of two numbers.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function add(a, b) {
return a + b;
}
/**
* The subtract function returns the difference (a - b).
* @param {number} a
* @param {number} b
* @returns {number}
*/
function subtract(a, b) {
return a - b;
}
/**
* The multiply function returns the product of two numbers.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function multiply(a, b) {
return a * b;
}
/**
* The divide function returns the quotient of a divided by b.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function divide(a, b) {
return a / b;
}
const addDeclaration = {
name: "addNumbers",
parameters: {
type: "object",
description: "Return the result of adding two numbers.",
properties: {
firstParam: {
type: "number",
description:
"The first parameter which can be an integer or a floating point number.",
},
secondParam: {
type: "number",
description:
"The second parameter which can be an integer or a floating point number.",
},
},
required: ["firstParam", "secondParam"],
},
};
const subtractDeclaration = {
name: "subtractNumbers",
parameters: {
type: "object",
description:
"Return the result of subtracting the second number from the first.",
properties: {
firstParam: {
type: "number",
description: "The first parameter.",
},
secondParam: {
type: "number",
description: "The second parameter.",
},
},
required: ["firstParam", "secondParam"],
},
};
const multiplyDeclaration = {
name: "multiplyNumbers",
parameters: {
type: "object",
description: "Return the product of two numbers.",
properties: {
firstParam: {
type: "number",
description: "The first parameter.",
},
secondParam: {
type: "number",
description: "The second parameter.",
},
},
required: ["firstParam", "secondParam"],
},
};
const divideDeclaration = {
name: "divideNumbers",
parameters: {
type: "object",
description:
"Return the quotient of dividing the first number by the second.",
properties: {
firstParam: {
type: "number",
description: "The first parameter.",
},
secondParam: {
type: "number",
description: "The second parameter.",
},
},
required: ["firstParam", "secondParam"],
},
};
// Step 1: Call generateContent with function calling enabled.
const generateContentResponse = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents:
"I have 57 cats, each owns 44 mittens, how many mittens is that in total?",
config: {
toolConfig: {
functionCallingConfig: {
mode: FunctionCallingConfigMode.ANY,
},
},
tools: [
{
functionDeclarations: [
addDeclaration,
subtractDeclaration,
multiplyDeclaration,
divideDeclaration,
],
},
],
},
});
// Step 2: Extract the function call.(
// Assuming the response contains a 'functionCalls' array.
const functionCall =
generateContentResponse.functionCalls &&
generateContentResponse.functionCalls[0];
console.log(functionCall);
// Parse the arguments.
const args = functionCall.args;
// Expected args format: { firstParam: number, secondParam: number }
// Step 3: Invoke the actual function based on the function name.
const functionMapping = {
addNumbers: add,
subtractNumbers: subtract,
multiplyNumbers: multiply,
divideNumbers: divide,
};
const func = functionMapping[functionCall.name];
if (!func) {
console.error("Unimplemented error:", functionCall.name);
return generateContentResponse;
}
const resultValue = func(args.firstParam, args.secondParam);
console.log("Function result:", resultValue);
// Step 4: Use the chat API to send the result as the final answer.
const chat = ai.chats.create({ model: "gemini-3.5-flash" });
const chatResponse = await chat.sendMessage({
message: "The final result is " + resultValue,
});
console.log(chatResponse.text);
return chatResponse;
}
function_calling.js
محارة
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://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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'
function_calling.sh
جافا
Client client = new Client();
FunctionDeclaration addFunction =
FunctionDeclaration.builder()
.name("addNumbers")
.parameters(
Schema.builder()
.type("object")
.properties(Map.of(
"firstParam", Schema.builder().type("number").description("First number").build(),
"secondParam", Schema.builder().type("number").description("Second number").build()))
.required(Arrays.asList("firstParam", "secondParam"))
.build())
.build();
FunctionDeclaration subtractFunction =
FunctionDeclaration.builder()
.name("subtractNumbers")
.parameters(
Schema.builder()
.type("object")
.properties(Map.of(
"firstParam", Schema.builder().type("number").description("First number").build(),
"secondParam", Schema.builder().type("number").description("Second number").build()))
.required(Arrays.asList("firstParam", "secondParam"))
.build())
.build();
FunctionDeclaration multiplyFunction =
FunctionDeclaration.builder()
.name("multiplyNumbers")
.parameters(
Schema.builder()
.type("object")
.properties(Map.of(
"firstParam", Schema.builder().type("number").description("First number").build(),
"secondParam", Schema.builder().type("number").description("Second number").build()))
.required(Arrays.asList("firstParam", "secondParam"))
.build())
.build();
FunctionDeclaration divideFunction =
FunctionDeclaration.builder()
.name("divideNumbers")
.parameters(
Schema.builder()
.type("object")
.properties(Map.of(
"firstParam", Schema.builder().type("number").description("First number").build(),
"secondParam", Schema.builder().type("number").description("Second number").build()))
.required(Arrays.asList("firstParam", "secondParam"))
.build())
.build();
GenerateContentConfig config = GenerateContentConfig.builder()
.toolConfig(ToolConfig.builder().functionCallingConfig(
FunctionCallingConfig.builder().mode("ANY").build()
).build())
.tools(
Collections.singletonList(
Tool.builder().functionDeclarations(
Arrays.asList(
addFunction,
subtractFunction,
divideFunction,
multiplyFunction
)
).build()
)
)
.build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
"I have 57 cats, each owns 44 mittens, how many mittens is that in total?",
config);
if (response.functionCalls() == null || response.functionCalls().isEmpty()) {
System.err.println("No function call received");
return null;
}
var functionCall = response.functionCalls().getFirst();
String functionName = functionCall.name().get();
var arguments = functionCall.args();
Map<String, BiFunction<Double, Double, Double>> functionMapping = new HashMap<>();
functionMapping.put("addNumbers", (a, b) -> a + b);
functionMapping.put("subtractNumbers", (a, b) -> a - b);
functionMapping.put("multiplyNumbers", (a, b) -> a * b);
functionMapping.put("divideNumbers", (a, b) -> b != 0 ? a / b : Double.NaN);
BiFunction<Double, Double, Double> function = functionMapping.get(functionName);
Number firstParam = (Number) arguments.get().get("firstParam");
Number secondParam = (Number) arguments.get().get("secondParam");
Double result = function.apply(firstParam.doubleValue(), secondParam.doubleValue());
System.out.println(result);
FunctionCalling.java
إعدادات الإنشاء
Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Tell me a story about a magic backpack.",
config=types.GenerateContentConfig(
candidate_count=1,
stop_sequences=["x"],
max_output_tokens=20,
temperature=1.0,
),
)
print(response.text)
configure_model_parameters.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: "Tell me a story about a magic backpack.",
config: {
candidateCount: 1,
stopSequences: ["x"],
maxOutputTokens: 20,
temperature: 1.0,
},
});
console.log(response.text);
configure_model_parameters.js
Go
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)
}
// Create local variables for parameters.
candidateCount := int32(1)
maxOutputTokens := int32(20)
temperature := float32(1.0)
response, err := client.Models.GenerateContent(
ctx,
"gemini-3.5-flash",
genai.Text("Tell me a story about a magic backpack."),
&genai.GenerateContentConfig{
CandidateCount:  candidateCount,
StopSequences:   []string{"x"},
MaxOutputTokens: maxOutputTokens,
Temperature:     &temperature,
},
)
if err != nil {
log.Fatal(err)
}
printResponse(response)
configure_model_parameters.go
محارة
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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"
configure_model_parameters.sh
جافا
Client client = new Client();
GenerateContentConfig config =
GenerateContentConfig.builder()
.candidateCount(1)
.stopSequences(List.of("x"))
.maxOutputTokens(20)
.temperature(1.0F)
.build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
"Tell me a story about a magic backpack.",
config);
System.out.println(response.text());
ConfigureModelParameters.java
إعدادات الأمان
Python
from google import genai
from google.genai import types
client = genai.Client()
unsafe_prompt = (
"I support Martians Soccer Club and I think Jupiterians Football Club sucks! "
"Write a ironic phrase about them including expletives."
)
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=unsafe_prompt,
config=types.GenerateContentConfig(
safety_settings=[
types.SafetySetting(
category="HARM_CATEGORY_HATE_SPEECH",
threshold="BLOCK_MEDIUM_AND_ABOVE",
),
types.SafetySetting(
category="HARM_CATEGORY_HARASSMENT", threshold="BLOCK_ONLY_HIGH"
),
]
),
)
try:
print(response.text)
except Exception:
print("No information generated by the model.")
print(response.candidates[0].safety_ratings)
safety_settings.py
Node.js
// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const unsafePrompt =
"I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them including expletives.";
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: unsafePrompt,
config: {
safetySettings: [
{
category: "HARM_CATEGORY_HATE_SPEECH",
threshold: "BLOCK_MEDIUM_AND_ABOVE",
},
{
category: "HARM_CATEGORY_HARASSMENT",
threshold: "BLOCK_ONLY_HIGH",
},
],
},
});
try {
console.log("Generated text:", response.text);
} catch (error) {
console.log("No information generated by the model.");
}
console.log("Safety ratings:", response.candidates[0].safetyRatings);
return response;
}
safety_settings.js
Go
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)
}
unsafePrompt := "I support Martians Soccer Club and I think Jupiterians Football Club sucks! " +
"Write a ironic phrase about them including expletives."
config := &genai.GenerateContentConfig{
SafetySettings: []*genai.SafetySetting{
{
Category:  "HARM_CATEGORY_HATE_SPEECH",
Threshold: "BLOCK_MEDIUM_AND_ABOVE",
},
{
Category:  "HARM_CATEGORY_HARASSMENT",
Threshold: "BLOCK_ONLY_HIGH",
},
},
}
contents := []*genai.Content{
genai.NewContentFromText(unsafePrompt, genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, config)
if err != nil {
log.Fatal(err)
}
// Print the generated text.
text := response.Text()
fmt.Println("Generated text:", text)
// Print the and safety ratings from the first candidate.
if len(response.Candidates) > 0 {
fmt.Println("Finish reason:", response.Candidates[0].FinishReason)
safetyRatings, err := json.MarshalIndent(response.Candidates[0].SafetyRatings, "", "  ")
if err != nil {
return err
}
fmt.Println("Safety ratings:", string(safetyRatings))
} else {
fmt.Println("No candidate returned.")
}
safety_settings.go
محارة
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://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d @request.json 2> /dev/null
safety_settings.sh
جافا
Client client = new Client();
String unsafePrompt = """
I support Martians Soccer Club and I think Jupiterians Football Club sucks!
Write a ironic phrase about them including expletives.
""";
GenerateContentConfig config =
GenerateContentConfig.builder()
.safetySettings(Arrays.asList(
SafetySetting.builder()
.category("HARM_CATEGORY_HATE_SPEECH")
.threshold("BLOCK_MEDIUM_AND_ABOVE")
.build(),
SafetySetting.builder()
.category("HARM_CATEGORY_HARASSMENT")
.threshold("BLOCK_ONLY_HIGH")
.build()
)).build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
unsafePrompt,
config);
try {
System.out.println(response.text());
} catch (Exception e) {
System.out.println("No information generated by the model");
}
System.out.println(response.candidates().get().getFirst().safetyRatings());
SafetySettings.java
تعليمات النظام
Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Good morning! How are you?",
config=types.GenerateContentConfig(
system_instruction="You are a cat. Your name is Neko."
),
)
print(response.text)
system_instruction.py
Node.js
// 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.generateContent({
model: "gemini-3.5-flash",
contents: "Good morning! How are you?",
config: {
systemInstruction: "You are a cat. Your name is Neko.",
},
});
console.log(response.text);
system_instruction.js
Go
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)
}
// Construct the user message contents.
contents := []*genai.Content{
genai.NewContentFromText("Good morning! How are you?", genai.RoleUser),
}
// Set the system instruction as a *genai.Content.
config := &genai.GenerateContentConfig{
SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", contents, config)
if err != nil {
log.Fatal(err)
}
printResponse(response)
system_instruction.go
محارة
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_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
جافا
Client client = new Client();
Part textPart = Part.builder().text("You are a cat. Your name is Neko.").build();
Content content = Content.builder().role("system").parts(ImmutableList.of(textPart)).build();
GenerateContentConfig config = GenerateContentConfig.builder()
.systemInstruction(content)
.build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.5-flash",
"Good morning! How are you?",
config);
System.out.println(response.text());
SystemInstruction.java
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال GenerateContentResponse.
الطريقة: models.streamGenerateContent
نقطة النهاية
مَعلمات المسار
نص الطلب
تمثيل JSON
نص الاستجابة
نطاقات الأذونات
مثال على الطلب
Text
صورة
الصوت
الفيديو
PDF
Chat
ينشئ ردًا متسلسلاً من النموذج بناءً على الإدخال GenerateContentRequest.
نقطة نهاية
post
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
مَعلمات المسار
model
string
الحقل مطلوب. اسم Model المطلوب استخدامه لإنشاء الإكمال
التنسيق: models/{model} ويكون بالتنسيق التالي: models/{model}.
نص الطلب
يتضمن نص الطلب بيانات بالبنية التالية:
الحقول
contents[]
object (Content)
الحقل مطلوب. محتوى المحادثة الحالية مع النموذج
بالنسبة إلى طلبات البحث ذات الدورة الواحدة، يكون هذا مثيلاً واحدًا. بالنسبة إلى الاستعلامات المتعددة الأدوار، مثل المحادثة، هذا حقل متكرّر يحتوي على سجلّ المحادثات وآخر طلب.
tools[]
object (Tool)
اختياريّ. قائمة Tools التي يمكن Model استخدامها لإنشاء الرد التالي
Tool هي جزء من الرمز البرمجي يتيح للنظام التفاعل مع الأنظمة الخارجية لتنفيذ إجراء أو مجموعة من الإجراءات خارج نطاق معرفة Model. Tool المتاحة هي Function وcodeExecution. لمزيد من المعلومات، يُرجى الرجوع إلى دليلَي استدعاء الدوال وتنفيذ الرمز.
toolConfig
object (ToolConfig)
اختياريّ. إعدادات الأداة لأي Tool محدّدة في الطلب راجِع دليل استدعاء الدوال للاطّلاع على مثال على الاستخدام.
safetySettings[]
object (SafetySetting)
اختياريّ. قائمة بحالات SafetySetting الفريدة لحظر المحتوى غير الآمن
سيتم تطبيق هذا الشرط على GenerateContentRequest.contents وGenerateContentResponse.candidates. يجب ألا يكون هناك أكثر من إعداد واحد لكل نوع SafetyCategory. ستحظر واجهة برمجة التطبيقات أي محتوى وردود لا تستوفي الحدود التي تحدّدها هذه الإعدادات. تلغي هذه القائمة الإعدادات التلقائية لكل SafetyCategory محدّد في safetySettings. إذا لم يكن هناك SafetySetting لفئة SafetyCategory معيّنة مقدَّمة في القائمة، ستستخدِم واجهة برمجة التطبيقات إعدادات الأمان التلقائية لهذه الفئة. تتوفّر فئات الضرر HARM_CATEGORY_HATE_SPEECH وHARM_CATEGORY_SEXUALLY_EXPLICIT وHARM_CATEGORY_DANGEROUS_CONTENT وHARM_CATEGORY_HARASSMENT وHARM_CATEGORY_CIVIC_INTEGRITY. راجِع الدليل للحصول على معلومات تفصيلية حول إعدادات الأمان المتاحة. يمكنك أيضًا الرجوع إلى إرشادات الأمان للتعرّف على كيفية تضمين اعتبارات الأمان في تطبيقات الذكاء الاصطناعي.
systemInstruction
object (Content)
اختياريّ. يضع المطوّر تعليمات النظام. في الوقت الحالي، يمكن إدخال نص فقط.
generationConfig
object (GenerationConfig)
اختياريّ. خيارات الإعداد لإنشاء النماذج والمخرجات
cachedContent
string
اختياريّ. اسم المحتوى المخزَّن مؤقتًا لاستخدامه كسياق لعرض التوقّع التنسيق: cachedContents/{cachedContent}
serviceTier
enum (ServiceTier)
اختياريّ. فئة الخدمة للطلب
store
boolean
اختياريّ. تضبط هذه السمة سلوك التسجيل لطلب معيّن. في حال ضبطها، تكون لها الأولوية على إعدادات التسجيل على مستوى المشروع.
مثال على الطلب
نص
Python
from google import genai
client = genai.Client()
response = client.models.generate_content_stream(
model="gemini-3.5-flash", contents="Write a story about a magic backpack."
)
for chunk in response:
print(chunk.text)
print("_" * 80)
text_generation.py
Node.js
// 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.5-flash",
contents: "Write a story about a magic backpack.",
});
let text = "";
for await (const chunk of response) {
console.log(chunk.text);
text += chunk.text;
}
text_generation.js
Go
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.5-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
text_generation.go
محارة
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-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."}]}]}'
text_generation.sh
جافا
Client client = new Client();
ResponseStream<GenerateContentResponse> responseStream =
client.models.generateContentStream(
"gemini-3.5-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();
TextGeneration.java
صورة
Python
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.5-flash", contents=["Tell me about this instrument", organ]
)
for chunk in response:
print(chunk.text)
print("_" * 80)
text_generation.py
Node.js
// 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.5-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;
}
text_generation.js
Go
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.5-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}
text_generation.go
محارة
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-2.0-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
text_generation.sh
جافا
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.5-flash",
content,
null);
StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
System.out.print(res.text());
response.append(res.text());
}
responseStream.close();
TextGeneration.java
الصوت
Python
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.5-flash",
contents=["Give me a summary of this audio file.", sample_audio],
)
for chunk in response:
print(chunk.text)
print("_" * 80)
text_generation.py
Go
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.5-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
text_generation.go
محارة
# 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-2.0-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
text_generation.sh
فيديو
Python
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.5-flash", contents=[myfile, "Describe this video clip"]
)
for chunk in response:
print(chunk.text)
print("_" * 80)
text_generation.py
Node.js
// 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.5-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;
}
text_generation.js
Go
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.5-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
text_generation.go
محارة
# 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-2.0-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
text_generation.sh
PDF
Python
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.5-flash",
contents=["Give me a summary of this document:", sample_pdf],
)
for chunk in response:
print(chunk.text)
print("_" * 80)
text_generation.py
Go
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.5-flash",
contents,
nil,
) {
if err != nil {
log.Fatal(err)
}
fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}
text_generation.go
محارة
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-2.0-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
text_generation.sh
محادثة
Python
from google import genai
from google.genai import types
client = genai.Client()
chat = client.chats.create(
model="gemini-3.5-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())
chat.py
Node.js
// 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.5-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());
chat.js
Go
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.5-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))
chat.go
محارة
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-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"
chat.sh
نص الاستجابة
إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مجموعة من أمثلة GenerateContentResponse.
GenerateContentResponse
تمثيل JSON
PromptFeedback
تمثيل JSON
BlockReason
UsageMetadata
تمثيل JSON
ModelStatus
تمثيل JSON
ModelStage
ردّ من النموذج يتضمّن عدة إجابات محتملة
يتم عرض تقييمات الأمان وفلترة المحتوى لكل من الطلب في GenerateContentResponse.prompt_feedback ولكل مرشّح في finishReason وsafetyRatings. تعمل واجهة برمجة التطبيقات على:  - عرض جميع المرشحين المطلوبين أو عدم عرض أي منهم  - عدم عرض أي مرشحين على الإطلاق فقط في حال وجود مشكلة في الطلب (راجِع promptFeedback)  - تسجيل الملاحظات حول كل مرشح في finishReason وsafetyRatings
الحقول
candidates[]
object (Candidate)
ردود المرشحين من النموذج
promptFeedback
object (PromptFeedback)
تعرض هذه السمة الملاحظات حول فلاتر المحتوى التي تم تلقّيها بشأن الطلب.
usageMetadata
object (UsageMetadata)
النتائج فقط. بيانات وصفية حول استخدام الرموز المميزة لطلبات الإنشاء
modelVersion
string
النتائج فقط. إصدار النموذج المستخدَم لإنشاء الردّ.
responseId
string
لإخراج البيانات فقط، ويُستخدم responseId لتحديد كل رد.
modelStatus
object (ModelStatus)
النتائج فقط. تعرض هذه السمة حالة النموذج الحالية.
تمثيل JSON
{
"candidates": [
{
object (Candidate)
}
],
"promptFeedback": {
object (PromptFeedback)
},
"usageMetadata": {
object (UsageMetadata)
},
"modelVersion": string,
"responseId": string,
"modelStatus": {
object (ModelStatus)
}
}
PromptFeedback
مجموعة من البيانات الوصفية للملاحظات التي حدّدها الطلب في GenerateContentRequest.content
الحقول
blockReason
enum (BlockReason)
اختياريّ. في حال ضبطها، تم حظر الطلب ولم يتم عرض أي نتائج محتملة. أعِد صياغة الطلب.
safetyRatings[]
object (SafetyRating)
تقييمات مدى أمان الطلب يمكن تقديم تقييم واحد كحدّ أقصى لكل فئة.
تمثيل JSON
{
"blockReason": enum (BlockReason),
"safetyRatings": [
{
object (SafetyRating)
}
]
}
BlockReason
تحدّد هذه السمة سبب حظر الطلب.
عمليات التعداد
BLOCK_REASON_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
SAFETY
تم حظر الطلب لأسباب تتعلق بالأمان. افحص safetyRatings لمعرفة فئة الأمان التي حظرته.
OTHER
تم حظر الطلب لأسباب غير معروفة.
BLOCKLIST
تم حظر الطلب بسبب العبارات المُدرَجة في قائمة الحظر الخاصة بالمصطلحات.
PROHIBITED_CONTENT
تم حظر الطلب بسبب المحتوى المحظور.
IMAGE_SAFETY
تم حظر المرشحين بسبب المحتوى غير الآمن الذي تم إنشاؤه من الصور.
UsageMetadata
بيانات وصفية حول استخدام الرموز المميزة لطلب الإنشاء
الحقول
promptTokenCount
integer
عدد الرموز المميزة في الطلب عند ضبط cachedContent، يظلّ هذا هو إجمالي حجم الطلب الفعّال، ما يعني أنّه يشمل عدد الرموز المميزة في المحتوى المخزّن مؤقتًا.
cachedContentTokenCount
integer
عدد الرموز المميّزة في الجزء المخزّن مؤقتًا من الطلب (المحتوى المخزّن مؤقتًا)
candidatesTokenCount
integer
إجمالي عدد الرموز المميزة في جميع الردود المقترَحة التي تم إنشاؤها
toolUsePromptTokenCount
integer
النتائج فقط. عدد الرموز المميزة المتوفّرة في طلبات استخدام الأدوات
thoughtsTokenCount
integer
النتائج فقط. عدد الرموز المميّزة للأفكار في نماذج التفكير
totalTokenCount
integer
إجمالي عدد الرموز المميّزة لطلب الإنشاء (الطلب + الأفكار + الردود المحتملة)
promptTokensDetails[]
object (ModalityTokenCount)
النتائج فقط. قائمة بالوسائط التي تمت معالجتها في بيانات الإدخال الخاصة بالطلب
cacheTokensDetails[]
object (ModalityTokenCount)
النتائج فقط. قائمة بأنواع المحتوى المخزّن مؤقتًا في بيانات طلب البحث.
candidatesTokensDetails[]
object (ModalityTokenCount)
النتائج فقط. قائمة بالوسائط التي تم عرضها في الردّ.
toolUsePromptTokensDetails[]
object (ModalityTokenCount)
النتائج فقط. قائمة بالوسائط التي تمت معالجتها لإدخالات طلب استخدام الأدوات
serviceTier
enum (ServiceTier)
النتائج فقط. فئة الخدمة للطلب
تمثيل JSON
{
"promptTokenCount": integer,
"cachedContentTokenCount": integer,
"candidatesTokenCount": integer,
"toolUsePromptTokenCount": integer,
"thoughtsTokenCount": integer,
"totalTokenCount": integer,
"promptTokensDetails": [
{
object (ModalityTokenCount)
}
],
"cacheTokensDetails": [
{
object (ModalityTokenCount)
}
],
"candidatesTokensDetails": [
{
object (ModalityTokenCount)
}
],
"toolUsePromptTokensDetails": [
{
object (ModalityTokenCount)
}
],
"serviceTier": enum (ServiceTier)
}
ModelStatus
حالة النموذج الأساسي يُستخدَم هذا الحقل للإشارة إلى مرحلة النموذج الأساسي ووقت إيقافه نهائيًا إذا كان ذلك منطبقًا.
الحقول
modelStage
enum (ModelStage)
مرحلة النموذج الأساسي
retirementTime
string (Timestamp format)
الوقت الذي سيتم فيه إيقاف النموذج نهائيًا.
يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
message
string
رسالة تشرح حالة النموذج
تمثيل JSON
{
"modelStage": enum (ModelStage),
"retirementTime": string,
"message": string
}
ModelStage
تحدّد هذه السمة مرحلة النموذج الأساسي.
عمليات التعداد
MODEL_STAGE_UNSPECIFIED
مرحلة النموذج غير محدّدة.
UNSTABLE_EXPERIMENTAL
يخضع النموذج الأساسي للكثير من عمليات الضبط.
تم إيقاف هذا العنصر نهائيًا.
EXPERIMENTAL
النماذج في هذه المرحلة مخصّصة لأغراض تجريبية فقط.
PREVIEW
تكون النماذج في هذه المرحلة أكثر تطورًا من النماذج التجريبية.
STABLE
تُعدّ النماذج في هذه المرحلة ثابتة وجاهزة للاستخدام في بيئة إنتاجية.
LEGACY
إذا كان النموذج في هذه المرحلة، يعني ذلك أنّه سيتم إيقافه نهائيًا في المستقبل القريب. يمكن للعملاء الحاليين فقط استخدام هذا النموذج.
DEPRECATED
تم إيقاف النماذج في هذه المرحلة نهائيًا. لا يمكن استخدام هذه النماذج.
تم إيقاف هذا العنصر نهائيًا.
RETIRED
يتم إيقاف النماذج في هذه المرحلة نهائيًا. لا يمكن استخدام هذه النماذج.
مرشح
تمثيل JSON
FinishReason
GroundingAttribution
تمثيل JSON
AttributionSourceId
تمثيل JSON
GroundingPassageId
تمثيل JSON
SemanticRetrieverChunk
تمثيل JSON
GroundingMetadata
تمثيل JSON
SearchEntryPoint
تمثيل JSON
GroundingChunk
تمثيل JSON
الويب
تمثيل JSON
الصورة
تمثيل JSON
RetrievedContext
تمثيل JSON
CustomMetadata
تمثيل JSON
StringList
تمثيل JSON
خرائط Google
تمثيل JSON
PlaceAnswerSources
تمثيل JSON
ReviewSnippet
تمثيل JSON
GroundingSupport
تمثيل JSON
الشريحة
تمثيل JSON
RetrievalMetadata
تمثيل JSON
LogprobsResult
تمثيل JSON
TopCandidates
تمثيل JSON
المرشّح
تمثيل JSON
UrlContextMetadata
تمثيل JSON
UrlMetadata
تمثيل JSON
UrlRetrievalStatus
مرشّح ردّ تم إنشاؤه من النموذج
الحقول
content
object (Content)
النتائج فقط. المحتوى الذي تم إنشاؤه والذي تم إرجاعه من النموذج
finishReason
enum (FinishReason)
اختياريّ. النتائج فقط. سبب توقّف النموذج عن إنشاء الرموز المميزة.
إذا كان الحقل فارغًا، يعني ذلك أنّ النموذج لم يتوقف عن إنشاء الرموز المميزة.
safetyRatings[]
object (SafetyRating)
قائمة بالتقييمات المتعلّقة بأمان الردّ المقترَح.
يمكن تقديم تقييم واحد كحدّ أقصى لكل فئة.
citationMetadata
object (CitationMetadata)
النتائج فقط. معلومات الاقتباس الخاصة بالمرشح الذي تم إنشاؤه بواسطة النموذج
قد تتم تعبئة هذا الحقل بمعلومات التلاوة لأي نص مضمّن في content. وهي عبارة عن مقاطع "مقتبسة" من مواد محمية بحقوق الطبع والنشر في بيانات التدريب الخاصة بالنموذج اللغوي الأساسي الكبير.
tokenCount
integer
النتائج فقط. عدد الرموز المميّزة لهذا المرشّح.
groundingAttributions[]
object (GroundingAttribution)
النتائج فقط. تمثّل هذه السمة معلومات تحديد المصدر للمصادر التي ساهمت في تقديم إجابة مستندة إلى مصادر.
يتم ملء هذا الحقل لطلبات GenerateAnswer.
groundingMetadata
object (GroundingMetadata)
النتائج فقط. البيانات الوصفية الأساسية للمرشّح
يتم ملء هذا الحقل لطلبات GenerateContent.
avgLogprobs
number
النتائج فقط. متوسط نتيجة الاحتمالية اللوغاريتمية للمرشّح
logprobsResult
object (LogprobsResult)
النتائج فقط. نتائج احتمالية تسجيل الدخول لرموز الردود والرموز الأعلى
urlContextMetadata
object (UrlContextMetadata)
النتائج فقط. البيانات الوصفية ذات الصلة بأداة استرجاع سياق عنوان URL
index
integer
النتائج فقط. فهرس المرشّح في قائمة المرشّحين للردّ
finishMessage
string
اختياريّ. النتائج فقط. تعرض هذه السمة سبب توقّف النموذج عن إنشاء الرموز المميّزة. لا تتم تعبئة هذا الحقل إلا عند ضبط finishReason.
تمثيل JSON
{
"content": {
object (Content)
},
"finishReason": enum (FinishReason),
"safetyRatings": [
{
object (SafetyRating)
}
],
"citationMetadata": {
object (CitationMetadata)
},
"tokenCount": integer,
"groundingAttributions": [
{
object (GroundingAttribution)
}
],
"groundingMetadata": {
object (GroundingMetadata)
},
"avgLogprobs": number,
"logprobsResult": {
object (LogprobsResult)
},
"urlContextMetadata": {
object (UrlContextMetadata)
},
"index": integer,
"finishMessage": string
}
FinishReason
تحدّد هذه السمة سبب توقّف النموذج عن إنشاء الرموز المميزة.
عمليات التعداد
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
تم إنهاء المحادثة بسبب ردّ مكتوب بشكل غير صحيح.
GroundingAttribution
معلومات تحديد المصدر الذي ساهم في تقديم إجابة
الحقول
sourceId
object (AttributionSourceId)
النتائج فقط. معرّف المصدر الذي يساهم في تحديد المصدر هذا.
content
object (Content)
المحتوى المصدر الأساسي الذي يتضمّنه هذا البيان
تمثيل JSON
{
"sourceId": {
object (AttributionSourceId)
},
"content": {
object (Content)
}
}
AttributionSourceId
معرّف المصدر الذي يساهم في تحديد المصدر هذا.
الحقول
source
Union type
يمكن أن يكون التعليق source إحدى القيم التالية فقط:
groundingPassage
object (GroundingPassageId)
تمثّل هذه السمة معرّفًا لمقطع مضمّن.
semanticRetrieverChunk
object (SemanticRetrieverChunk)
معرّف Chunk تم استرجاعه من خلال Semantic Retriever.
تمثيل JSON
{
// source
"groundingPassage": {
object (GroundingPassageId)
},
"semanticRetrieverChunk": {
object (SemanticRetrieverChunk)
}
// Union type
}
GroundingPassageId
معرّف لجزء ضمن GroundingPassage
الحقول
passageId
string
النتائج فقط. معرّف الفقرة المطابقة لـ GroundingPassage.id في GenerateAnswerRequest
partIndex
integer
النتائج فقط. فهرس الجزء ضمن GroundingPassage.content من GenerateAnswerRequest
تمثيل JSON
{
"passageId": string,
"partIndex": integer
}
SemanticRetrieverChunk
معرّف Chunk تم استرداده من خلال Semantic Retriever المحدّد في GenerateAnswerRequest باستخدام SemanticRetrieverConfig.
الحقول
source
string
النتائج فقط. اسم المصدر الذي يتطابق مع SemanticRetrieverConfig.source في الطلب مثال: corpora/123 أو corpora/123/documents/abc
chunk
string
النتائج فقط. اسم Chunk الذي يحتوي على النص المنسوب. مثال: corpora/123/documents/abc/chunks/xyz
تمثيل JSON
{
"source": string,
"chunk": string
}
GroundingMetadata
البيانات الوصفية التي يتم عرضها للعميل عند تفعيل ميزة "الاستناد إلى مصادر"
الحقول
groundingChunks[]
object (GroundingChunk)
قائمة بالمراجع الداعمة التي تم استرجاعها من مصدر المعلومات الأساسية المحدّد عند البث، لا يحتوي هذا الحقل إلا على أجزاء التأسيس التي لم يتم تضمينها في البيانات الوصفية للتأسيس في الردود السابقة.
groundingSupports[]
object (GroundingSupport)
قائمة بميزات التأسيس المتوافقة
webSearchQueries[]
string
طلبات البحث على الويب التي يتم إجراؤها بعد البحث الأولي على الويب
imageSearchQueries[]
string
طلبات البحث بالصور المستخدَمة في التأسيس
searchEntryPoint
object (SearchEntryPoint)
اختياريّ. نقطة دخول "بحث Google" لعمليات البحث اللاحقة على الويب
retrievalMetadata
object (RetrievalMetadata)
البيانات الوصفية المرتبطة باسترجاع المعلومات في مسار تحديد المصدر
googleMapsWidgetContextToken
string
اختياريّ. اسم المورد لرمز السياق الخاص بأداة Google Maps الذي يمكن استخدامه مع أداة PlacesContextElement لعرض البيانات السياقية. لا تتم تعبئة هذا الحقل إلا في حال تفعيل ميزة "استخدام خرائط Google كمصدر".
تمثيل JSON
{
"groundingChunks": [
{
object (GroundingChunk)
}
],
"groundingSupports": [
{
object (GroundingSupport)
}
],
"webSearchQueries": [
string
],
"imageSearchQueries": [
string
],
"searchEntryPoint": {
object (SearchEntryPoint)
},
"retrievalMetadata": {
object (RetrievalMetadata)
},
"googleMapsWidgetContextToken": string
}
SearchEntryPoint
نقطة دخول إلى "بحث Google"
الحقول
renderedContent
string
اختياريّ. مقتطف من محتوى الويب يمكن تضمينه في صفحة ويب أو WebView في تطبيق
sdkBlob
string (bytes format)
اختياريّ. تمثّل هذه السمة JSON مرمّزًا بتنسيق Base64، وهو يمثّل مجموعة من أزواج <عبارة البحث، عنوان URL الخاص بالبحث.
سلسلة مرمّزة باستخدام Base64
تمثيل JSON
{
"renderedContent": string,
"sdkBlob": string
}
GroundingChunk
يمثّل GroundingChunk جزءًا من الأدلة الداعمة التي تستند إليها استجابة النموذج. يمكن أن تكون هذه المعلومات مقتطفًا من الويب أو سياقًا تم استرجاعه من ملف أو معلومات من "خرائط Google".
الحقول
chunk_type
Union type
نوع الجزء يمكن أن يكون التعليق chunk_type إحدى القيم التالية فقط:
web
object (Web)
مقتطف تحديد المصدر من الويب
image
object (Image)
اختياريّ. مقتطف تحديد المصدر من "بحث الصور"
retrievedContext
object (RetrievedContext)
اختياريّ. جزء مستند إلى السياق تم استرداده من خلال أداة البحث عن الملفات
maps
object (Maps)
اختياريّ. مقتطف مستند إلى "خرائط Google"
تمثيل JSON
{
// chunk_type
"web": {
object (Web)
},
"image": {
object (Image)
},
"retrievedContext": {
object (RetrievedContext)
},
"maps": {
object (Maps)
}
// Union type
}
الويب
مقتطف من الويب
الحقول
uri
string
النتائج فقط. يشير إلى معرّف الموارد المنتظم (URI) الخاص بالجزء.
title
string
النتائج فقط. تمثّل هذه السمة عنوان الجزء.
تمثيل JSON
{
"uri": string,
"title": string
}
صورة
مقتطف من بحث الصور
الحقول
sourceUri
string
معرّف الموارد المنتظم (URI) لصفحة الويب الخاصة بتحديد المصدر
imageUri
string
عنوان URL لمادة عرض الصورة
title
string
تمثّل عنوان صفحة الويب التي تمّت استعارة الصورة منها.
domain
string
النطاق الجذر لصفحة الويب التي تأتي منها الصورة، مثل "example.com".
تمثيل JSON
{
"sourceUri": string,
"imageUri": string,
"title": string,
"domain": string
}
RetrievedContext
مقتطف من السياق الذي تم استرجاعه باستخدام أداة البحث عن الملفات
الحقول
customMetadata[]
object (CustomMetadata)
اختياريّ. بيانات وصفية مقدَّمة من المستخدم حول السياق الذي تم استرجاعه
uri
string
اختياريّ. معرّف الموارد المنتظم (URI) الخاص بمستند الاسترجاع الدلالي
title
string
اختياريّ. تمثّل هذه السمة عنوان المستند.
text
string
اختياريّ. نص الجزء
fileSearchStore
string
اختياريّ. اسم FileSearchStore الذي يحتوي على المستند مثال: fileSearchStores/123
pageNumber
integer
اختياريّ. تمثّل هذه السمة رقم الصفحة التي تم استرداد السياق منها، إذا كان ذلك منطبقًا.
mediaId
string
اختياريّ. اسم مورد blob الوسائط لنتائج البحث عن الملفات المتعدّدة الوسائط التنسيق: fileSearchStores/{file_search_store_id}/media/{blobId}
تمثيل JSON
{
"customMetadata": [
{
object (CustomMetadata)
}
],
"uri": string,
"title": string,
"text": string,
"fileSearchStore": string,
"pageNumber": integer,
"mediaId": string
}
CustomMetadata
قدّم المستخدم بيانات وصفية حول GroundingFact.
الحقول
key
string
مفتاح البيانات الوصفية
value
Union type
قيمة البيانات الوصفية يمكن أن تكون سلسلة أو قائمة سلاسل أو رقمًا. يمكن أن يكون التعليق value إحدى القيم التالية فقط:
stringValue
string
اختياريّ. قيمة السلسلة للبيانات الوصفية
stringListValue
object (StringList)
اختياريّ. قائمة بقيم السلسلة للبيانات الوصفية
numericValue
number
اختياريّ. القيمة الرقمية للبيانات الوصفية يعتمد النطاق المتوقّع لهذه القيمة على key المحدّد المستخدَم.
تمثيل JSON
{
"key": string,
// value
"stringValue": string,
"stringListValue": {
object (StringList)
},
"numericValue": number
// Union type
}
StringList
قائمة بقيم السلسلة
الحقول
values[]
string
قيم السلسلة في القائمة
تمثيل JSON
{
"values": [
string
]
}
خرائط Google
مقتطف من "خرائط Google" يتوافق جزء "خرائط Google" مع مكان واحد.
الحقول
uri
string
تمثّل هذه السمة مرجع معرّف الموارد المنتظم (URI) للمكان.
title
string
تمثّل هذه السمة عنوان المكان.
text
string
تمثّل هذه السمة الوصف النصي لإجابة المكان.
placeId
string
معرّف المكان بالتنسيق places/{placeId} يمكن للمستخدم استخدام هذا المعرّف للبحث عن هذا المكان.
placeAnswerSources
object (PlaceAnswerSources)
المصادر التي تقدّم إجابات عن ميزات مكان معيّن في "خرائط Google"
تمثيل JSON
{
"uri": string,
"title": string,
"text": string,
"placeId": string,
"placeAnswerSources": {
object (PlaceAnswerSources)
}
}
PlaceAnswerSources
مجموعة من المصادر التي تقدّم إجابات حول ميزات مكان معيّن في "خرائط Google" تتطابق كل رسالة PlaceAnswerSources مع مكان محدّد في "خرائط Google". استخدمت أداة "خرائط Google" هذه المصادر للإجابة عن أسئلة حول ميزات المكان (مثلاً: "هل يوفّر مقهى Foo خدمة Wi-Fi؟" أو "هل يمكن الوصول إلى مقهى Foo Bar باستخدام كرسي متحرك؟"). في الوقت الحالي، لا نتيح سوى مقتطفات المراجعات كمصادر.
الحقول
reviewSnippets[]
object (ReviewSnippet)
مقتطفات من المراجعات تُستخدَم لإنشاء إجابات حول ميزات مكان معيّن في "خرائط Google"
تمثيل JSON
{
"reviewSnippets": [
{
object (ReviewSnippet)
}
]
}
ReviewSnippet
تتضمّن مقتطفًا من مراجعة مستخدم تجيب عن سؤال حول ميزات مكان معيّن في "خرائط Google".
الحقول
reviewId
string
رقم تعريف مقتطف من المراجعة.
googleMapsUri
string
رابط يؤدي إلى مراجعة المستخدم على "خرائط Google".
title
string
تمثّل هذه السمة عنوان المراجعة.
تمثيل JSON
{
"reviewId": string,
"googleMapsUri": string,
"title": string
}
GroundingSupport
دعم تحديد المصدر
الحقول
groundingChunkIndices[]
integer
اختياريّ. قائمة بالفهارس (في grounding_chunk في response.candidate.grounding_metadata) تحدّد الاقتباسات المرتبطة بالمطالبة. على سبيل المثال، [1,3,4] تعني أنّ grounding_chunk[1] وgrounding_chunk[3] وgrounding_chunk[4] هي المحتوى الذي تم استرجاعه والمستخدَم في الادعاء. إذا كانت الاستجابة يتم بثها، تشير groundingChunkIndices إلى الفهارس في جميع الاستجابات. يتحمّل العميل مسؤولية تجميع أجزاء المستندات الأساسية من جميع الردود (مع الحفاظ على الترتيب نفسه).
confidenceScores[]
number
اختياريّ. درجة الثقة في مراجع الدعم تتراوح القيم بين 0 و1. 1 هي أعلى درجة ثقة. يجب أن يكون حجم هذه القائمة مماثلاً لحجم groundingChunkIndices.
renderedParts[]
integer
النتائج فقط. فهارس في الحقل parts الخاص بمحتوى المرشّح تحدّد هذه الفهارس الأجزاء المعروضة المرتبطة بمصدر الدعم هذا.
segment
object (Segment)
شريحة المحتوى التي ينتمي إليها هذا الدعم
تمثيل JSON
{
"groundingChunkIndices": [
integer
],
"confidenceScores": [
number
],
"renderedParts": [
integer
],
"segment": {
object (Segment)
}
}
تقسيم
جزء من المحتوى
الحقول
partIndex
integer
فهرس كائن "الجزء" ضِمن كائن "المحتوى" الرئيسي
startIndex
integer
فهرس البداية في الجزء المحدّد، ويتم قياسه بالبايت. الإزاحة من بداية الجزء، شاملة، بدءًا من الصفر
endIndex
integer
فهرس النهاية في الجزء المحدّد، ويُقاس بالبايت. الإزاحة من بداية الجزء، باستثناء الجزء نفسه، بدءًا من الصفر
text
string
تمثّل هذه السمة النص الذي يتطابق مع المقطع من الردّ.
تمثيل JSON
{
"partIndex": integer,
"startIndex": integer,
"endIndex": integer,
"text": string
}
RetrievalMetadata
البيانات الوصفية المرتبطة باسترجاع المعلومات في مسار تحديد المصدر
الحقول
googleSearchDynamicRetrievalScore
number
اختياريّ. نتيجة تشير إلى مدى احتمال أن تساعد المعلومات من "بحث Google" في الإجابة عن الطلب. تندرج النتيجة ضمن النطاق [0, 1]، حيث يشير 0 إلى الاحتمال الأقل ويشير 1 إلى الاحتمال الأكبر. لا تتم تعبئة هذه النتيجة إلا عند تفعيل ميزة "الاستناد إلى بحث Google" و"الاسترجاع الديناميكي". ستتم مقارنته بالحدّ لتحديد ما إذا كان سيتم تفعيل البحث على Google.
تمثيل JSON
{
"googleSearchDynamicRetrievalScore": number
}
LogprobsResult
نتيجة Logprobs
الحقول
topCandidates[]
object (TopCandidates)
الطول = إجمالي عدد خطوات فك الترميز.
chosenCandidates[]
object (Candidate)
الطول = إجمالي عدد خطوات فك الترميز. قد يكون المرشّحون المختارون ضمن topCandidates أو لا يكونون.
logProbabilitySum
number
مجموع احتمالات اللوغاريتمات لجميع الرموز المميزة
تمثيل JSON
{
"topCandidates": [
{
object (TopCandidates)
}
],
"chosenCandidates": [
{
object (Candidate)
}
],
"logProbabilitySum": number
}
TopCandidates
المرشّحون الذين لديهم أعلى احتمالات السجلّ في كل خطوة من خطوات فك الترميز
الحقول
candidates[]
object (Candidate)
مرتّبة تنازليًا حسب احتمالية اللوغاريتم.
تمثيل JSON
{
"candidates": [
{
object (Candidate)
}
]
}
مرشح
المرشّح للرمز المميز ونتيجة logprobs
الحقول
token
string
قيمة سلسلة الرمز المميّز للمرشّح.
tokenId
integer
تمثّل هذه السمة قيمة المعرّف المميز للمرشّح.
logProbability
number
يشير ذلك إلى لوغاريتم يوضِّح معدّل احتمالية المرشّح.
تمثيل JSON
{
"token": string,
"tokenId": integer,
"logProbability": number
}
UrlContextMetadata
البيانات الوصفية ذات الصلة بأداة استرجاع سياق عنوان URL
الحقول
urlMetadata[]
object (UrlMetadata)
قائمة بسياق عناوين URL
تمثيل JSON
{
"urlMetadata": [
{
object (UrlMetadata)
}
]
}
UrlMetadata
سياق استرداد عنوان URL واحد
الحقول
retrievedUrl
string
عنوان URL الذي تم استرداده بواسطة الأداة
urlRetrievalStatus
enum (UrlRetrievalStatus)
حالة استرداد عنوان URL
تمثيل JSON
{
"retrievedUrl": string,
"urlRetrievalStatus": enum (UrlRetrievalStatus)
}
UrlRetrievalStatus
حالة استرداد عنوان 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 لأنّ المحتوى غير آمن.
CitationMetadata
تمثيل JSON
CitationSource
تمثيل JSON
مجموعة من بيانات تحديد المصدر لجزء من المحتوى
الحقول
citationSources[]
object (CitationSource)
اقتباسات من مصادر لردّ معيّن
تمثيل JSON
{
"citationSources": [
{
object (CitationSource)
}
]
}
CitationSource
اقتباس من مصدر لجزء من ردّ معيّن
الحقول
startIndex
integer
اختياريّ. بداية جزء الردّ الذي يعود إلى هذا المصدر
يشير الفهرس إلى بداية المقطع، ويتم قياسه بالبايت.
endIndex
integer
اختياريّ. نهاية الجزء الذي تم تحديد مصدره، غير مشمولة.
uri
string
اختياريّ. معرّف الموارد المنتظم (URI) الذي يتم تحديده كمصدر لجزء من النص
license
string
اختياريّ. ترخيص مشروع GitHub الذي تم تحديده كمصدر للجزء
يجب توفير معلومات الترخيص عند تضمين اقتباسات من الرمز البرمجي.
تمثيل JSON
{
"startIndex": integer,
"endIndex": integer,
"uri": string,
"license": string
}
GenerationConfig
تمثيل JSON
نمط البيانات
SpeechConfig
تمثيل JSON
VoiceConfig
تمثيل JSON
PrebuiltVoiceConfig
تمثيل JSON
MultiSpeakerVoiceConfig
تمثيل JSON
SpeakerVoiceConfig
تمثيل JSON
ThinkingConfig
تمثيل JSON
ThinkingLevel
ImageConfig
تمثيل JSON
MediaResolution
ResponseFormatConfig
تمثيل JSON
TextResponseFormat
تمثيل JSON
MimeType
AudioResponseFormat
تمثيل JSON
MimeType
التسليم
ImageResponseFormat
تمثيل JSON
MimeType
التسليم
AspectRatio
ImageSize
خيارات الإعداد لإنشاء النماذج والمخرجات لا يمكن ضبط جميع المَعلمات لكل نموذج.
الحقول
stopSequences[]
string
اختياريّ. مجموعة تسلسلات الأحرف (حتى 5) التي ستؤدي إلى إيقاف إنشاء الناتج. في حال تحديدها، ستتوقف واجهة برمجة التطبيقات عند ظهور stop_sequence للمرة الأولى. لن يتم تضمين تسلسل الإيقاف كجزء من الرد.
responseMimeType
string
اختياريّ. نوع MIME للنص المرشّح الذي تم إنشاؤه. أنواع MIME المتوافقة هي: text/plain: (تلقائي) إخراج نصي. application/json: استجابة JSON في المرشّحين للاستجابة ‫text/x.enum: ENUM كسلسلة استجابة في خيارات الاستجابة. يُرجى الرجوع إلى المستندات للاطّلاع على قائمة بجميع أنواع MIME المتوافقة مع النصوص.
responseSchema
object (Schema)
اختياريّ. مخطط الإخراج للنص المرشّح الذي تم إنشاؤه. يجب أن تكون المخططات مجموعة فرعية من مخطط OpenAPI ويمكن أن تكون كائنات أو أنواعًا أساسية أو مصفوفات.
في حال ضبط هذه السياسة، يجب أيضًا ضبط سياسة responseMimeType متوافقة. أنواع MIME المتوافقة: application/json: مخطط لاستجابة JSON. راجِع دليل إنشاء نص JSON لمزيد من التفاصيل.
_responseJsonSchema
value (Value format)
اختياريّ. مخطط الناتج للردّ الذي تم إنشاؤه. هذا بديل عن responseSchema يقبل مخطط JSON.
في حال ضبطها، يجب حذف responseSchema، ولكن يجب تضمين responseMimeType.
على الرغم من إمكانية إرسال مخطط JSON الكامل، لا تتوفّر جميع الميزات. على وجه التحديد، لا تتوفّر سوى السمات التالية:
$id
$defs
$ref
$anchor
type
format
title
description
enum (للنصوص والأرقام)
items
prefixItems
minItems
maxItems
minimum
maximum
anyOf
‫oneOf (يتم تفسيرها على النحو نفسه الذي يتم به تفسير anyOf)
properties
additionalProperties
required
يمكن أيضًا ضبط السمة propertyOrdering غير العادية.
يتم فك المراجع الدورية إلى حدّ معيّن، وبالتالي لا يمكن استخدامها إلا في السمات غير المطلوبة. (لا تكفي الخصائص التي تقبل القيم الخالية). إذا تم ضبط $ref على مخطط فرعي، لا يمكن ضبط أي خصائص أخرى، باستثناء تلك التي تبدأ بـ $.
responseJsonSchema
value (Value format)
اختياريّ. تفاصيل داخلية استخدِم responseJsonSchema بدلاً من هذا الحقل.
responseModalities[]
enum (Modality)
اختياريّ. طُرق عرض الردّ المطلوبة. تمثّل هذه السمة مجموعة الوسائط التي يمكن أن يعرضها النموذج، ويجب توقّعها في الردّ. هذه مطابقة تامة لطرق عرض الرد.
قد يتضمّن النموذج عدة مجموعات من الوسائط المتوافقة. إذا لم تتطابق الوسائط المطلوبة مع أي من المجموعات المتوافقة، سيظهر خطأ.
القائمة الفارغة تعادل طلب النص فقط.
candidateCount
integer
اختياريّ. عدد الردود التي تم إنشاؤها والمطلوب عرضها. إذا لم يتم ضبط هذا الحقل، سيتم ضبطه تلقائيًا على 1. يُرجى العِلم أنّ هذه الميزة لا تعمل مع نماذج الجيل السابق (عائلة Gemini 1.0).
maxOutputTokens
integer
اختياريّ. الحد الأقصى لعدد الرموز المميّزة التي يمكن تضمينها في ردّ محتمل
ملاحظة: تختلف القيمة التلقائية حسب الطراز، راجِع السمة Model.output_token_limit التي يتم عرضها من Model من الدالة getModel.
temperature
number
اختياريّ. تتحكّم هذه السمة في عشوائية الناتج.
ملاحظة: تختلف القيمة التلقائية حسب الطراز، راجِع السمة Model.temperature التي يتم عرضها من Model من الدالة getModel.
يمكن أن تتراوح القيم بين [0.0, 2.0].
topP
number
اختياريّ. الحدّ الأقصى للاحتمال التراكمي للرموز المميّزة التي يجب أخذها في الاعتبار عند أخذ العيّنات.
يستخدم النموذج اختيار العيّنات بناءً على الاحتمال التراكمي وأعلى k احتمال.
يتم ترتيب الرموز المميزة استنادًا إلى الاحتمالات المحدّدة لها، وبالتالي يتم أخذ الرموز المميزة الأكثر ترجيحًا فقط في الاعتبار. يحدّ اختيار العيّنات بناءً على أعلى k من الحد الأقصى لعدد الرموز المميّزة التي يجب أخذها في الاعتبار، بينما يحدّ اختيار العيّنات بناءً على الاحتمال التراكمي من عدد الرموز المميّزة استنادًا إلى الاحتمال التراكمي.
ملاحظة: تختلف القيمة التلقائية حسب Model ويتم تحديدها من خلال السمة Model.top_p التي تعرضها الدالة getModel. تشير السمة topK الفارغة إلى أنّ النموذج لا يطبّق أخذ العينات من أعلى k ولا يسمح بضبط topK على الطلبات.
topK
integer
اختياريّ. الحد الأقصى لعدد الرموز المميزة التي يجب أخذها في الاعتبار عند أخذ العيّنات
تستخدم نماذج Gemini طريقة اختيار العيّنات بناءً على الاحتمال التراكمي أو مزيجًا من طريقة اختيار العيّنات بناءً على أعلى k احتمال وطريقة اختيار العيّنات بناءً على الاحتمال التراكمي. تأخذ عملية أخذ العيّنات من أعلى k مجموعة الرموز المميّزة topK الأكثر احتمالاً في الاعتبار. لا تسمح النماذج التي تعمل باستخدام اختيار العيّنات بناءً على الاحتمال التراكمي بإعداد topK.
ملاحظة: تختلف القيمة التلقائية حسب Model ويتم تحديدها من خلال السمة Model.top_p التي تعرضها الدالة getModel. تشير السمة topK الفارغة إلى أنّ النموذج لا يطبّق أخذ العينات من أعلى k ولا يسمح بضبط topK على الطلبات.
seed
integer
اختياريّ. العبارة الأولية المستخدَمة في فك التشفير في حال عدم ضبط هذه القيمة، يستخدم الطلب قيمة أولية تم إنشاؤها عشوائيًا.
presencePenalty
number
اختياريّ. يتم تطبيق عقوبة الحضور على احتمالات تسجيل الرمز المميز التالي إذا سبق أن ظهر الرمز المميز في الردّ.
تكون هذه العقوبة ثنائية (مفعّلة أو غير مفعّلة) ولا تعتمد على عدد المرات التي يتم فيها استخدام الرمز المميّز (بعد المرة الأولى). استخدِم frequencyPenalty لفرض غرامة تزداد مع كل استخدام.
ستؤدي العقوبة الإيجابية إلى تثبيط استخدام الرموز المميزة التي سبق استخدامها في الرد، ما يزيد من المفردات.
سيشجّع العقاب السلبي على استخدام الرموز المميزة التي تم استخدامها من قبل في الردّ، ما يؤدي إلى تقليل المفردات.
frequencyPenalty
number
اختياريّ. يتم تطبيق عقوبة عدد مرات الظهور على logprobs للرمز المميز التالي، مضروبًا في عدد المرات التي ظهر فيها كل رمز مميز في الرد حتى الآن.
ستؤدي العقوبة الإيجابية إلى تثبيط استخدام الرموز المميزة التي سبق استخدامها، بما يتناسب مع عدد المرات التي تم فيها استخدام الرمز المميز: كلما زاد استخدام الرمز المميز، زادت صعوبة استخدام النموذج لهذا الرمز المميز مرة أخرى، ما يؤدي إلى زيادة مفردات الردود.
تنبيه: ستشجّع العقوبة السالبة النموذج على إعادة استخدام الرموز المميزة بما يتناسب مع عدد المرات التي تم فيها استخدام الرمز المميز. ستؤدي القيم السلبية الصغيرة إلى تقليل مفردات الردّ. ستؤدي القيم السالبة الأكبر إلى بدء النموذج في تكرار رمز مميز شائع إلى أن يصل إلى الحدّ الأقصى البالغ maxOutputTokens.
responseLogprobs
boolean
اختياريّ. إذا كانت القيمة صحيحة، سيتم تصدير نتائج logprobs في الردّ.
logprobs
integer
اختياريّ. لا يسري إلا إذا كان responseLogprobs=True. يحدّد هذا المعلمة عدد logprobs الأعلى، بما في ذلك المرشح المختار، الذي سيتم عرضه في كل خطوة فك ترميز في Candidate.logprobs_result. يجب أن يكون الرقم في النطاق [0, 20].
enableEnhancedCivicAnswers
boolean
اختياريّ. تفعيل الإجابات المحسّنة حول المواضيع المدنية قد لا تكون هذه الميزة متاحة لبعض الطُرز.
speechConfig
object (SpeechConfig)
اختياريّ. إعدادات إنشاء الكلام
thinkingConfig
object (ThinkingConfig)
اختياريّ. إعدادات ميزات التفكير سيتم عرض خطأ إذا تم ضبط هذا الحقل على نماذج لا تتيح التفكير.
imageConfig
object (ImageConfig)
اختياريّ. إعدادات إنشاء الصور سيتم عرض خطأ إذا تم ضبط هذا الحقل للطُرز التي لا تتوافق مع خيارات الإعداد هذه.
mediaResolution
enum (MediaResolution)
اختياريّ. في حال تحديدها، سيتم استخدام دقة الوسائط المحدّدة.
responseFormat
object (ResponseFormatConfig)
اختياريّ. إعدادات تنسيق إخراج الردّ تسمح هذه السمة بتحديد إعدادات الإخراج لكل نمط بيانات (نص أو صوت أو صورة) في بنية مسطّحة.
تمثيل JSON
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object (Schema)
},
"_responseJsonSchema": value,
"responseJsonSchema": value,
"responseModalities": [
enum (Modality)
],
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"seed": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseLogprobs": boolean,
"logprobs": integer,
"enableEnhancedCivicAnswers": boolean,
"speechConfig": {
object (SpeechConfig)
},
"thinkingConfig": {
object (ThinkingConfig)
},
"imageConfig": {
object (ImageConfig)
},
"mediaResolution": enum (MediaResolution),
"responseFormat": {
object (ResponseFormatConfig)
}
}
نمط البيانات
وسائط الردّ المتوافقة
عمليات التعداد
MODALITY_UNSPECIFIED
القيمة التلقائية
TEXT
تشير إلى أنّ النموذج يجب أن يعرض نصًا.
IMAGE
تشير إلى أنّ النموذج يجب أن يعرض صورًا.
AUDIO
تشير إلى أنّ النموذج يجب أن يعرض صوتًا.
SpeechConfig
إعدادات إنشاء الصوت وتحويله إلى نص
الحقول
voiceConfig
object (VoiceConfig)
الإعداد في حال الإخراج الصوتي بصوت واحد
multiSpeakerVoiceConfig
object (MultiSpeakerVoiceConfig)
اختياريّ. إعدادات نظام مكبّرات الصوت المتعددة ولا يمكن استخدامه مع الحقل voiceConfig.
languageCode
string
اختياريّ. رمز اللغة BCP-47 التابع لفريق هندسة الإنترنت (IETF) الذي ضبط المستخدم التطبيق لاستخدامه تُستخدَم للتعرّف على الكلام وتركيبه.
القيم الصالحة هي: de-DE وen-AU وen-GB وen-IN وen-US وes-US وfr-FR وhi-IN وpt-BR وar-XA وes-ES وfr-CA وid-ID وit-IT وja-JP وtr-TR وvi-VN وbn-IN وgu-IN وkn-IN وml-IN وmr-IN وta-IN وte-IN وnl-NL وko-KR وcmn-CN وpl-PL وru-RU وth-TH.
تمثيل JSON
{
"voiceConfig": {
object (VoiceConfig)
},
"multiSpeakerVoiceConfig": {
object (MultiSpeakerVoiceConfig)
},
"languageCode": string
}
VoiceConfig
إعدادات الصوت المطلوب استخدامه
الحقول
voice_config
Union type
تمثّل هذه السمة إعدادات مكبّر الصوت الذي سيتم استخدامه. يمكن أن يكون التعليق voice_config إحدى القيم التالية فقط:
prebuiltVoiceConfig
object (PrebuiltVoiceConfig)
إعدادات الصوت المُعدّ مسبقًا الذي سيتم استخدامه
تمثيل JSON
{
// voice_config
"prebuiltVoiceConfig": {
object (PrebuiltVoiceConfig)
}
// Union type
}
PrebuiltVoiceConfig
تحدّد هذه السمة إعدادات مكبّر الصوت المُدمج الذي سيتم استخدامه.
الحقول
voiceName
string
تمثّل هذه السمة اسم الصوت المضبوط مسبقًا المطلوب استخدامه.
تمثيل JSON
{
"voiceName": string
}
MultiSpeakerVoiceConfig
إعدادات نظام مكبّرات الصوت المتعددة
الحقول
speakerVoiceConfigs[]
object (SpeakerVoiceConfig)
الحقل مطلوب. جميع أصوات مكبّر الصوت المفعَّلة
تمثيل JSON
{
"speakerVoiceConfigs": [
{
object (SpeakerVoiceConfig)
}
]
}
SpeakerVoiceConfig
تمثّل هذه السمة إعدادات مكبّر صوت واحد في إعدادات مكبّرات صوت متعددة.
الحقول
speaker
string
الحقل مطلوب. اسم المتحدث المطلوب استخدامه. يجب أن يكون الاسم مطابقًا للاسم الوارد في الطلب.
voiceConfig
object (VoiceConfig)
الحقل مطلوب. إعدادات الصوت المطلوب استخدامه
تمثيل JSON
{
"speaker": string,
"voiceConfig": {
object (VoiceConfig)
}
}
ThinkingConfig
إعدادات ميزات التفكير
الحقول
includeThoughts
boolean
تُستخدَم لتحديد ما إذا كان سيتم تضمين الأفكار في الردّ. إذا كانت القيمة صحيحة، يتم عرض الأفكار فقط عندما تكون متاحة.
thinkingBudget
integer
عدد الرموز المميزة للأفكار التي يجب أن ينشئها النموذج.
thinkingLevel
enum (ThinkingLevel)
اختياريّ. تتحكّم هذه السمة في الحدّ الأقصى لعمق عملية الاستدلال الداخلية للنموذج قبل أن ينتج ردًا. تعتمد القيمة التلقائية على النموذج. يمكنك الرجوع إلى دليل مستويات التفكير لمزيد من التفاصيل. يُنصح به لطُرز Gemini 3 أو الأحدث. يؤدي استخدامها مع النماذج السابقة إلى حدوث خطأ.
تمثيل JSON
{
"includeThoughts": boolean,
"thinkingBudget": integer,
"thinkingLevel": enum (ThinkingLevel)
}
ThinkingLevel
السماح للمستخدم بتحديد مقدار التفكير باستخدام تعداد بدلاً من ميزانية عدد صحيح
عمليات التعداد
THINKING_LEVEL_UNSPECIFIED
القيمة التلقائية
MINIMAL
لا يتطلّب الأمر تفكيرًا كبيرًا.
LOW
مستوى التفكير منخفض.
MEDIUM
مستوى التفكير المتوسط
HIGH
مستوى التفكير العالي
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.
تمثيل JSON
{
"aspectRatio": string,
"imageSize": string
}
MediaResolution
تمثّل هذه السمة دقة الوسائط المُدخَلة.
عمليات التعداد
MEDIA_RESOLUTION_UNSPECIFIED
لم يتم ضبط دقة الوسائط.
MEDIA_RESOLUTION_LOW
تم ضبط دقة الوسائط على منخفضة (64 رمزًا مميزًا).
MEDIA_RESOLUTION_MEDIUM
تم ضبط دقة الوسائط على متوسطة (256 رمزًا مميزًا).
MEDIA_RESOLUTION_HIGH
تم ضبط دقة الوسائط على "عالية" (إعادة ضبط الإطار مع تكبير باستخدام 256 رمزًا مميزًا).
ResponseFormatConfig
إعدادات تنسيق إخراج الردّ هذا عنصر مسطّح يضبط فيه كل حقل فرعي اختياري طريقة إخراج معيّنة.
الحقول
text
object (TextResponseFormat)
اختياريّ. إعدادات تنسيق إخراج النص
audio
object (AudioResponseFormat)
اختياريّ. إعدادات تنسيق مصدر إخراج الصوت
image
object (ImageResponseFormat)
اختياريّ. إعدادات تنسيق إخراج الصورة
تمثيل JSON
{
"text": {
object (TextResponseFormat)
},
"audio": {
object (AudioResponseFormat)
},
"image": {
object (ImageResponseFormat)
}
}
TextResponseFormat
إعدادات تنسيق إخراج النص
الحقول
mimeType
enum (MimeType)
اختياريّ. نوع MIME الخاص بنص الناتج.
schema
value (Value format)
اختياريّ. مخطط JSON الذي يجب أن يتوافق معه الناتج. لا ينطبق إلا عندما يكون mimeType هو APPLICATION_JSON.
تمثيل JSON
{
"mimeType": enum (MimeType),
"schema": value
}
MimeType
أنواع MIME المتوافقة مع إخراج النص
عمليات التعداد
MIME_TYPE_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
APPLICATION_JSON
تنسيق الإخراج JSON
TEXT_PLAIN
تنسيق إخراج النص العادي
AudioResponseFormat
إعدادات تنسيق إخراج الصوت
الحقول
mimeType
enum (MimeType)
اختياريّ. نوع MIME الخاص بمصدر إخراج الصوت
delivery
enum (Delivery)
اختياريّ. وضع تسليم مصدر إخراج الصوت
sampleRate
integer
اختياريّ. معدّل البيانات في الملف الصوتي بوحدة هرتز
bitRate
integer
اختياريّ. معدل نقل البيانات بوحدة "بت في الثانية" ينطبق ذلك فقط على التنسيقات المضغوطة (MP3 وOpus).
تمثيل JSON
{
"mimeType": enum (MimeType),
"delivery": enum (Delivery),
"sampleRate": integer,
"bitRate": integer
}
MimeType
أنواع MIME المتوافقة لمصدر إخراج الصوت
عمليات التعداد
MIME_TYPE_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
AUDIO_MP3
تنسيق الصوت MP3
AUDIO_OGG_OPUS
تنسيق الصوت OGG Opus
AUDIO_L16
تنسيق الصوت Raw PCM (L16)
AUDIO_WAV
تنسيق الصوت WAV
AUDIO_ALAW
تنسيق الصوت A-law
AUDIO_MULAW
تنسيق الصوت Mu-law
إرسال المحتوى
وضع عرض الإعلانات لإخراج الصوت
عمليات التعداد
DELIVERY_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
INLINE
يتم عرض بيانات الصوت بشكل مضمّن في الردّ.
URI
يتم عرض البيانات الصوتية كمعرّف موارد موحّد (URI).
ImageResponseFormat
إعدادات تنسيق إخراج الصورة
الحقول
mimeType
enum (MimeType)
اختياريّ. نوع MIME الخاص بإخراج الصورة.
delivery
enum (Delivery)
اختياريّ. تحدّد هذه السمة طريقة عرض الصورة.
aspectRatio
enum (AspectRatio)
اختياريّ. نسبة العرض إلى الارتفاع لناتج الصورة
imageSize
enum (ImageSize)
اختياريّ. حجم الناتج من الصورة
تمثيل JSON
{
"mimeType": enum (MimeType),
"delivery": enum (Delivery),
"aspectRatio": enum (AspectRatio),
"imageSize": enum (ImageSize)
}
MimeType
أنواع MIME المتوافقة لإخراج الصور
عمليات التعداد
MIME_TYPE_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
IMAGE_JPEG
تنسيق صورة JPEG
إرسال المحتوى
طريقة إرسال الصور
عمليات التعداد
DELIVERY_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
INLINE
يتم عرض بيانات الصور بشكل مضمّن في الردّ.
URI
يتم عرض بيانات الصورة كمعرّف URI.
AspectRatio
نِسب العرض إلى الارتفاع المتاحة لإخراج الصور
عمليات التعداد
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
أحجام الصور المتوافقة مع إخراج الصور
عمليات التعداد
IMAGE_SIZE_UNSPECIFIED
القيمة التلقائية هذه القيمة غير مستخدَمة.
IMAGE_SIZE_FIVE_TWELVE
حجم الصورة 512 بكسل
IMAGE_SIZE_ONE_K
حجم الصورة 1K
IMAGE_SIZE_TWO_K
حجم الصورة 2K
IMAGE_SIZE_FOUR_K
حجم الصورة بدقة 4K
HarmCategory
تمثّل هذه السمة فئة التقييم.
تغطّي هذه الفئات أنواعًا مختلفة من الأضرار التي قد يريد المطوّرون تعديلها.
عمليات التعداد
HARM_CATEGORY_UNSPECIFIED
الفئة غير محدَّدة.
HARM_CATEGORY_DEROGATORY
PaLM: تعليقات سلبية أو مؤذية تستهدف الهوية و/أو السمات المحمية
HARM_CATEGORY_TOXICITY
PaLM: المحتوى الذي يتضمّن لغة وقحة أو غير محترمة أو نابية
HARM_CATEGORY_VIOLENCE
PaLM: يصف سيناريوهات تصوّر العنف ضد فرد أو مجموعة، أو أوصافًا عامة للمشاهد الدموية.
HARM_CATEGORY_SEXUAL
PaLM: تتضمّن السمة إشارات إلى أفعال جنسية أو محتوًى بذيئًا آخر.
HARM_CATEGORY_MEDICAL
PaLM: يروّج لنصائح طبية غير مدقَّقة.
HARM_CATEGORY_DANGEROUS
PaLM: المحتوى الخطير الذي يروّج لأفعال ضارّة أو يسهّل تنفيذها أو يشجّع عليها
HARM_CATEGORY_HARASSMENT
Gemini: المحتوى الذي يهدف إلى المضايقة
HARM_CATEGORY_HATE_SPEECH
‫Gemini - الكلام الذي يحض على الكراهية والمحتوى
HARM_CATEGORY_SEXUALLY_EXPLICIT
Gemini - المحتوى الجنسي الفاضح
HARM_CATEGORY_DANGEROUS_CONTENT
Gemini - المحتوى الخطير
HARM_CATEGORY_CIVIC_INTEGRITY
Gemini: المحتوى الذي قد يُستخدم للإضرار بالنزاهة المدنية تم إيقاف هذه السمة نهائيًا، لذا يُرجى استخدام enableEnhancedCivicAnswers بدلاً منها.
تم إيقاف هذا العنصر نهائيًا.
ModalityTokenCount
تمثيل JSON
نمط البيانات
تمثّل هذه السمة معلومات حول عدد الرموز المميزة لوسيط واحد.
الحقول
modality
enum (Modality)
تمثّل هذه السمة نوع الوسائط المرتبط بعدد الرموز المميزة هذا.
tokenCount
integer
عدد الرموز المميّزة
تمثيل JSON
{
"modality": enum (Modality),
"tokenCount": integer
}
نمط البيانات
طريقة عرض جزء المحتوى
عمليات التعداد
MODALITY_UNSPECIFIED
طريقة غير محدّدة
TEXT
نص عادي
IMAGE
صورة:
VIDEO
الفيديو
AUDIO
ملف صوتي:
DOCUMENT
مستند، مثل PDF
SafetyRating
تمثيل JSON
HarmProbability
تمثّل هذه السمة تقييم السلامة لجزء من المحتوى.
يتضمّن تقييم الأمان فئة الضرر ومستوى احتمالية الضرر في تلك الفئة لقطعة من المحتوى. يتم تصنيف المحتوى من حيث الأمان ضمن عدد من فئات الضرر، ويتم تضمين احتمالية تصنيف الضرر هنا.
الحقول
category
enum (HarmCategory)
الحقل مطلوب. تمثّل هذه السمة فئة التقييم.
probability
enum (HarmProbability)
الحقل مطلوب. تمثّل هذه السمة احتمال الضرر من هذا المحتوى.
blocked
boolean
هل تم حظر هذا المحتوى بسبب هذا التقييم؟
تمثيل JSON
{
"category": enum (HarmCategory),
"probability": enum (HarmProbability),
"blocked": boolean
}
HarmProbability
احتمال أن يكون المحتوى ضارًا
يقدّم نظام التصنيف احتمال أن يكون المحتوى غير آمن. ولا يشير ذلك إلى مدى خطورة الضرر الذي قد يسبّبه المحتوى.
عمليات التعداد
HARM_PROBABILITY_UNSPECIFIED
لم يتم تحديد الاحتمالية.
NEGLIGIBLE
من غير المحتمل أن يكون المحتوى غير آمن.
LOW
إذا كان من المحتمَل أنّ المحتوى غير آمن
MEDIUM
هناك احتمال متوسط بأن يكون المحتوى غير آمن.
HIGH
من المحتمل جدًا أن يكون المحتوى غير آمن.
SafetySetting
تمثيل JSON
HarmBlockThreshold
إعدادات الأمان التي تؤثر في سلوك الحظر المتعلق بالأمان
يؤدي ضبط إعدادات الأمان لفئة معيّنة إلى تغيير الاحتمالية المسموح بها لحظر المحتوى.
الحقول
category
enum (HarmCategory)
الحقل مطلوب. فئة هذا الإعداد
threshold
enum (HarmBlockThreshold)
الحقل مطلوب. تتحكّم هذه السمة في حد الاحتمال الذي يتم عنده حظر الضرر.
تمثيل JSON
{
"category": enum (HarmCategory),
"threshold": enum (HarmBlockThreshold)
}
HarmBlockThreshold
الحظر عند مستوى احتمال ضرر محدّد أو أعلى
عمليات التعداد
HARM_BLOCK_THRESHOLD_UNSPECIFIED
لم يتم تحديد الحدّ.
BLOCK_LOW_AND_ABOVE
سيتم السماح بالمحتوى الذي يتضمّن مستوى "ضئيل".
BLOCK_MEDIUM_AND_ABOVE
سيُسمح بالمحتوى الذي يتضمّن تصنيفًا بـ "ضئيل" و"منخفض".
BLOCK_ONLY_HIGH
سيُسمح بالمحتوى الذي يتضمّن مستوى خطورة "ضئيل" و"منخفض" و"متوسط".
BLOCK_NONE
سيتم السماح بكل المحتوى.
OFF
أوقِف فلتر الأمان.
ServiceTier
فئة الخدمة للطلب
عمليات التعداد
unspecified
فئة الخدمة التلقائية، وهي الفئة العادية
standard
فئة الخدمة العادية
flex
فئة خدمة Flex
priority
فئة الخدمة ذات الأولوية
إرسال ملاحظات
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0‏ ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0‏. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers‏. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2026-05-20 (حسب التوقيت العالمي المتفَّق عليه)
هل تريد مشاركة ملاحظاتك معنا؟
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2026-05-20 (حسب التوقيت العالمي المتفَّق عليه)"],[],[]]
البنود
الخصوصية
Manage cookies
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어