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

# دليل استخدام Gemini Generate Content API

> Gemini AI API guide - Ace Data Cloud

Google Gemini هو نظام محادثة بالذكاء الاصطناعي قوي جدًا، يمكنه إنشاء ردود سلسة وطبيعية خلال ثوانٍ عبر إدخال المطالبات. يصف هذا المستند بشكل أساسي كيفية استخدام Gemini Generate Content API، وهو تنسيق API الأصلي الرسمي من Google، ويدعم نقطتي النهاية `generateContent` و`streamGenerateContent`.

## الفرق عن Chat Completions API

يستخدم Gemini Generate Content API تنسيق الطلبات الأصلي الرسمي من Google (حقل `contents`) بدلًا من التنسيق المتوافق مع OpenAI (حقل `messages`). إذا كنت تستخدم بالفعل Google Gemini SDK أو كنت على دراية بتنسيق API الرسمي، فيمكنك استخدام هذا API مباشرةً دون الحاجة إلى تعديل تنسيق الطلب.

## نطاق الدعم الحالي

تقبل الواجهة مدخلات النصوص والصور والفيديو والصوت (عبر `inlineData` أو `fileData`)، وتكوينات التفكير وإعلانات الدوال المخصصة. لا يوجد حتى الآن ضمان موحد لتوافر الحقول الأصلية مثل مخرجات الصوت والأدوات المضمنة والتخزين المؤقت الصريح للسياق؛ يُرجى الاعتماد على النتائج الفعلية التي يعيدها النموذج المحدد.

عند إرسال ملفات مثل الصوت باستخدام `fileData.fileUri`، يُرجى التأكد من إمكانية الوصول إلى الملف مباشرةً عبر HTTPS، وألا يعتمد على حالة تسجيل الدخول، وأن تغطي مدة صلاحية الرابط الموقّع كامل وقت معالجة الطلب. لا تُرجع تحليلات الصوت غير المتدفقة النتائج إلا بعد أن ينتهي النموذج من المعالجة، وقد تتجاوز 90 ثانية؛ يجب على العميل تعيين مهلة إجمالية طويلة بما يكفي وفقًا لحجم الملف وسيناريو العمل، لتجنب قطع الاتصال بينما لا يزال الخادم يعالج الطلب.

## عملية التقديم

قبل استخدام Gemini Generate Content API، يُرجى أولًا زيارة صفحة [Gemini Generate Content API](https://platform.acedata.cloud/documents/gemini-generate-content-api)، والنقر على زر "الحصول" للحصول على بيانات الاعتماد المطلوبة للطلب.

إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول. سيتوفر رصيد مجاني عند أول طلب.

## الاستخدام الأساسي

### Non-Streaming（غير متدفق）

أرسل طلب POST إلى `/v1beta/models/{model}:generateContent`:

> **تنبيه**: سلسلة `gemini-3.x` من flash هي نماذج تفكير، وستستهلك reasoning tokens أولًا؛ يُرجى ضبط `generationConfig.maxOutputTokens` على 512 أو أكثر، وإلا فقد تُرجع محتوى فارغًا فقط.

```bash theme={null}
curl -X POST "https://api.acedata.cloud/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "你好，请介绍一下你自己"
          }
        ]
      }
    ]
  }'
```

مثال على النتيجة المعادة:

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "你好！很高兴与你交流。"}]
      },
      "finishReason": "MAX_TOKENS"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 19,
    "thoughtsTokenCount": 489,
    "totalTokenCount": 514
  },
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 19,
    "total_tokens": 514,
    "thoughts_tokens": 489,
    "cost": {
      "amount": 0.008860916380159999,
      "currency": "credit",
      "list_amount": 0.009631430847999998
    }
  },
  "modelVersion": "gemini-3.5-flash",
  "model": "gemini-3.5-flash"
}
```

تتم محاسبة حقول token في `usageMetadata` وفقًا لدلالات Gemini الأصلية:

* يتضمن `promptTokenCount` ‏`cachedContentTokenCount`، ويُحتسب الجزء الذي تصيبه ذاكرة التخزين المؤقت بسعر قراءة ذاكرة التخزين المؤقت، ولن يُحتسب مرة أخرى كمدخلات عادية.
* تتم تسوية `promptTokensDetails` و`cacheTokensDetails` إلى `text_tokens` و`image_tokens` و`video_tokens` و`audio_tokens` وتفاصيل `cached_*` المقابلة ضمن `usage.prompt_tokens_details`. تُضمَّن هذه القيم على التوالي في `prompt_tokens` و`cached_tokens`؛ ولا يُعاد احتساب الوسائط المختلفة إلا بأسعارها الخاصة، دون محاسبة متكررة.
* يُحتسب كل من `candidatesTokenCount` و`thoughtsTokenCount` بسعر output token.
* إن `toolUsePromptTokenCount` هو token إدخال أدوات مستقل، ويُحتسب بسعر input token.

تعيد Ace Data Cloud بالإضافة إلى ذلك كائن `usage` موحّدًا، وتتم قراءة تكلفة هذه المكالمة بشكل موحّد عبر بروتوكولات النماذج من `usage.cost`. إن `cost` هي معاينة اختيارية للتكلفة؛ عندما لا تكون معاينة الأسعار متاحة مؤقتًا، ستظل استجابة النموذج تُعاد بشكل طبيعي، لكنها قد لا تتضمن هذا الحقل. تخضع الفاتورة النهائية لسجلات الاستخدام.

### Streaming（متدفق）

أرسل طلب POST إلى `/v1beta/models/{model}:streamGenerateContent?alt=sse`:

```bash theme={null}
curl -X POST "https://api.acedata.cloud/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "写一首关于春天的诗"
          }
        ]
      }
    ]
  }'
```

تُعاد الاستجابة المتدفقة تدريجيًا بتنسيق SSE (Server-Sent Events). عادةً ما تحتوي الأحداث الوسيطة على محتوى إضافي فقط؛ أما الحدث النهائي الذي يتضمن بيانات الاستخدام المعتمدة فسيحتوي على `usageMetadata` و`usage` الموحّد، وتبقى التكلفة في `usage.cost`:

```text theme={null}
data: {"candidates":[{"content":{"parts":[{"text":"Hello!"}],"role":"model"},"index":0}],"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

data: {"candidates":[{"content":{"parts":[],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":7,"candidatesTokenCount":89,"totalTokenCount":96},"usage":{"prompt_tokens":7,"completion_tokens":89,"total_tokens":96,"cost":{"amount":0.00026161075472,"currency":"credit","list_amount":0.000284359516}},"modelVersion":"gemini-3.1-flash-lite","model":"gemini-3.1-flash-lite"}

```

يشير إغلاق الاتصال إلى انتهاء التدفق؛ لا يرسل تدفق Gemini الأصلي `data: [DONE]`. إذا كانت معاينة السعر النهائي غير متاحة مؤقتًا، فسيظل `usage` يعيد استخدام token، لكنه سيحذف `cost`.

## النماذج المدعومة

| اسم النموذج | الوصف |
| - | - |
| `gemini-3.8-flash` | أحدث نموذج Flash، مناسب للمهام العامة عالية الجودة |
| `gemini-3.7-flash` | نموذج Flash عام عالي الجودة |
| `gemini-3.6-flash` | نموذج متعدد الوسائط مستقر عالي الأداء |
| `gemini-3.5-flash` | نموذج متعدد الوسائط عالي الإنتاجية |
| `gemini-3.5-flash-lite` | نموذج منخفض زمن الاستجابة ومنخفض التكلفة |
| `gemini-3.1-flash-lite` | نموذج خفيف بإصدار مستقر |
| `gemini-3.1-pro-preview` | نموذج للاستدلال المعقد والبرمجة |
| `gemini-3-flash-preview` | نموذج معاينة Gemini 3 Flash |
| `gemini-2.5-pro` | نموذج Gemini 2.5 Pro |
| `gemini-2.5-flash` | نموذج Gemini 2.5 Flash |
| `gemini-2.5-flash-lite` | نموذج Gemini 2.5 Flash-Lite |
| `gemini-3.1-flash-image` | نموذج توليد الصور |
| `gemini-3-pro-image` | نموذج توليد صور عالية الجودة |
| `gemini-2.5-flash-image` | نموذج توليد الصور Gemini 2.5 |

## الميزات المتقدمة

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

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好"}]
    }
  ],
  "systemInstruction": {
    "parts": [{"text": "你是一个专业的诗人，所有回复都用诗歌形式。"}]
  }
}
```

### إعدادات التوليد

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "讲一个故事"}]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1024,
    "topP": 0.9,
    "topK": 40
  }
}
```

### وضع JSON

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "列出三个中国城市及其人口"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "population": {
            "type": "integer"
          }
        }
      }
    }
  }
}
```

### وضع التفكير (Thinking)

يمكن للنماذج التي تدعم ميزة التفكير (مثل gemini-2.5-flash وgemini-2.5-pro) تفعيل وضع التفكير:

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "解释量子纠缠"}]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 2048
    }
  }
}
```

### استدعاء الدوال

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "北京现在的天气怎么样？"}]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "获取指定城市的天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "城市名称"
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}
```

### محادثة متعددة الجولات

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "你好，我叫小明"}]
    },
    {
      "role": "model",
      "parts": [{"text": "你好小明！很高兴认识你。"}]
    },
    {
      "role": "user",
      "parts": [{"text": "我叫什么名字？"}]
    }
  ]
}
```

### فهم الصور

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "描述这张图片"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64_encoded_image_data..."
          }
        }
      ]
    }
  ]
}
```

## إعدادات الأمان

يمكن التحكم في تصفية المحتوى عبر `safetySettings`:

```json theme={null}
{
  "contents": [...],
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_ONLY_HIGH"
    }
  ]
}
```

## معالجة الأخطاء

| رمز حالة HTTP | المعنى |
| - | - |
| 400 | معلمات الطلب غير صالحة |
| 401 | فشلت المصادقة، يرجى التحقق من Token |
| 403 | تم اعتراض المحتوى بواسطة فلتر الأمان |
| 429 | الطلبات متكررة للغاية |
| 500 | خطأ داخلي في الخادم |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.