Gemini Chat Completion API 申请及使用

Google Gemini هي نظام محادثة AI قوي للغاية، حيث يمكنه توليد ردود طبيعية وسلسة في غضون ثوانٍ قليلة بمجرد إدخال كلمات التحفيز. يمكن لـ Gemini تقديم مساعدة ذكية مذهلة، مما يزيد بشكل كبير من كفاءة وإبداع البشر في العمل. تتناول هذه الوثيقة بشكل رئيسي عملية استخدام Gemini Chat Completion API، مما يتيح لنا استخدام وظيفة المحادثة الرسمية لـ Gemini بسهولة.

申请流程

لاستخدام Gemini Chat Completion API، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

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

📘 الوثيقة الكاملة: Gemini Chat Completion API →

基本使用

بعد ذلك، يمكنك ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

عند استخدام هذه الواجهة لأول مرة، نحتاج على الأقل إلى ملء ثلاثة محتويات، أحدها هو authorization، يمكنك اختياره مباشرة من القائمة المنسدلة. المعامل الآخر هو model، حيث يشير model إلى نوع نموذج Gemini الذي نختار استخدامه، وهنا لدينا 6 أنواع من النماذج، يمكنك الاطلاع على النماذج التي نقدمها. المعامل الأخير هو messages، حيث أن messages هو مصفوفة كلمات الاستفسار التي ندخلها، وهي مصفوفة تمثل إمكانية تحميل عدة كلمات استفسار في نفس الوقت، كل كلمة استفسار تحتوي على role و content، حيث يشير role إلى دور المستفسر، وقد قدمنا ثلاث هويات، وهي user و assistant و system. أما content فهو المحتوى المحدد لاستفسارنا. يمكنك أيضًا ملاحظة وجود كود استدعاء مطابق على الجانب الأيمن، يمكنك نسخ الكود وتشغيله مباشرة، أو يمكنك النقر على زر “Try” للاختبار.

提示：سلسلة gemini-3.x flash هي نماذج تفكير، ستستهلك أولاً رموز reasoning؛ يرجى ضبط max_tokens على 512 أو أكثر، وإلا قد يتم إرجاع محتوى فارغ فقط. gemini-3.6-flash هو النموذج الموصى به حاليًا، ويدعم ما يصل إلى 1 مليون توكن في السياق، وإدخال الصور، واستدعاء الأدوات، والاستجابة المتدفقة؛ حاليًا يتم استدعاؤه من خلال واجهة Chat Completions.

بعد الاستدعاء، نجد أن النتيجة المرجعة هي كما يلي:

{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-3.5-flash",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "أنا نموذج لغة كبير، تم تدريبي بواسطة Google.",
        "reasoning_content": "**تفكيري: الإجابة على سؤال المستخدم**\n\nحسنًا، إليك كيف سأقترب من الإجابة على سؤال المستخدم، \"ما هو النموذج الذي أنت عليه؟\". الجوهر هو أن أكون مباشرًا ومعلوماتيًا. أولاً، يجب أن أكون واضحًا بشأن أصلي. ثم، أحتاج إلى التأكد من أن الشرح سهل الفهم، نظرًا لأن المستخدم قد لا يكون على دراية بالمصطلحات التقنية. أحتاج إلى شرح ما يفعله \"نموذج اللغة الكبير\" فعليًا، وتقديم أمثلة قابلة للتواصل. أعلم أن المستخدم قد يبحث عن اسم محدد، مثلما تفعل النماذج الأخرى، لذا سأتعامل مع ذلك مباشرة ثم أنهيه بدعوة للاستمرار.\n\nلذا، إليك خطتي:\n\n1.  **ابدأ بالمعلومات الأساسية:** سأبدأ بالقول إنني نموذج لغة كبير تم إنشاؤه بواسطة Google. هذه هي القطعة الأساسية والأكثر أهمية في اللغز.\n2.  **تعريف المصطلح:** ثم، سأشرح \"نموذج اللغة الكبير\" بمصطلحات بسيطة. سأشرح ما أفعله - معالجة وتوليد النص؛ كيف أفعله - من خلال التدريب على كميات هائلة من بيانات النص؛ والهدف - أن أكون قادرًا على التواصل مثل الإنسان.\n3.  **توفير السياق:** بعد ذلك، لجعل المفهوم أكثر وضوحًا، سأقدم قائمة بأمثلة على قدراتي. سأذكر أشياء مثل الإجابة على الأسئلة، تلخيص النصوص، كتابة القصص، ترجمة اللغات، وتوليد الأفكار.\n4.  **الاعتراف بعدم وجود اسم شخصي:** سأنتظر السؤال المحتمل حول اسم النموذج (مثل ChatGPT) من خلال الإشارة بوضوح إلى أنني لا أملك اسمًا شخصيًا وأنه من الأفضل التفكير فيّ كمساعد AI من Google.\n5.  **إنهاء بدعوة:** أخيرًا، سأختتم بسؤال بسيط وودود لدعوة المزيد من التفاعل وتوجيه المحادثة.\n\nمع هذا النهج، أنا واثق من أنني يمكنني الإجابة بنجاح على هذا السؤال المهم.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

تتضمن النتيجة المرجعة عدة حقول، كما هو موضح أدناه:

id، معرف مهمة المحادثة التي تم إنشاؤها، يستخدم لتحديد هذه المهمة بشكل فريد.
model، النموذج المختار من موقع Gemini الرسمي.
choices، معلومات الرد التي قدمها Gemini على كلمات الاستفسار.
usage، إحصائيات حول استخدام الرموز لهذه المحادثة.

حيث أن choices تحتوي على معلومات رد Gemini، ويمكنك ملاحظة أن choices تحتوي على المعلومات المحددة للرد من Gemini، كما هو موضح في الصورة.

يمكنك أن ترى أن حقل content داخل choices يحتوي على المحتوى المحدد لرد Gemini.

图片理解（多模态输入）

Gemini هو نموذج متعدد الوسائط أصلي، يمكنه “رؤية الصور” مباشرة. لإدخال صورة، قم بتغيير content لرسالة معينة من سلسلة إلى مصفوفة كتل المحتوى، حيث تحتوي المصفوفة على كتل text و image_url معًا - وهذا يتوافق تمامًا مع تنسيق OpenAI، وكذلك مع تنسيق Gemini الرسمي. يدعم image_url.url نوعين من الكتابة:

base64 data: URI (موصى به، الأكثر استقرارًا): التنسيق هو data:<نوع الوسائط>;base64,<البيانات>، على سبيل المثال data:image/jpeg;base64,/9j/4AAQ.... نوع الوسائط (MIME) مكتوب بالفعل في بادئة data:، لذا لا حاجة لوجود حقل media_type منفصل.
رابط صورة يمكن الوصول إليه علنًا: على سبيل المثال https://cdn.acedata.cloud/4hfydw.jpg.

أنواع الصور المدعومة: png، jpeg، webp، heic، heif. مثال على كود استدعاء Python (base64 data URI):

import base64
import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

# قراءة الصورة المحلية كـ base64 data URI
with open("image.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{base64_image}"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "يرجى وصف هذه الصورة في جملة واحدة."},
                {"type": "image_url", "image_url": {"url": data_uri}}
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

يمكنك أيضًا تمرير عنوان URL لصورة يمكن الوصول إليها علنًا مباشرة:

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "يرجى وصف هذه الصورة في جملة واحدة."},
                {"type": "image_url", "image_url": {"url": "https://cdn.acedata.cloud/4hfydw.jpg"}}
            ]
        }
    ]
}

💡 image_url تقبل فقط حقل url (يمكن أن تكون القيمة عنوان URL للصورة أو base64 data: URI)، بالإضافة إلى حقل detail الاختياري. لا تقم بتمرير media_type - فهذا خاص بحقل الصورة في Anthropic Claude، ولا ينتمي إلى تنسيق image_url الخاص بـ OpenAI / Gemini.

استجابة متدفقة

تدعم هذه الواجهة أيضًا الاستجابة المتدفقة، مما يكون مفيدًا جدًا لتكامل الويب، حيث يمكن أن يتيح عرض النتائج كلمة بكلمة. إذا كنت ترغب في إرجاع استجابة متدفقة، يمكنك تغيير معلمة stream في رأس الطلب إلى true. التعديل كما هو موضح في الصورة، ولكن يجب أن يحتوي كود الاستدعاء على التغييرات المناسبة لدعم الاستجابة المتدفقة.

بعد تغيير stream إلى true، ستقوم واجهة برمجة التطبيقات بإرجاع بيانات JSON المقابلة سطرًا بسطر، وسنحتاج إلى إجراء التعديلات المناسبة على مستوى الكود للحصول على النتائج سطرًا بسطر. مثال على كود الاستدعاء بلغة بايثون:

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"مرحبًا، ما هو النموذج الذي تستخدمه؟"}],
    "stream": True,
    "stream_options": {"include_usage": True}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

تكون نتيجة الإخراج كما يلي:

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**حدد طبيعتي**\n\nلقد بدأت أفكر. يريد المستخدم معرفة طبيعتي، ويسأل مباشرة \"ما أنت؟\" كانت الخطوة الأولية بسيطة: تحديد الاستفسار. الآن، أتذكر هويتي الأساسية: أنا نموذج لغة كبير. هذه هي الحقيقة الأساسية التي أهدف إلى إيصالها.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**تنقيح ردي**\n\nلقد أضفت المعلومات الأساسية التي تم تدريبي بواسطة Google إلى هوية \"نموذج لغة كبير\" الأساسية. خطوتي التالية هي التفكير في ما يعنيه أن أكون \"نموذج لغة كبير\" فعليًا، حتى أتمكن من شرح قدراتي الأساسية. أركز على تقديم السياق دون الخوض في تفاصيل تقنية محددة أو أسماء نماذج. أريد أن أوصل وظيفتي بطريقة يمكن للمستخدم فهمها بسهولة.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**تأكيد الهوية الأساسية**\n\nأنا الآن أرسخ ردي. يحتاج استفسار المستخدم حول انتمائي للنموذج إلى إجابة مركزة. لقد حددت أن \"تم تدريبي بواسطة Google\" هو أمر أساسي، مما يوفر سياقًا رئيسيًا. أقاوم الرغبة في ذكر أي أسماء نماذج محددة، حيث إنه ليس ذا صلة. الهدف هو تقديم بيان مباشر ودقيق. يظل هدفي هو الرد بوضوح واختصار، متجنبًا المصطلحات التقنية والذهاب مباشرة إلى النقطة ذات الصلة.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "أنا نموذج لغة كبير، تم تدريبي بواسطة Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

يمكنك أن ترى أن الاستجابة تحتوي على العديد من data، وdata داخلها choices هي المحتوى الجديد للإجابة، وهو متوافق مع المحتوى المقدم أعلاه. choices هي المحتوى الجديد للإجابة، يمكنك دمج النتائج في نظامك. في الوقت نفسه، يتم تحديد نهاية الاستجابة المتدفقة بناءً على محتوى data، إذا كانت المحتويات هي [DONE]، فهذا يعني أن إجابة الاستجابة المتدفقة قد انتهت بالكامل. تحتوي نتائج data المعادة على العديد من الحقول، كما هو موضح أدناه:

id،生成此次对话任务的 ID，用于唯一标识此次对话任务。
model ،选择的 Gemini 官网模型。
choices،Gemini 针对提问词给于的回答信息。

JavaScript 也是支持的，比如 Node.js 的流式调用代码如下：

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-2.5-pro",
    messages: [{ role: "user", content: "مرحبًا، ما هو النموذج الذي تستخدمه؟" }],
    stream: true
  })
};

const response = await fetch("https://api.acedata.cloud/gemini/chat/completions", options);
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Java 样例代码：

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "مرحبًا، ما هو النموذج الذي تستخدمه؟")));
jsonObject.put("stream", true);
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(jsonObject.toString(), mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/gemini/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

其他语言可以另外自行改写，原理都是一样的。

多轮对话

إذا كنت ترغب في دمج وظيفة المحادثة متعددة الجولات، تحتاج إلى تحميل عدة أسئلة في حقل messages، أمثلة محددة لعدة أسئلة موضحة في الصورة أدناه:

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"مرحبًا"},{"role":"assistant","content":"مرحبًا! كيف يمكنني مساعدتك اليوم؟"},{"role":"user","content":"ما هو النموذج الذي تستخدمه؟"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

من خلال تحميل عدة أسئلة، يمكنك بسهولة تحقيق محادثة متعددة الجولات، ويمكنك الحصول على إجابة مثل:

{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "أنا نموذج لغوي كبير، تم تدريبي بواسطة Google.",
        "reasoning_content": "حسنًا، إليك كيف سأتعامل مع هذا، أفكر كذكاء اصطناعي متطور:\n\nأولاً، المستخدم يستفسر مباشرة عن هويتي الأساسية: \"ما هو النموذج الذي تستخدمه؟\" هذا سؤال بسيط ومباشر. مهمتي الأساسية هي تقديم معلومات دقيقة ومفيدة، لذا يجب أن أجيب على هذا على الفور.\n\nمن البداية، أعلم الإجابة. أنا *نموذج لغوي كبير*. هذه هي هيكليتي الأساسية ومبدأ عملي. أنا مبني على شبكة واسعة من الاتصالات ومدرب على مجموعة بيانات ضخمة.\n\nثم يجب أن أضيف السياق الضروري. من الضروري أن أقدم مصدر تدريبي. لقد *تم تدريبي* بواسطة Google. هذه هوية رئيسية. توفر للمستخدم معلومات قيمة عن أصلي والتحيزات المحتملة (على الرغم من أنني مدرب لتخفيفها).\n\nالآن يجب أن أبني الرد. هدفي هو أن أكون واقعيًا، مختصرًا، وسهل الفهم.\n\nالرد المركب هو شيء مثل: \"أنا نموذج لغوي كبير، تم تدريبي بواسطة Google.\"\n\nيجب أن أقيم المخرجات: هل تلبي المعايير؟ إنه واضح. يوضح ما أنا عليه، ويشمل قطعة حاسمة من المعلومات حول أصلي، ويتجنب المصطلحات الفنية. لا وعود مضللة.\n\nالتحقق النهائي: هل يجيب فعلاً على السؤال؟ نعم. هل المعلومات صحيحة وصادقة؟ نعم. هل هي مختصرة؟ بالتأكيد. هل النغمة مناسبة لأي مستخدم؟ نعم. وأخيرًا، هذه هي الاستجابة القياسية المعتمدة. ممتاز.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

يمكنك أن ترى أن المعلومات الموجودة في choices تتوافق مع المحتوى الأساسي المستخدم، وهذا يتضمن المحتوى المحدد الذي يقدمه Gemini للرد على عدة محادثات، مما يتيح لك الإجابة على الأسئلة المقابلة بناءً على محتوى المحادثات المتعددة.

نموذج Gemini-3.0 متعدد الوسائط

طلب عينة:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ما هو محتوى الصورة؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

نتيجة العينة:

{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.1-pro-preview",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "هذه صورة نصفية خارجية لامرأة شابة.\n\nإليك الوصف الرئيسي لمحتوى الصورة:\n\n*   **مظهر الشخصية**: الفتاة في الصورة لديها شعر طويل مستقيم وناعم باللون الأسود، وملامح وجهها جميلة، وبشرتها فاتحة. تبتسم بلطف، وتنظر إلى الكاميرا.\n*   **الملابس**: ترتدي بلوزة بأكمام منتفخة بلون البيج الفاتح أو لون المشمش، مع تنورة أو سترة سوداء.\n*   **الإضاءة والجو**: تسلط الشمس من الجهة اليسرى الخلفية، مما يضيء شعرها، ويخلق هالة دافئة باللون الذهبي، مما يضفي جوًا منعشًا وجميلاً.\n*   **الخلفية**: الخلفية مشوشة، ويمكن رؤية أنها في الخارج، مع طريق فارغ خلفها (طريق معبد) وأشجار خضراء على جانب الطريق.\n\nبشكل عام، تعطي هذه الصورة شعورًا بالحنان والشمس وفتاة الجوار."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

بالطبع يمكنك أيضًا إرسال رابط الفيديو، المدخلات المحددة كما يلي:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ما هو محتوى الفيديو؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

نتيجة العينة:

{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.1-pro-preview",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "محتوى هذا الفيديو مليء بالمرح، ويعرض بشكل رئيسي قطة **برتقالية** تجري بثقة على طريق ريفي في وقت الغسق.\n\nالتفاصيل المحددة كما يلي:\n\n1.  **محتوى الصورة**:\n    *   الشخصية الرئيسية هي قطة برتقالية مخططة.\n    *   الخلفية هي لحظة غروب الشمس (أو شروقها)، حيث تكون الإضاءة ذهبية وناعمة. يوجد سياج خشبي وأراضي مفتوحة على جانب الطريق، وفي المسافة يوجد ظل شخص يمشي.\n    *   تم تصوير الكاميرا من زاوية منخفضة، أحيانًا تلتقط القطة وهي تجري نحو الكاميرا، وأحيانًا تلتقطها من الخلف، بالإضافة إلى لقطات قريبة لوجه القطة ونقوشها.\n\n2.  **خصائص الصوت (النقاط الرئيسية)**:\n    *   التعليق الصوتي في الفيديو مميز جدًا. على الرغم من أن الصورة تظهر قطة خفيفة تجري، إلا أن الصوت المصاحب هو **صوت حوافر ثقيلة وإيقاعية** (أو صوت يشبه صوت الخشب/الكعب العالي على الطريق).\n    *   هذا التباين في الصوت مع الصورة يخلق شعورًا من الفكاهة، كما لو أن هذه القطة تعتبر نفسها حصانًا يجري.\n\nبشكل عام، هذا فيديو حيوانات أليفة يستخدم التباين الصوتي والصوري لخلق لحظات لطيفة وضاحكة."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

من الواضح أن نموذج Gemini 3.0 يمكنه دعم الفهم متعدد الوسائط.

نموذج Gemini-3.1 متعدد الوسائط

gemini-3.1-pro-preview هو معرف النموذج الرسمي الحالي لـ Gemini 3.1 Pro، ويدعم المدخلات متعددة الوسائط مثل النصوص والصور والفيديو، وهو مناسب لمهام الاستدلال المعقدة والترميز والفهم. عينة الطلب:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ما هو محتوى الصورة؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

يدعم Gemini 3.1 Pro أيضًا فهم الفيديو:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ما هو محتوى الفيديو؟"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

تنسيق الاستجابة متطابق مع Gemini 3.0 Pro، انظر إلى قسم نموذج Gemini-3.0 متعدد الوسائط أعلاه لمزيد من التفاصيل.

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

400 token_mismatched: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
400 api_not_implemented: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.
429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في جلب البيانات"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الاستنتاج

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

Coding

Gemini Chat Completion API 申请及使用

申请流程

基本使用

图片理解（多模态输入）

استجابة متدفقة

多轮对话

نموذج Gemini-3.0 متعدد الوسائط

نموذج Gemini-3.1 متعدد الوسائط

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

مثال على استجابة الخطأ

الاستنتاج

​申请流程

​基本使用

​图片理解（多模态输入）

​استجابة متدفقة

​多轮对话

​نموذج Gemini-3.0 متعدد الوسائط

​نموذج Gemini-3.1 متعدد الوسائط

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

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

​الاستنتاج

申请流程

基本使用

图片理解（多模态输入）

استجابة متدفقة

多轮对话

نموذج Gemini-3.0 متعدد الوسائط

نموذج Gemini-3.1 متعدد الوسائط

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

مثال على استجابة الخطأ

الاستنتاج