الانتقال إلى المحتوى الرئيسي
POST
/
v1beta
/
models
/
{model}
:
{operator}
import os
from google import genai

client = genai.Client(
    api_key=os.environ["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، وأنماط توليد الصور الأصلية، وغير ذلك. استخدم نقطة النهاية هذه عندما تحتاج إلى قدرات غير متاحة عبر نقطة نهاية الدردشة المتوافقة مع OpenAI.
كل من ترويسات x-goog-api-key وAuthorization: Bearer مدعومان للمصادقة.

​
بداية سريعة

لاستخدام أي Gemini SDK أو عميل HTTP مع CometAPI، استبدل عنوان URL الأساسي ومفتاح API:
SettingGoogle DefaultCometAPI
الإعدادالإعداد الافتراضي لـ GoogleCometAPI
Base URLgenerativelanguage.googleapis.comapi.cometapi.com
API Key$GEMINI_API_KEY$COMETAPI_KEY

​
إرسال إدخال فيديو

يقبل generateContent في Gemini الفيديو كجزء من المحتوى. اختر شكل الإدخال بناءً على مكان تخزين الفيديو:
Video sourceRequest partUse when
ملف فيديو محليinlineDataيكون الفيديو صغيرًا بما يكفي لإرساله بصيغة base64 ضمن طلب JSON.
عنوان URL عام للفيديوfileData.fileUriيكون الفيديو متاحًا عبر عنوان URL عام باستخدام HTTPS ولا يتطلب مصادقة.
بالنسبة إلى طلبات REST وcurl، استخدم أسماء الحقول بصيغة camelCase الخاصة بـ Gemini مثل inlineData.mimeType وfileData.fileUri. لا ترسل وسائط URL بصيغة file_data.file_uri.
يقرأ هذا المثال ملف MP4 محليًا، ويحوّله إلى base64، ثم يرسله في جسم الطلب: 
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_PATH="./your_video.mp4"
VIDEO_B64=$(base64 < "$VIDEO_PATH" | tr -d '\n')

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "${VIDEO_B64}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF
يرسل هذا المثال عنوان URL عامًا لملف MP4 باستخدام fileData.fileUri: 
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY
VIDEO_URL="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"

curl -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<EOF
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "${VIDEO_URL}"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "thinkingConfig": {"thinkingLevel": "MINIMAL"}
  }
}
EOF
لا يوصي CometAPI باستخدام مسار رفع منفصل عبر Gemini Files API لهذه نقطة النهاية. أرسل الوسائط ضمن طلب generateContent نفسه باستخدام inlineData أو fileData.fileUri.

​
تكوين التفكير (reasoning)

يمكن لنماذج Gemini تنفيذ reasoning داخلي قبل توليد الرد. تعتمد طريقة التحكم على إصدار النموذج.
تستخدم نماذج Gemini 3 thinkingLevel للتحكم في عمق reasoning. المستويات المتاحة: MINIMAL, LOW, MEDIUM, HIGH.استخدم gemini-3-flash-preview كـ نموذج المثال الافتراضي ما لم تكن تحتاج تحديدًا إلى variant مختلف من 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"}
    }
  }'
قد يؤدي استخدام thinkingLevel مع نماذج Gemini 2.5 (أو thinkingBudget مع نماذج Gemini 3) إلى حدوث أخطاء. استخدم المعلمة الصحيحة لإصدار النموذج الخاص بك.

​
بث الردود

لتلقي Server-Sent Events أثناء توليد النموذج للمحتوى، استخدم streamGenerateContent?alt=sse كـ operator. يحتوي كل حدث SSE على سطر data: مع كائن GenerateContentResponse بصيغة JSON. 
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"
    }
  }'
لتمكين البحث على الويب في الوقت الفعلي، أضف أداة 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 مع عناوين URLs للمصادر ودرجات الثقة.

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

استجابة نموذجية من نقطة نهاية 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 يوضح عدد الـ tokens التي استهلكها النموذج في الاستدلال الداخلي، حتى عندما لا يكون إخراج التفكير مضمنًا في الاستجابة.

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

الميزةGemini Native (/v1beta/models/...)OpenAI-Compatible (/v1/chat/completions)
التحكم في ThinkingthinkingConfig مع thinkingLevel / thinkingBudgetغير متاح
ربط Google Searchtools: [\{"google_search": \{\}\}]غير متاح
ربط Google Mapstools: [\{"googleMaps": \{\}\}]غير متاح
نمط توليد الصورresponseModalities: ["IMAGE"]غير متاح
ترويسة المصادقةx-goog-api-key أو BearerBearer فقط
تنسيق الاستجابةGemini native (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 $COMETAPI_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[]
​
systemInstruction
object

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

​
tools
object[]

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

​
toolConfig
object

Configuration for tool usage, such as function calling mode.

​
safetySettings
object[]

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

​
generationConfig
object

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

​
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.

​
promptFeedback
object

Feedback on the prompt, including safety blocking information.

​
usageMetadata
object

Token usage statistics for the request.

​
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.