التوثيق
الاتصال

Google GenAI SDK

Markdown

صيغة Gemini الأصلية: حزمة Google GenAI SDK لـPython وJavaScript، وطلبات REST المباشرة.

الدليل الكامل

التثبيت

pip 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)

المدخلات الممكن إرسالها

  • حقول المستوى الأعلى: 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 مع status INVALID_ARGUMENT والفئة invalid_request (في ErrorInfo.reason — INVALID_REQUEST). كما تعيد أخطاء JSON غير الصالح ومعاملات المسار والفحوص الأخرى الرمز 400؛ اقرأ نص الخطأ وRequest ID. تختلف القدرات بحسب النموذج: تحقق من صِيَغه ومدخلاته في الكتالوج.
الإدخالأنواع MIME المدعومة
صور مضمّنة inlineimage/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)

النماذج المتاحة

تتوفر 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.

هل لديك أسئلة أخرى؟ أرسل Request ID ووصفاً للمشكلة وسنساعدك على فهمها.مراسلة الدعم