سيساعدك هذا الدليل في بدء استخدام واجهة برمجة التطبيقات القديمة generateContent. بالنسبة إلى المشاريع والتطبيقات الجديدة، ننصحك بشدة باستخدام Interactions API الجديدة، وهي أسهل وأفضل طريقة للاستفادة من نماذج Gemini ووكلائه.
يوضّح لك هذا الدليل السريع كيفية تثبيت
المكتبات وإجراء طلبك الأول، والعرض تدريجيًا للردود، وإنشاء محادثات مترابطة، واستخدام الأدوات باستخدام طريقة generateContent العادية.
الحصول على مفتاح واجهة برمجة تطبيقات
لاستخدام Gemini API، يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات للمصادقة على طلباتك وفرض حدود الأمان وتتبُّع الاستخدام في حسابك.
- ينشئ Google AI Studio تلقائيًا مشروعًا ومفتاح واجهة برمجة تطبيقات للمستخدمين الجدد. يمكنك نسخه من صفحة مفاتيح واجهة برمجة التطبيقات.
- إذا كنت بحاجة إلى مفتاح جديد، انقر على إنشاء مفتاح واجهة برمجة تطبيقات في AI Studio واتّبِع مربع الحوار لإضافة زوج جديد من المفتاح والمشروع.
اضبط مفتاحك كمتغيّر بيئة:
export GEMINI_API_KEY="YOUR_API_KEY"
الترقية إلى الفئة المدفوعة
تؤدي الترقية إلى الفئة المدفوعة إلى زيادة حدود معدّل الطلبات وتتطلّب إعداد Cloud Billing.
- انقر على إعداد الفوترة في صفحة مفاتيح واجهة برمجة التطبيقات أو المشاريع في AI Studio.
- اتّبِع مربّع حوار "الفوترة في Cloud" لإنشاء حساب فوترة أو ربطه، وإضافة طريقة دفع، ودفع مبلغ مسبق لا يقل عن 10 دولار أمريكي (أو ما يعادله بالعملة المحلية) في شكل أرصدة مدفوعة.
- يمكنك الاطّلاع على استخدامك لواجهة برمجة التطبيقات في Google AI Studio ضمن لوحة البيانات > الاستخدام.
لمزيد من المعلومات، يُرجى الاطّلاع على صفحة الفوترة.
تثبيت حزمة تطوير البرامج (SDK) من Google GenAI
Python
باستخدام Python 3.9 أو إصدار أحدث، ثبِّت حزمة
google-genai
باستخدام
أمر pip التالي:
pip install -q -U google-genai
JavaScript
باستخدام Node.js الإصدار 18 أو إصدار أحدث، ثبِّت حزمة تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي في TypeScript وJavaScript باستخدام أمر npm التالي:
npm install @google/genai
إنشاء نص
استخدِم طريقة models.generate_content من أجل
إنشاء ردّ نصي.
Python
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.6-flash",
contents="Explain how AI works in a few words"
)
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.6-flash",
contents: "Explain how AI works in a few words",
});
console.log(response.text);
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works in a few words"
}
]
}
]
}'
عرض الردود تدريجيًا
تعرض النماذج تلقائيًا ردًا بعد اكتمال عملية الإنشاء بأكملها. للحصول على تجربة أسرع وأكثر تفاعلية، يمكنك بث أجزاء الرد أثناء إنشائها.
Python
response = client.models.generate_content_stream(
model="gemini-3.6-flash",
contents="Explain how AI works in detail"
)
for chunk in response:
print(chunk.text, end="", flush=True)
JavaScript
async function main() {
const responseStream = await ai.models.generateContentStream({
model: "gemini-3.6-flash",
contents: "Explain how AI works in detail",
});
for await (const chunk of responseStream) {
process.stdout.write(chunk.text);
}
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:streamGenerateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works in detail"
}
]
}
]
}'
محادثات مترابطة
بالنسبة إلى المحادثات المترابطة، توفّر حِزم تطوير البرامج (SDK) أداة مساعدة chats ذات الحالة لإنشاء تجربة محادثة مترابطة تدير سجل المحادثات تلقائيًا.
Python
chat = client.chats.create(model="gemini-3.6-flash")
response1 = chat.send_message("I have 2 dogs in my house.")
print("Response 1:", response1.text)
response2 = chat.send_message("How many paws are in my house?")
print("Response 2:", response2.text)
JavaScript
async function main() {
const chat = ai.chats.create({ model: "gemini-3.6-flash" });
let response = await chat.sendMessage({ message: "I have 2 dogs in my house." });
console.log("Response 1:", response.text);
response = await chat.sendMessage({ message: "How many paws are in my house?" });
console.log("Response 2:", response.text);
}
main();
REST
# REST is stateless. You must pass the full conversation history in the request.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [{"text": "I have 2 dogs in my house."}]
},
{
"role": "model",
"parts": [{"text": "That is nice! Two dogs mean you have plenty of company."}]
},
{
"role": "user",
"parts": [{"text": "How many paws are in my house?"}]
}
]
}'
استخدام الأدوات
يمكنك توسيع إمكانات النموذج من خلال تحديد المصدر من خلال "بحث Google" للوصول إلى محتوى الويب في الوقت الفعلي. يقرّر النموذج تلقائيًا متى يجب البحث، وينفّذ طلبات البحث، ويصوغ ردًا.
Python
from google import genai
from google.genai import types
config = types.GenerateContentConfig(
tools=[types.Tool(google_search=types.GoogleSearch())]
)
response = client.models.generate_content(
model="gemini-3.6-flash",
contents="Who won the euro 2024?",
config=config
)
print(response.text)
metadata = response.candidates[0].grounding_metadata
if metadata.web_search_queries:
print("\nSearch queries executed:")
for query in metadata.web_search_queries:
print(f" - {query}")
if metadata.grounding_chunks:
print("\nSources:")
for chunk in metadata.grounding_chunks:
print(f" - [{chunk.web.title}]({chunk.web.uri})")
JavaScript
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.6-flash",
contents: "Who won the euro 2024?",
config: {
tools: [{ googleSearch: {} }]
}
});
console.log(response.text);
const metadata = response.candidates[0]?.groundingMetadata;
if (metadata?.webSearchQueries) {
console.log("\nSearch queries executed:");
for (const query of metadata.webSearchQueries) {
console.log(` - ${query}`);
}
}
if (metadata?.groundingChunks) {
console.log("\nSources:");
for (const chunk of metadata.groundingChunks) {
console.log(` - [${chunk.web.title}](${chunk.web.uri})`);
}
}
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{"text": "Who won the euro 2024?"}
]
}
],
"tools": [
{
"google_search": {}
}
]
}'
تتيح Gemini API أيضًا استخدام أدوات مضمّنة أخرى:
- تنفيذ الرموز البرمجية: يتيح للنموذج كتابة رموز Python البرمجية وتشغيلها لحلّ المسائل الرياضية المعقّدة.
- سياق عنوان URL: يتيح لك تحديد أساس الردود في عناوين URL محدّدة لصفحات الويب تقدّمها.
- البحث عن الملفات: تتيح لك هذه الميزة تحميل الملفات وتحديد المصدر الأساسي للردود من محتواها باستخدام البحث الدلالي.
- خرائط Google: تتيح لك تحديد أساس الردود استنادًا إلى بيانات الموقع الجغرافي والبحث عن أماكن واتجاهات وخرائط.
- استخدام الكمبيوتر: تتيح هذه الميزة للنموذج التفاعل مع شاشة ولوحة مفاتيح وفأرة افتراضية على الكمبيوتر لتنفيذ المهام.
استدعاء الدوال المخصّصة
استخدِم استدعاء الدوال لربط النماذج بأدواتك وواجهات برمجة التطبيقات المخصّصة. يحدّد النموذج الوقت المناسب لاستدعاء الدالة ويعرض functionCall في الردّ الذي يتلقّاه تطبيقك لتنفيذه.
يعرّف هذا المثال دالة وهمية لدرجة الحرارة ويتحقّق مما إذا كان النموذج يريد استدعاءها.
Python
from google import genai
from google.genai import types
weather_function = {
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco",
},
},
"required": ["location"],
},
}
tools = types.Tool(function_declarations=[weather_function])
config = types.GenerateContentConfig(tools=[tools])
contents = ["What's the temperature in London?"]
response = client.models.generate_content(
model="gemini-3.6-flash",
contents=contents,
config=config,
)
part = response.candidates[0].content.parts[0]
if part.function_call:
fc = part.function_call
print(f"Model requested function: {fc.name} with args {fc.args}")
mock_result = {"temperature": "15C", "condition": "Cloudy"}
contents.append(response.candidates[0].content)
fn_response_part = types.Part.from_function_response(
name=fc.name,
response=mock_result,
id=fc.id
)
contents.append(types.Content(role="user", parts=[fn_response_part]))
final_response = client.models.generate_content(
model="gemini-3.6-flash",
contents=contents,
config=config,
)
print("Final Response:", final_response.text)
JavaScript
import { GoogleGenAI, Type } from '@google/genai';
async function main() {
const weatherFunction = {
name: 'get_current_temperature',
description: 'Gets the current temperature for a given location.',
parameters: {
type: Type.OBJECT,
properties: {
location: {
type: Type.STRING,
description: 'The city name, e.g. San Francisco',
},
},
required: ['location'],
},
};
const contents = [{
role: 'user',
parts: [{ text: "What's the temperature in London?" }]
}];
const response = await ai.models.generateContent({
model: 'gemini-3.6-flash',
contents: contents,
config: {
tools: [{ functionDeclarations: [weatherFunction] }],
},
});
if (response.functionCalls && response.functionCalls.length > 0) {
const fc = response.functionCalls[0];
console.log(`Model requested function: ${fc.name}`);
const mockResult = { temperature: "15C", condition: "Cloudy" };
contents.push(response.candidates[0].content);
contents.push({
role: 'user',
parts: [{
functionResponse: {
name: fc.name,
response: mockResult,
id: fc.id
}
}]
});
const finalResponse = await ai.models.generateContent({
model: 'gemini-3.6-flash',
contents: contents,
config: {
tools: [{ functionDeclarations: [weatherFunction] }],
},
});
console.log("Final Response:", finalResponse.text);
}
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [{"text": "What'\''s the temperature in London?"}]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco"
}
},
"required": ["location"]
}
}
]
}
]
}'
الخطوات التالية
بعد أن بدأت استخدام واجهة Gemini API، يمكنك الاطّلاع على الأدلة التالية لإنشاء تطبيقات أكثر تقدّمًا: