> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# البدء السريع في Gemini API: استخدم الطلبات الأصلية والطلبات المتوافقة مع OpenAI عبر CometAPI

> استدعِ نماذج Gemini النصية عبر CometAPI باستخدام طلبات generateContent الأصلية أو طلبات Chat Completions المتوافقة مع OpenAI.

## ما الذي ستبنيه

سترسل طلب Gemini أصليًا إلى `POST /v1beta/models/\{model\}:generateContent`، ثم تقارنه بخيار `POST /v1/chat/completions` المتوافق مع OpenAI للتطبيقات التي تستخدم بالفعل بنية طلبات Chat Completions.

## المتطلبات المسبقة

* مفتاح API من CometAPI مخزَّن في `COMETAPI_KEY`
* model ID لنموذج Gemini نصي من [صفحة النماذج](/ar/overview/models)
* `curl` أو Python 3.10+ أو Node.js 18+

## مفتاح API وعنوان URL الأساسي والمصادقة

استخدم endpoint الأصلي لـ Gemini عندما تريد حقول طلب Gemini:

```text theme={null}
https://api.cometapi.com/v1beta/models/{model}:generateContent
```

استخدم `x-goog-api-key` لطلبات HTTP الأصلية المباشرة لـ Gemini:

```text theme={null}
x-goog-api-key: $COMETAPI_KEY
```

استخدم عنوان URL الأساسي المتوافق مع OpenAI فقط عندما يكون تطبيقك يستخدم بالفعل Chat Completions:

```text theme={null}
https://api.cometapi.com/v1
```

## تنسيق Gemini الأصلي

تستخدم طلبات Gemini الأصلية `contents` و`parts` و`generationConfig`. استخدم هذا المسار عندما تحتاج إلى حقول خاصة بـ Gemini مثل عناصر التحكم في التفكير، وأجزاء الوسائط، وGoogle Search grounding، أو عوامل Streaming الأصلية.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cometapi.com/v1beta/models/your-gemini-model-id:generateContent" \
    -H "x-goog-api-key: $COMETAPI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "Explain why base URL configuration matters."
            }
          ]
        }
      ],
      "generationConfig": {
        "temperature": 0.3
      }
    }'
  ```

  ```python Python theme={null}
  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="your-gemini-model-id",
      contents="Explain why base URL configuration matters.",
      config={
          "temperature": 0.3,
      },
  )

  print(response.text)
  ```

  ```javascript Node.js theme={null}
  import { GoogleGenAI } from "@google/genai";

  const ai = new GoogleGenAI({
    apiKey: process.env.COMETAPI_KEY,
    httpOptions: {
      baseUrl: "https://api.cometapi.com",
      apiVersion: "v1beta",
    },
  });

  const response = await ai.models.generateContent({
    model: "your-gemini-model-id",
    contents: "Explain why base URL configuration matters.",
    config: {
      temperature: 0.3,
    },
  });

  console.log(response.text);
  ```
</CodeGroup>

## الخيار المتوافق مع OpenAI

استخدم المسار المتوافق مع OpenAI عندما تكون بصدد ترحيل OpenAI SDK موجود أو تطبيق Chat Completions قائم، ولا تحتاج إلى حقول طلب Gemini الأصلية.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cometapi.com/v1/chat/completions \
    -H "Authorization: Bearer $COMETAPI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "your-gemini-model-id",
      "messages": [
        {
          "role": "user",
          "content": "Explain why base URL configuration matters."
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["COMETAPI_KEY"],
      base_url="https://api.cometapi.com/v1",
  )

  completion = client.chat.completions.create(
      model="your-gemini-model-id",
      messages=[
          {
              "role": "user",
              "content": "Explain why base URL configuration matters.",
          }
      ],
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.COMETAPI_KEY,
    baseURL: "https://api.cometapi.com/v1",
  });

  const completion = await client.chat.completions.create({
    model: "your-gemini-model-id",
    messages: [
      {
        role: "user",
        content: "Explain why base URL configuration matters.",
      },
    ],
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## شرح التدفق

| المسار           | Endpoint                                        | بنية الطلب                                         | SDK                            | يُستخدم عندما                                                                                                        |
| ---------------- | ----------------------------------------------- | -------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Gemini الأصلي    | `POST /v1beta/models/\{model\}:generateContent` | `contents`, `parts`, `generationConfig`            | Google GenAI SDK أو HTTP مباشر | تحتاج إلى حقول خاصة بـ Gemini، أو أجزاء متعددة الوسائط، أو عناصر التحكم في التفكير، أو grounding، أو Streaming أصلي. |
| متوافق مع OpenAI | `POST /v1/chat/completions`                     | `messages`, `temperature`, `max_completion_tokens` | OpenAI SDK أو HTTP مباشر       | يستخدم تطبيقك بالفعل Chat Completions ويحتاج فقط إلى نموذج Gemini نصي خلف هذه البنية.                                |

لا تخلط بين تنسيقي الطلبين. حقول Gemini الأصلية مثل `contents` و`generationConfig` تنتمي إلى مسار `generateContent`. أما حقول Chat Completions مثل `messages` فتنتمي إلى المسار المتوافق مع OpenAI.

## استكشاف الأخطاء وإصلاحها / الأسئلة الشائعة

<AccordionGroup>
  <Accordion title="أي مسار يجب أن أبدأ به">
    ابدأ بـ `generateContent` الأصلي لـ Gemini عندما تكون تبني سير عمل Gemini جديدًا. استخدم المسار المتوافق مع OpenAI عندما يكون تطبيق موجود يعتمد بالفعل على OpenAI SDK أو بُنى طلبات Chat Completions.
  </Accordion>

  <Accordion title="حقول Gemini الأصلية تفشل مع Chat Completions">
    أرسل طلبات `contents` و`parts` و`generationConfig` و`streamGenerateContent` إلى endpoint الأصلي لـ Gemini. يتوقع المسار المتوافق مع OpenAI وجود `messages` ومعاملات Chat Completions.
  </Accordion>

  <Accordion title="model ID الخاص بـ Gemini يفشل">
    تأكد من أن model ID متاح لحسابك ويدعم المسار الذي تستدعيه. استخدم [صفحة النماذج](/ar/overview/models) للعثور على model IDs الحالية.
  </Accordion>

  <Accordion title="يشير SDK إلى الخدمة الخاطئة">
    بالنسبة إلى طلبات Google GenAI SDK، اضبط عنوان URL الأساسي على `https://api.cometapi.com`. وبالنسبة إلى طلبات OpenAI SDK، اضبط `base_url` في Python أو `baseURL` في Node.js على `https://api.cometapi.com/v1`.
  </Accordion>
</AccordionGroup>

## الخطوات التالية

* استخدم [مرجع Gemini native API](/api/text/gemini-generating-content) للاطلاع على حقول الطلب والاستجابة الكاملة لـ `generateContent`.
* اقرأ [مرجع Chat Completions API](/api/text/chat) للتعرّف على بنية الطلب المتوافقة مع OpenAI.
* اضبط عملاء OpenAI SDK في [استخدام CometAPI مع OpenAI SDKs](/ar/guides/use-cometapi-with-openai-sdk).
* اعرض النماذج المتاحة باستخدام [عرض نماذج CometAPI المتاحة](/ar/guides/how-to-list-available-models).
* أضف معالجة إعادة المحاولة وحدود المعدل باستخدام [أكواد الأخطاء واستراتيجية إعادة المحاولة](/ar/guides/error-codes-and-retry-strategy).