واجهة Gemini API: كيف تحصل على المفتاح وتستدعي النموذج، وأسعار التوكنات

واجهة Gemini API هي الطريقة لاستدعاء نماذج Gemini من كودك بدلاً من نافذة الدردشة: بوت دعم على موقعك، سكربت يفرز التذاكر، إكمال الكود في المحرر، تكامل مع نظام CRM. الطريق التقليدي يتطلب حساب Google وإعداد الفوترة السحابية وبطاقة أجنبية. على NeuralSpace الطريق أقصر: يُنشأ المفتاح في لوحة الحساب خلال دقيقة، ويُستدعى النموذج بطلب متوافق مع OpenAI، والدفع من رصيد الرموز — دون اشتراك. فيما يلي شرح خطوة بخطوة: كيف تحصل على المفتاح، وكيف يبدو أول استدعاء لـ Gemini 3.8 Flash، وكم تكلّف التوكنات.

ما هي واجهة Gemini API ومن تحتاجها

Gemini هي عائلة نماذج اللغة من Google. عبر الواجهة البرمجية تتاح للمطورين: ترسل مصفوفة رسائل، تستلم رداً مولَّداً وتستخدمه في منتجك — تعرضه للمستخدم أو تخزنه أو تعالجه لاحقاً. الاستخدامات النموذجية: بوتات الدعم، تلخيص البريد والمستندات، استخراج بيانات منظمة من النصوص، صياغة المسودات، أتمتة الروتين في السكربتات. نموذج Gemini 3.8 Flash في كتالوج NeuralSpace هو الفرع السريع من العائلة: توازن بين السرعة والسعر يناسب المحادثات والمعالجة الجماعية للنصوص.

الخطوة 1. احصل على المفتاح

1. سجّل في NeuralSpace بالبريد الإلكتروني — أقل من دقيقة. يُضاف للمستخدمين الجدد رموز ابتدائية فوراً تكفي لأولى الاستدعاءات دون شحن.
2. افتح صفحة مفاتيح API في لوحة الحساب وأنشئ مفتاحاً. يبدو المفتاح هكذا nsk-… ويُعرض مرة واحدة — احفظه فوراً في مدير كلمات مرور أو متغير بيئة، لا في مستودع الكود.
3. تحقق من الرصيد: تتطلب نماذج النص حداً أدنى 50 رمزاً في الحساب. الشحن من لوحة الحساب — دون بطاقات أجنبية ودون رسوم اشتراك.

الخطوة 2. استدعِ النموذج

يعمل Gemini في الواجهة العامة عبر نقطة النهاية المتوافقة مع OpenAI‏ POST /v1/chat/completions: يحمل جسم الطلب النموذج ومصفوفة messages بأدوار system / user / assistant وحد max_tokens. أبسط طلب عبر curl:

curl https://neuralspace.pro/v1/chat/completions \
  -H "Authorization: Bearer nsk-your_key" \
  -H "content-type: application/json" \
  -d '{
    "model": "gemini-3-8-flash",
    "messages": [{"role": "user", "content": "اقترح ثلاثة أسماء لقناة عن الشبكات العصبية"}],
    "max_tokens": 500
  }'

تعود الاستجابة بصيغة OpenAI: النص المولَّد في choices[0].message.content والاستهلاك الفعلي في usage. إذا كان لديك كود جاهز على OpenAI SDK فالتغيير قيمتان فقط — base_url والمفتاح:

from openai import OpenAI

client = OpenAI(
    base_url="https://neuralspace.pro/v1",
    api_key="nsk-your_key",
)

resp = client.chat.completions.create(
    model="gemini-3-8-flash",
    messages=[
        {"role": "system", "content": "أجب عن الأسئلة التقنية بإيجاز."},
        {"role": "user", "content": "ما الفرق بين البث المباشر للاستجابة والاستجابة العادية؟"},
    ],
)
print(resp.choices[0].message.content)

لواجهات الدردشة يفيد البث: أضف "stream": true فيأتي الرد على دفعات عبر Server-Sent Events، فيرى المستخدم الكلمات الأولى قبل اكتمال التوليد.

الخطوة 3. اعرف التكلفة

الفوترة على الأساس الفعلي: توكنات الإدخال (طلبك) والإخراج (رد النموذج) تُحسب منفصلة ولكلٍّ منه سعره لكل مليون. بالنسبة إلى Gemini 3.8 Flash وقت كتابة المقال: 33.5 رمزاً لكل مليون إدخال و168 رمزاً لكل مليون إخراج. طلب نمطي من «2000 توكن سياق + 500 توكن رد» يكلف نحو 0.15 رمز. السعر مرتبط بسعر الصرف ويتغير، لذا راجع الجدول الحي قبل أي حسابات: منشور على صفحة توثيق الواجهة ويعود آلياً من نقطة النهاية GET /v1/models. للمقارنة: DeepSeek V4 Flash في الكتالوج نفسه بسعر 21/42 رمزاً لكل مليون، ونماذج Claude أغلى بوضوح؛ أما Gemini 3.8 Flash فمتوسط السعر مع سرعة عالية في الاستجابة.

حدّان نظاميان: 60 طلباً في الدقيقة لكل مفتاح، وحد أدنى للرصيد 50 رمزاً لنماذج النص. الرصيد الحالي عبر GET /v1/balance، وتظهر الخصومات في سجل المعاملات للملف الشخصي.

Gemini على الموقع — دون كود

إذا لم تكن بحاجة للواجهة البرمجية بعد، فالنماذج نفسها متاحة في الواجهة: اختر Gemini 3.8 Flash في الدردشة — حيث البحث في الويب مفعّل — وفي قسم توليد الصور ستجد Nano Banana، نموذجاً مبنياً على Gemini 2.5 Flash. الرصيد مشترك: الدردشة والواجهة من الحساب نفسه.

أخطاء شائعة في أولى الاستدعاءات

• 401 Unauthorized — المفتاح مُمرِّر بشكل خاطئ: مسافة زائدة أو قيمة مقطوعة أو بادئة غريبة. يمرَّر المفتاح كاملاً بعد Bearer أو في ترويسة x-api-key.
• 429 Too Many Requests — وصلت إلى حد 60 طلباً في الدقيقة. أضف مهلة أو طابوراً في تطبيقك.
• خطأ رصيد — أقل من 50 رمزاً في الحساب: اشحن من لوحة الحساب وأعد المحاولة.
• المفتاح «تسرّب» إلى git — احفظه في متغيرات البيئة (.env) ولا ترفعه في الكوميت؛ عند التسريب أعد إصدار المفتاح من صفحة مفاتيح API نفسها.

أسئلة شائعة

هل أحتاج حساب Google أو بطاقة أجنبية؟

لا. يُصدر المفتاح من لوحة حسابك في NeuralSpace والدفع من رصيد الرموز بنظام الدفع بالرموز، دون اشتراك ودون فوترة سحابية.

كم يكلف استدعاء Gemini API؟

الرموز الفعلية فقط: وقت كتابة المقال 33.5 رمزاً لكل مليون إدخال و168 لكل مليون إخراج لنموذج Gemini 3.8 Flash؛ طلب من بضعة آلاف توكن يكلف نحو 0.15 رمز. الأسعار الحالية في GET /v1/models وجدول التوثيق.

هل توجد خطة مجانية؟

لا توجد توليدات مجانية على المنصة. يحصل المستخدمون الجدد على رموز ابتدائية تكفي للتجارب الأولى، وبعدها الدفع بالرموز دون رسم اشتراك.

ماذا تقدم الواجهة غير النص؟

بالمفتاح نفسه: توليد الصور والفيديو والموسيقى، وتوليد الكلام والتعرف عليه، وخادم MCP على العنوان https://neuralspace.pro/mcp لوكلاء الذكاء الاصطناعي. قائمة نقاط النهاية كاملة في التوثيق.