Gemini لتوليد المحتوى

استخدم تنسيق Gemini native API عبر CometAPI لتوليد النصوص، والإدخال متعدد الوسائط، وthinking/reasoning، وFunction Calling، وGoogle Search grounding، ووضع JSON، وStreaming.

POST /v1beta/models/{model}:{operator}

Python

Basic

from google import genai

client = genai.Client(
    api_key="<COMETAPI_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explain how AI works in a few words",
)

print(response.text)

200

{
  "candidates": [
    {
      "content": {
        "role": "<string>",
        "parts": [
          {
            "text": "<string>",
            "functionCall": {
              "name": "<string>",
              "args": {}
            },
            "inlineData": {
              "mimeType": "<string>",
              "data": "<string>"
            },
            "thought": true
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "<string>",
          "probability": "<string>",
          "blocked": true
        }
      ],
      "citationMetadata": {
        "citationSources": [
          {
            "startIndex": 123,
            "endIndex": 123,
            "uri": "<string>",
            "license": "<string>"
          }
        ]
      },
      "tokenCount": 123,
      "avgLogprobs": 123,
      "groundingMetadata": {
        "groundingChunks": [
          {
            "web": {
              "uri": "<string>",
              "title": "<string>"
            }
          }
        ],
        "groundingSupports": [
          {
            "groundingChunkIndices": [
              123
            ],
            "confidenceScores": [
              123
            ],
            "segment": {
              "startIndex": 123,
              "endIndex": 123,
              "text": "<string>"
            }
          }
        ],
        "webSearchQueries": [
          "<string>"
        ]
      },
      "index": 123
    }
  ],
  "promptFeedback": {
    "blockReason": "SAFETY",
    "safetyRatings": [
      {
        "category": "<string>",
        "probability": "<string>",
        "blocked": true
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 123,
    "candidatesTokenCount": 123,
    "totalTokenCount": 123,
    "trafficType": "<string>",
    "thoughtsTokenCount": 123,
    "promptTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "<string>",
        "tokenCount": 123
      }
    ]
  },
  "modelVersion": "<string>",
  "createTime": "<string>",
  "responseId": "<string>"
}

​

نظرة عامة

تدعم CometAPI تنسيق Gemini native API، ما يمنحك وصولًا كاملًا إلى الميزات الخاصة بـ Gemini مثل التحكم في thinking، وGoogle Search grounding، وأنماط توليد الصور الأصلية، وغير ذلك. استخدم نقطة النهاية هذه عندما تحتاج إلى إمكانات غير متاحة عبر نقطة نهاية الدردشة المتوافقة مع OpenAI.

​

البدء السريع

استبدل عنوان URL الأساسي ومفتاح API في أي Gemini SDK أو عميل HTTP:

الإعداد	الإعداد الافتراضي لـ Google	CometAPI
عنوان URL الأساسي	generativelanguage.googleapis.com	api.cometapi.com
مفتاح API	$GEMINI_API_KEY	$COMETAPI_KEY

يتم دعم كلٍّ من ترويسة x-goog-api-key وترويسة Authorization: Bearer للمصادقة.

​

Thinking (Reasoning)

يمكن لنماذج Gemini تنفيذ reasoning داخلي قبل إنشاء الاستجابة. تعتمد طريقة التحكم على جيل النموذج.

Gemini 3 (thinkingLevel)

تستخدم نماذج Gemini 3 القيمة thinkingLevel للتحكم في عمق reasoning. المستويات المتاحة: MINIMAL، LOW، MEDIUM، HIGH.

curl "https://api.cometapi.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Explain quantum physics simply."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "LOW"}
    }
  }'

Gemini 2.5 (thinkingBudget)

تستخدم نماذج Gemini 2.5 القيمة thinkingBudget للتحكم الدقيق على مستوى Token:

• 0 — تعطيل thinking
• -1 — ديناميكي (يقرر النموذج، وهو الإعداد الافتراضي)
• > 0 — ميزانية Token محددة (مثل 1024، 2048)

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Solve this logic puzzle step by step."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingBudget": 2048}
    }
  }'

قد يؤدي استخدام thinkingLevel مع نماذج Gemini 2.5 (أو thinkingBudget مع نماذج Gemini 3) إلى حدوث أخطاء. استخدم المعامل الصحيح لإصدار النموذج الخاص بك.

---

​

Streaming

استخدم streamGenerateContent?alt=sse كعامل تشغيل لتلقي Server-Sent Events أثناء قيام النموذج بإنشاء المحتوى. يحتوي كل حدث SSE على سطر data: يتضمن كائن JSON من نوع GenerateContentResponse.

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  -d '{
    "contents": [{"parts": [{"text": "Write a short poem about the stars"}]}]
  }'

---

​

تعليمات النظام

وجّه سلوك النموذج عبر المحادثة بأكملها باستخدام systemInstruction:

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "What is 2+2?"}]}],
    "systemInstruction": {
      "parts": [{"text": "You are a math tutor. Always show your work."}]
    }
  }'

---

​

وضع JSON

افرض إخراج JSON منظّمًا باستخدام responseMimeType. ويمكنك اختياريًا توفير responseSchema للتحقق الصارم من صحة المخطط:

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "List 3 planets with their distances from the sun"}]}],
    "generationConfig": {
      "responseMimeType": "application/json"
    }
  }'

---

​

Google Search Grounding

فعّل البحث على الويب في الوقت الفعلي عبر إضافة أداة googleSearch:

curl "https://api.cometapi.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -d '{
    "contents": [{"parts": [{"text": "Who won the euro 2024?"}]}],
    "tools": [{"google_search": {}}]
  }'

يتضمن الرد groundingMetadata مع روابط URL للمصادر ودرجات الثقة.

---

​

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

استجابة نموذجية من نقطة نهاية Gemini في CometAPI:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello"}]
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.0023
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 1,
    "totalTokenCount": 30,
    "trafficType": "ON_DEMAND",
    "thoughtsTokenCount": 24,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 5}],
    "candidatesTokensDetails": [{"modality": "TEXT", "tokenCount": 1}]
  },
  "modelVersion": "gemini-2.5-flash",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

يعرض الحقل thoughtsTokenCount في usageMetadata عدد الـ tokens التي أنفقها النموذج على الاستدلال الداخلي، حتى عندما لا يتم تضمين مخرجات التفكير في الاستجابة.

---

​

الفروق الرئيسية عن نقطة النهاية المتوافقة مع OpenAI

الميزة	Gemini Native (/v1beta/models/...)	OpenAI-Compatible (/v1/chat/completions)
التحكم في التفكير	thinkingConfig مع thinkingLevel / thinkingBudget	غير متاح
Google Search grounding	tools: [\{"google_search": \{\}\}]	غير متاح
Google Maps grounding	tools: [\{"googleMaps": \{\}\}]	غير متاح
نمط إنشاء الصور	responseModalities: ["IMAGE"]	غير متاح
ترويسة المصادقة	x-goog-api-key أو Bearer	Bearer فقط
تنسيق الاستجابة	تنسيق Gemini الأصلي (candidates, parts)	تنسيق OpenAI (choices, message)

التفويضات

x-goog-api-key · string · header · مطلوب

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer <key>) is also supported.

معلمات المسار

model · string · مطلوب

The Gemini model ID to use. See the Models page for current Gemini model IDs.

مثال:

"gemini-2.5-flash"

operator · enum<string> · مطلوب

The operation to perform. Use generateContent for synchronous responses, or streamGenerateContent?alt=sse for Server-Sent Events streaming.

الخيارات المتاحة: generateContent, streamGenerateContent?alt=sse

مثال:

"generateContent"

الجسم

application/json

contents · object[] · مطلوب

The conversation history and current input. For single-turn queries, provide a single item. For multi-turn conversations, include all previous turns.

Show child attributes

systemInstruction · object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools · object[]

Tools the model may use to generate responses. Supports function declarations, Google Search, Google Maps, and code execution.

Show child attributes

toolConfig · object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings · object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig · object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent · string

The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.

الاستجابة

200 - application/json

Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data:.

candidates · object[]

The generated response candidates.

Show child attributes

promptFeedback · object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata · object

Token usage statistics for the request.

Show child attributes

modelVersion · string

The model version that generated this response.

createTime · string

The timestamp when this response was created (ISO 8601 format).

responseId · string

Unique identifier for this response.