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

POST

v1beta

models

{model}

{operator}

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)

{
  "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 2.5 (thinkingBudget)

تستخدم نماذج 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 للتحكم الدقيق على مستوى 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.

Anthropic Messages

Embeddings

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)

{
  "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>"
}

نظرة عامة

مرجع API

أدلة التكامل

الأخطاء

الأسعار والفوترة

الدعم

نظرة عامة

البدء السريع

Thinking (Reasoning)

Streaming

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

وضع JSON

Google Search Grounding

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

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

التفويضات

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

الجسم

الاستجابة

نظرة عامة

مرجع API

أدلة التكامل

الأخطاء

الأسعار والفوترة

الدعم

​نظرة عامة

​البدء السريع

​Thinking (Reasoning)

​Streaming

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

​وضع JSON

​Google Search Grounding

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

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

التفويضات

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

الجسم

الاستجابة

نظرة عامة

البدء السريع

Thinking (Reasoning)

Streaming

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

وضع JSON

Google Search Grounding

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

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