إنشاء المحتوى

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 تنسيق API الأصلي لـ Gemini، ما يمنحك وصولًا كاملًا إلى الميزات الخاصة بـ Gemini مثل التحكم في التفكير، وGoogle Search grounding، وأنماط إنشاء الصور الأصلية، وغير ذلك. استخدم نقطة النهاية هذه عندما تحتاج إلى إمكانات غير متاحة عبر نقطة نهاية الدردشة المتوافقة مع OpenAI.

استخدم مرجع GenerateContent API الرسمي من Google بوصفه المصدر المعتمد لجميع حقول الطلب، ومخطط الاستجابة، والسلوك الخاص بنماذج Gemini. تشرح صفحة CometAPI هذه كيفية إرسال بنية الطلب الأصلية هذه عبر CometAPI.

يمكن أن تتغير معلمات طلب Gemini وحقول الاستجابة مع قيام Google بتحديث API الأصلي. راجع وثائق إنشاء النصوص لـ Gemini للحصول على أحدث قائمة كاملة بالمعلمات والسلوك الخاص بمزوّد الخدمة.

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

البدء السريع

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

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

إرسال مُدخلات الفيديو

يقبل Gemini generateContent الفيديو كجزء من المحتوى. اختر شكل الإدخال بناءً على مكان تخزين الفيديو:

مصدر الفيديو	جزء الطلب	يُستخدم عندما
ملف فيديو محلي	`inlineData`	يكون الفيديو صغيرًا بما يكفي لإرساله كـ base64 داخل طلب JSON.
رابط URL عام للفيديو	`fileData.fileUri`	يكون الفيديو متاحًا عبر رابط 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

يرسل هذا المثال رابط 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 لهذا الـ endpoint. أرسل الوسائط ضمن طلب generateContent نفسه باستخدام inlineData أو fileData.fileUri.

تهيئة التفكير (الاستدلال)

يمكن لنماذج 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) إلى حدوث أخطاء. استخدم المعامل الصحيح لإصدار النموذج لديك.

بث Responses

لتلقي Server-Sent Events أثناء قيام النموذج بإنشاء المحتوى، استخدم streamGenerateContent?alt=sse كعامل التشغيل. يحتوي كل حدث 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"
    }
  }'

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

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

الميزة	Gemini الأصلي (`/v1beta/models/...`)	المتوافق مع OpenAI (`/v1/chat/completions`)
التحكم في التفكير	`thinkingConfig` مع `thinkingLevel` / `thinkingBudget`	غير متاح
الارتكاز إلى Google Search	`tools: [\{"google_search": \{\}\}]`	غير متاح
الارتكاز إلى 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 $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[]

Conversation content. Each entry has an optional role (user or model) and a parts array.

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.

إنشاء رسالة

واجهات برمجة تطبيقات إنشاء الصور وتحريرها

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

الإشراف على المحتوى

مفاتيح API

البدء السريع

إرسال مُدخلات الفيديو

تهيئة التفكير (الاستدلال)

بث Responses

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

طلب إخراج JSON

الإسناد باستخدام Google Search

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

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

التفويضات

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

الجسم

الاستجابة

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

​إرسال مُدخلات الفيديو

​تهيئة التفكير (الاستدلال)

​بث Responses

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

​طلب إخراج JSON

​الإسناد باستخدام Google Search

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

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

التفويضات

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

الجسم

الاستجابة

البدء السريع

إرسال مُدخلات الفيديو

تهيئة التفكير (الاستدلال)

بث Responses

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

طلب إخراج JSON

الإسناد باستخدام Google Search

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

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