Google GenAI SDK
Markdownصيغة Gemini الأصلية: حزمة Google GenAI SDK لـPython وJavaScript، وطلبات REST المباشرة.
الدليل الكامل
التثبيت
pip install google-genainpm install @google/genaiالاتصال
العنوان هو https://api.ailoot.ai دون /v1beta: تجمع حزمة SDK المسار /v1beta/models/<النموذج>:generateContent تلقائياً. في Python يُحدد العنوان عبر HttpOptions(base_url=…)، وفي JavaScript عبر httpOptions.baseUrl. ترسل حزمة SDK المفتاح في الترويسة x-goog-api-key.
from google import genai
from google.genai import types
import os
client = genai.Client(
api_key=os.environ["AILOOT_API_KEY"],
http_options=types.HttpOptions(base_url="https://api.ailoot.ai"), # دون /v1beta
)
resp = client.models.generate_content(
model="gemini-3.8-flash",
contents="اقترح ثلاثة أسماء لمقهى.",
)
print(resp.text)import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: process.env.AILOOT_API_KEY,
httpOptions: { baseUrl: "https://api.ailoot.ai" }, // دون /v1beta
});
const resp = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "اقترح ثلاثة أسماء لمقهى.",
});
console.log(resp.text);curl "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $AILOOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "اقترح ثلاثة أسماء لمقهى."}]}
]
}' المدخلات الممكن إرسالها
- حقول المستوى الأعلى:
contents,systemInstruction,generationConfig,safetySettings,toolsوtoolConfig. generationConfigيقبلtemperature,topP,topK,maxOutputTokens,thinkingConfig,responseMimeType(text/plainأوapplication/json),responseSchemaأوresponseJsonSchema(كائن JSON)،stopSequences(مصفوفة سلاسل نصية)،candidateCount: 1، وقيمة صحيحة لـseed، وقيم عددية لـpresencePenaltyوfrequencyPenalty. تعتمد النطاقات والقدرات المسموح بها على النموذج المحدد؛ للحصول على رد JSON، اختر صيغة مخطط واحدة مدعومة وapplication/json. في النماذج النصية، تكونresponseModalities— فقط["TEXT"].safetySettings— مصفوفة كائنات تتضمنcategory,thresholdوالحقل الاختياريmethod؛ اختر القيم وفق توثيق النموذج المحدد.- في نماذج Gemini التي تدعم نوع الإدخال المطلوب،
parts[].inlineDataيحتوي علىmimeTypeوبيانات base64 غير فارغة؛ ويجب أن يكون PDF ملف PDF حقيقياً.fileDataيحتوي على عنوان عام يبدأ بـhttpsضمنfileUriونوع MIME للملف. يمكن ترك MIME دون تحديد لروابط YouTube.httpوالعناوين الخاصة وgs://وكائنات Google Files API غير مدعومة، وكذلك الرفع عبر Google Files API. يمكن إضافةvideoMetadata:startOffset/endOffsetكسلسلة نصية بالثواني (مثل1.5s) وfpsأكبر من 0 ولا يتجاوز 24. يُتحقق من حجم الجسم والسياق والإدخال المسموح وحد الرد بحسب النموذج والصيغة. - دوال العميل
functionDeclarationsينفذها تطبيقك. تقبل النماذج النصية أيضاً{"googleSearch": {}}و{"urlContext": {}}: كلاً منها على حدة أو معاً في مصفوفةtools. لا يمكن الجمع بين Google Search أو URL context وبينfunctionDeclarationsفي طلب واحد. لتوليد الصور، تتاح دوال العميل فقط. الأدوات المدمجة الأخرى وexplicit cache غير مدعومة. قد تتطلب Search/URL context حجز رصيد وفق الحد الكامل للإدخال؛ وتُحسب قيمtoolUsePromptTokenCountالفعلية بوصفها توكنات إدخال. - إذا كان النموذج لا يدعم حقلاً أو مرفقاً أو تركيبة أدوات، يُرفض الطلب قبل حجز الرصيد ولا يُخصم شيء. سيأتي رد HTTP
400معstatusINVALID_ARGUMENTوالفئةinvalid_request(فيErrorInfo.reason—INVALID_REQUEST). كما تعيد أخطاء JSON غير الصالح ومعاملات المسار والفحوص الأخرى الرمز400؛ اقرأ نص الخطأ وRequest ID. تختلف القدرات بحسب النموذج: تحقق من صِيَغه ومدخلاته في الكتالوج.
| الإدخال | أنواع MIME المدعومة |
|---|---|
| صور مضمّنة inline | image/png, image/jpeg, image/webp |
| المستندات | application/pdf; text/plain, text/html, text/css, text/csv, text/xml, text/rtf, text/markdown, text/javascript, application/x-javascript, text/x-python, application/x-python |
| الصوت | audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac |
| الفيديو | video/mp4, video/mpeg, video/mov, video/quicktime, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp |
import json, os, urllib.request
def generate(model, payload):
req = urllib.request.Request(
"https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
data=json.dumps(payload).encode(),
headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
"Content-Type": "application/json"},
)
# إرسال واحد فقط. بعد انتهاء المهلة، تحقّق من Request ID في سجل الاستخدام قبل إعادة المحاولة.
with urllib.request.urlopen(req, timeout=300) as response:
print("Request ID:", response.headers.get("X-Request-ID"))
return json.load(response)
import base64, pathlib, sys
# قدّم ملف PDF أو ملف صوت أو فيديو محليًا حقيقيًا، مع نوع MIME المدعوم له.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
{"text": "صِف محتوى الملف بإيجاز."},
{"inlineData": {"mimeType": mime,
"data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# مرفق بديل: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# لعنوان URL فعلي على YouTube: {"fileData": {"fileUri": youtube_url}}دورة الدالة الكاملة
أرسل تعريف الدالة، واستقبل functionCall، ونفّذ دالتك، وأعد functionResponse، ثم اطلب الرد التالي. احتفظ بكامل content للنموذج، بما في ذلك thoughtSignature؛ ولا تنشئ التوقيع بنفسك.
import json, os, urllib.request
def generate(model, payload):
req = urllib.request.Request(
"https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
data=json.dumps(payload).encode(),
headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
"Content-Type": "application/json"},
)
# إرسال واحد فقط. بعد انتهاء المهلة، تحقّق من Request ID في سجل الاستخدام قبل إعادة المحاولة.
with urllib.request.urlopen(req, timeout=300) as response:
print("Request ID:", response.headers.get("X-Request-ID"))
return json.load(response)
tools = [{"functionDeclarations": [{
"name": "multiply", "description": "ضرب عددين",
"parameters": {"type": "object", "properties": {
"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "اضرب 7 في 8 باستخدام دالة"}]}]
for turn in range(4): # ضع حدًا لحلقة الأدوات؛ لا تُعد إرسال طلب لم تتضح نتيجته.
reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
content = reply["candidates"][0]["content"]
contents.append(content) # احتفظ بجميع الأجزاء الأصلية وبـ thoughtSignature دون أي تغيير.
results = []
for part in content.get("parts", []):
call = part.get("functionCall")
if not call:
continue
if call["name"] != "multiply":
raise ValueError("Unexpected function")
args = call["args"]
result = {"name": call["name"], "response": {"value": args["a"] * args["b"]}}
if "id" in call:
result["id"] = call["id"]
results.append({"functionResponse": result})
if not results:
print(content)
break
contents.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool loop limit reached")الرد المتدفق
for chunk in client.models.generate_content_stream(
model="gemini-3.8-flash",
contents="صِف غروب الشمس فوق البحر",
):
print(chunk.text, end="", flush=True)curl -N "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $AILOOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"role": "user", "parts": [{"text": "صِف غروب الشمس فوق البحر"}]}]}' النماذج المتاحة
تتوفر 27 معرّفاً بصيغة Gemini: gemini-3.8-flash, gemini-3.1-pro, gemini-pro-agent, gemini-3.8-flash-tiered, gemini-3.8-flash-medium, gemini-3.8-flash-low, gemini-3.8-flash-high, gemini-3.7-flash, gemini-3.7-flash-tiered, gemini-3.7-flash-medium, gemini-3.7-flash-low, gemini-3.7-flash-high, gemini-3.6-flash, gemini-3.6-flash-tiered, gemini-3.6-flash-medium, gemini-3.6-flash-low, gemini-3.6-flash-high, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3.1-pro-low, gemini-3.1-pro-high, gemini-3.1-flash-lite, gemini-3-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-thinking, gemini-2.5-flash-lite.
تتوفر نماذج Gemini أيضاً بصيغة Anthropic Messages، وهو مناسب للعملاء الذين لا يدعمون سوى هذه الصيغة: Anthropic SDK.