Gemini Generating Content - CometAPI Documentation

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-3-flash-preview",
    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
          }
        ]
      },
      "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": {
    "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 مثل التحكم في التفكير، وإسناد Google Search، وmodalities الأصلية لتوليد الصور، والمزيد. استخدم نقطة النهاية هذه عندما تحتاج إلى قدرات غير متاحة عبر OpenAI-compatible chat endpoint.

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

البدء السريع

لاستخدام أي Gemini SDK أو عميل HTTP مع CometAPI، استبدل Base URL ومفتاح API:

Setting	Google Default	CometAPI
Base URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
API Key	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

إعداد التفكير (الاستدلال)

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

Gemini 3 (thinkingLevel)
Gemini 2.5 (thinkingBudget)

تستخدم نماذج Gemini 3 القيمة thinkingLevel للتحكم في عمق الاستدلال. المستويات المتاحة: MINIMAL وLOW وMEDIUM وHIGH.استخدم gemini-3-flash-preview كنموذج المثال الافتراضي ما لم تكن بحاجة تحديدًا إلى إصدار Gemini 3 مختلف.

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-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 — تعطيل التفكير
-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) إلى حدوث أخطاء. استخدم المعامل الصحيح لإصدار النموذج الخاص بك.

بث الاستجابات

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

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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-3-flash-preview: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-3-flash-preview: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"
    }
  }'

Ground with Google Search

لتمكين البحث على الويب في الوقت الفعلي، أضف أداة googleSearch:

curl "https://api.cometapi.com/v1beta/models/gemini-3-flash-preview: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-3-flash-preview",
  "createTime": "2026-03-25T04:21:43.756483Z",
  "responseId": "CeynaY3LDtvG4_UP0qaCuQY"
}

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

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

الميزة	Gemini Native (`/v1beta/models/...`)	OpenAI-Compatible (`/v1/chat/completions`)
التحكم في التفكير	`thinkingConfig` مع `thinkingLevel` / `thinkingBudget`	غير متاح
Grounding عبر Google Search	`tools: [\{"google_search": \{\}\}]`	غير متاح
Grounding عبر Google Maps	`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

مطلوب

Gemini model ID. Example: gemini-3-flash-preview, gemini-2.5-pro. See the Models page for current options.

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

الجسم

application/json

contents

object[]

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-3-flash-preview",
    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
          }
        ]
      },
      "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": {
    "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>"
}

Documentation Index

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

​إعداد التفكير (الاستدلال)

​بث الاستجابات

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

​إخراج JSON للطلب

​Ground with Google Search

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

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

التفويضات

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

الجسم

الاستجابة

البدء السريع

إعداد التفكير (الاستدلال)

بث الاستجابات

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

إخراج JSON للطلب

Ground with Google Search

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

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