صيغة Google للمحادثة (Gemini generateContent)

الوثائق الرسمية

Google Gemini API

📝 مقدّمة

يمكن استدعاء جميع نماذج Gemini على البوابة بشكلٍ أصلي عبر صيغة Google Gemini API ‏(generateContent / streamGenerateContent).

📮 نقطة الوصول

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

المصادقة

استخدم إحدى الطريقتين:

x-goog-api-key: $WS_API_KEY

أو معامل الاستعلام ?key=$WS_API_KEY.

💡 أمثلة الطلبات

محادثة أساسية ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ]
  }'

مثال على الاستجابة:

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "Hello! How can I help you today?"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 10,
    "totalTokenCount": 14
  },
  "modelVersion": "gemini-2.5-flash"
}

تعليمات النظام + إعدادات التوليد ✅

curl "http://baseurl/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "system_instruction": {
      "parts": [{"text": "You are a concise assistant. Answer in one sentence."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Why is the sky blue?"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 256,
      "topP": 0.95
    }
  }'

الاستجابة المتدفقة ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Tell me a short story"}]}
    ]
  }'

تصل الاستجابات كأحداث SSE، ويحتوي كل سطر data: على استجابة GenerateContentResponse جزئية.

إدخال الصور ✅

curl "http://baseurl/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_IMAGE>"}},
          {"text": "Describe this image."}
        ]
      }
    ]
  }'

استدعاء الدوال ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "What is the weather in Abu Dhabi?"}]}
    ],
    "tools": [
      {
        "function_declarations": [
          {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {"type": "string"}
              },
              "required": ["location"]
            }
          }
        ]
      }
    ]
  }'

استخدام الحزمة الرسمية

from google import genai

client = genai.Client(
    api_key="sk-...",                     # مفتاح WS API الخاص بك
    http_options={"base_url": "http://baseurl"},
)

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Hello, Gemini!",
)
print(resp.text)

📋 معاملات جسم الطلب

المعامل	النوع	مطلوب	الوصف
contents	array	نعم	أدوار المحادثة. لكل عنصر role ‏(user / model) وparts ‏(text وinline_data وfile_data وfunction_call وfunction_response)
system_instruction	object	لا	موجّه النظام، {"parts": [{"text": "..."}]}
generationConfig	object	لا	‏temperature وtopP وtopK وmaxOutputTokens وstopSequences وresponseMimeType وresponseSchema وthinkingConfig وresponseModalities وغيرها
tools	array	لا	‏function_declarations لاستدعاء الدوال
toolConfig	object	لا	نمط استدعاء الدوال: AUTO / ANY / NONE
safetySettings	array	لا	عتبات فئات الأمان

📥 حقول الاستجابة

الحقل	النوع	الوصف
candidates	array	المرشّحات المولّدة. يحتوي كل مرشّح على content.parts وfinishReason ‏(STOP وMAX_TOKENS وSAFETY وغيرها) وindex
usageMetadata	object	‏promptTokenCount وcandidatesTokenCount وtotalTokenCount وthoughtsTokenCount
modelVersion	string	إصدار النموذج المستخدم

بديل متوافق مع OpenAI

يمكن أيضًا استدعاء كل نموذج Gemini عبر صيغة OpenAI على POST /v1/chat/completions — وهو خيار مريح إذا كان تطبيقك يستخدم حزمة OpenAI SDK بالفعل.