DEV Community

Cover image for كيفية استخدام واجهة Gemini 4 Neon API؟
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

كيفية استخدام واجهة Gemini 4 Neon API؟

دليل واجهة Gemini 4 Neon API: الإعداد، الانتقال، المخرجات الطويلة، والتحكم في التكلفة

تستخدم واجهة Gemini 4 Neon API معرّف النموذج gemini-4-neon. تستدعيها بطلب POST إلى https://generativelanguage.googleapis.com/v1beta/interactions، مع مفتاحك في الترويسة x-goog-api-key، وحقلَي model وinput في جسم طلب JSON. تعمل النموذج على الفئة المدفوعة فقط، بسعر 3 دولارات لكل مليون رمز إدخال و15 دولارًا لكل مليون رمز إخراج، وهو يعتمد افتراضيًا على مستوى التفكير high.

جرّب Apidog اليوم

يغطي هذا الدليل ما يميز Neon: الإعداد المطلوب للفئة المدفوعة، والانتقال من نموذج آخر من عائلة Gemini 4، والمخرجات التي تتجاوز 64 ألف رمز، والدمج بين Neon وHydrogen، وكيفية التحكم في الفاتورة. جميع أسماء الحقول مأخوذة من وثائق Google.

ماذا تحتاج قبل أول استدعاء لواجهة Gemini 4 Neon API؟

تحتاج إلى مفتاح Gemini API مرتبط بمشروع مفعَّل فيه نظام الفوترة، ومعرّف النموذج gemini-4-neon، ونقطة نهاية Interactions. أصدرت Google نموذج Neon في 18 نوفمبر 2026 ليكون النموذج المتوسط في عائلة Gemini 4، بين Hydrogen وCarbon.

العنصر القيمة
معرّف النموذج gemini-4-neon
نقطة النهاية POST /v1beta/interactions على generativelanguage.googleapis.com
ترويسة المصادقة x-goog-api-key: $GEMINI_API_KEY
الواجهات البرمجية Interactions API وgenerateContent
مستويات التفكير low وmedium وhigh (الافتراضي) وxhigh
نافذة السياق 1,048,576 رمزًا، مشتركة بين الإدخال والتفكير والإخراج
الإخراج لكل استدعاء متزامن 65,536 رمزًا
التفكيك الطويل حتى 1,048,576 رمزًا مطروحًا منها حجم الإدخال
الفئة المجانية غير متاح
السعر المدفوع 3.00 دولارات / مليون رمز إدخال، 15.00 دولار / مليون رمز إخراج (شاملًا التفكير)
الإدخال المخزَّن مؤقتًا 0.15 دولار / مليون عبر التخزين المؤقت الضمني

بالنسبة لملفات PDF واستدعاء الدوال والبث المتدفق، تتطابق أشكال الطلبات مع دليل Gemini 4 Hydrogen API لدينا؛ ما عليك سوى تغيير معرّف النموذج.

صورة

كيف تحصل على مفتاح Gemini API يعمل مع Neon؟

النموذج Neon غير متاح على الفئة المجانية، لذا لا يكفي المفتاح وحده؛ يجب أن يكون المشروع المرتبط به مفعَّلًا فيه نظام الفوترة.

  1. افتح صفحة مفاتيح API في Google AI Studio وأنشئ مفتاحًا، أو استخدم مفتاحًا تملكه بالفعل.
  2. تأكد من أن مشروع المفتاح على الفئة المدفوعة. تنص وثائق Google بوضوح: «متاح Neon على الفئة المدفوعة فقط (وليس على الفئة المجانية)».
  3. صدِّر المفتاح: export GEMINI_API_KEY="YOUR_API_KEY". تقرأ حزم Google GenAI SDK المفتاح تلقائيًا.
  4. راجع حدود المعدل للفئة المدفوعة على صفحة حدود المعدل قبل التخطيط لدُفعة كبيرة.

كيف ترسل أول طلب لواجهة Gemini 4 Neon API؟

أرسل model وinput إلى نقطة نهاية Interactions. هذا هو الشكل الوارد في الدليل السريع من Google:

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-neon",
    "input": "Review this Go handler for missing error checks and suggest fixes."
  }'
Enter fullscreen mode Exit fullscreen mode

نفس الاستدعاء باستخدام حزمة Python SDK (pip install -U google-genai):

from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Review this Go handler for missing error checks and suggest fixes.",
)

print(interaction.output_text)
print(interaction.usage)
Enter fullscreen mode Exit fullscreen mode

اقرأ حقل usage في كل استجابة أثناء الاختبار: تُحتسب رموز التفكير بسعر الإخراج البالغ 15 دولارًا، لذا فإن عدد رموز التفكير هو ما يحدد تكلفتك.

تتبع هذه المقتطفات دليل Google. لم نجرّبها عند إعداد هذه التدوينة، لذا تحقق من شكل الاستجابة مقابل أول استدعاء تجريه بنفسك.

ما الذي يتغير عند الانتقال من Hydrogen أو Carbon؟

إذا كنت تستخدم بالفعل نموذجًا آخر من عائلة Gemini 4، فالانتقال إلى Neon لا يتطلب أي تغييرات في مخطط الطلب. غيِّر سلسلة model فقط وتحقق من ثلاثة أمور:

التحقق Neon Hydrogen Carbon وArgon
مستوى التفكير الافتراضي high high medium
أعلى مستوى xhigh xhigh high
الإدخال / الإخراج لكل مليون 3 / 15 دولارات 1.50 / 7.50 دولارات راجع تسعير Carbon

إذا كنت قادمًا من Carbon أو Argon، فإن الانتقال الافتراضي من medium إلى high يعني المزيد من رموز التفكير على نفس الموجّه. حدِّد thinking_level صراحةً إذا كنت تريد السلوك القديم:

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Audit this payment retry queue for race conditions.",
    generation_config={"thinking_level": "medium"},
)
Enter fullscreen mode Exit fullscreen mode

أما إذا كنت قادمًا من Gemini 3.8 Flash أو إصدار أقدم، فالقائمة أطول. وفقًا لقائمة انتقال Google:

  • ارفع حدود الإخراج المنخفضة. يشمل max_output_tokens رموز التفكير والإجابة معًا. احذف الحدود الثابتة مثل 8,192 أو ارفعها إلى 65,536، وخفِّض مستوى التفكير إذا احتجت إلى إنفاق أقل.
  • احذف minimal. يرفض النموذج Neon هذه القيمة ويُرجع خطأ.
  • احذف معاملات أخذ العينات. يتجاهل الخادم القيم في النطاق من temperature وtop_p وtop_k، ويُرجع الخطأ 400 للقيم خارج النطاق.
  • تخلَّ عن التخزين المؤقت الصريح. لا يدعم النموذج Neon cachedContents أو caches.create، لذا احذف حقول cached_content.
  • صرِّح بالأدوات بشكل أصلي. قد يؤدي توجيه النموذج لتوليد استدعاءات أدوات بصيغة JSON خام دون تصريح بالأدوات إلى إرجاع الخطأ MALFORMED_FUNCTION_CALL. استخدم استدعاء الدوال أو المخرجات المهيكلة.

كيف تحصل على أكثر من 64 ألف رمز من النموذج Neon؟

يتوقف الطلب المتزامن عند 65,536 رمزًا، سواء كان ببث متدفق أو بدونه. للحصول على مخرجات أطول، مثل مواصفات انتقال كاملة مع مجموعة اختباراتها، اضبط background على true وارفع max_output_tokens فوق 65,536. يواصل خادم Google عندها التوليد على دفعات من 64 ألف رمز حتى الوصول إلى الحد الذي حددته.

Gemini 4 Neon long decode

ابدأ المهمة واحتفظ بقيمة id الخاصة بها:

export ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-neon",
    "input": "Generate a complete multi-module migration specification and test suite for this service.",
    "background": true,
    "generation_config": {
      "max_output_tokens": 262144,
      "thinking_level": "high"
    }
  }' | jq -r '.id')
Enter fullscreen mode Exit fullscreen mode

ثم استخدم الاستقصاء حتى تنتهي المهمة وادمج النص من كل دفعة (بـ Python، باستخدام ID الذي صدّرته):

import os, time

interaction = client.interactions.get(id=os.environ["ID"])
while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

text = "".join(
    c.text
    for step in interaction.steps if step.type == "model_output"
    for c in step.content if c.type == "text"
)
Enter fullscreen mode Exit fullscreen mode

ثلاث قواعد من دليل Google تمنع حدوث مشكلات هنا:

  1. إذا ضبطت background دون تحديد max_output_tokens، يتوقف الخادم عند 65,536 رمزًا.
  2. يمكن أن يصل الحد الأقصى إلى 1,048,576 مطروحًا منها رموز الإدخال. تنصح Google باستخدام 131,072 أو 262,144 للأعمال الطويلة متعددة الخطوات.
  3. قد تستغرق الموجّهات المعقدة عدة دقائق. استخدم وضع الخلفية، أو اضبط مهلات عميل HTTP على 15 دقيقة على الأقل.

إذا كنت تفضّل عدم تخزين التفاعلات على خوادم Google، فإن دليل التفكيك الطويل يوثّق أيضًا أسلوب المتابعة من جهة العميل في أحدث حزم SDK.

كيف تدمج النموذج Neon مع Hydrogen؟

استخدم Neon للتقدير والحكم، وHydrogen للحجم الكبير. يخطط Neon لسير عمل أو يراجعه، ثم تمرّر id التفاعل الخاص به كقيمة previous_interaction_id إلى استدعاء بنموذج gemini-4-hydrogen ينفذ خطوة واحدة. يعرض دليل مطوّري Cloud من Google هذا النمط:

plan = client.interactions.create(
    model="gemini-4-neon",
    input="Design a 3-step plan to migrate our REST order service to gRPC in Go.",
    store=True,
)

step = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Implement step 1 (.proto service definition) from the plan.",
    previous_interaction_id=plan.id,
)
print(step.output_text)
Enter fullscreen mode Exit fullscreen mode

دمج Neon مع Hydrogen

كل رمز إخراج تكتبه Hydrogen بدلًا من Neon يكلّف نصف السعر. يشرح دليل منسّق Gemini 4 Hydrogen لدينا الحلقة نفسها مع Carbon كمنسّق.

كيف تُبقي تكاليف واجهة Gemini 4 Neon API منخفضة؟

أربع رافعات، مرتّبة حسب ما يحقق عائدًا عادةً:

  1. اختر أدنى مستوى تفكير يجتاز اختباراتك. تنصح Google بتشغيل تقييماتك على المستويات الأربعة جميعها مع قيمة مرتفعة من max_output_tokens، ثم اختيار أدنى thinking_level يستوفي معيار الجودة لديك.
  2. أعد استخدام الموجّهات الطويلة. يعمل التخزين المؤقت الضمني افتراضيًا على الموجّهات التي تبلغ 4,096 رمزًا على الأقل، ويخفض تكلفة الإدخال المخزَّن مؤقتًا بنسبة 95%، من 3.00 إلى 0.15 دولار لكل مليون. ضَع الجزء الطويل والثابت من موجّهك (نص النظام، الوثائق، المخططات) في المقدمة.
  3. سلِّم التنفيذ إلى Hydrogen. راجع نمط الدمج أعلاه.
  4. احسب كل شيء. تُحتسب فاتورة Google على كل رمز يعالجه النموذج، بما في ذلك رموز التفكير والتعليمات الداخلية المضافة عند استخدام الترسيخ (grounding). كما يُحتسب الترسيخ عبر Google Search لكل استعلام على حدة.

تحقق سريع من الواقع: استدعاء بـ 20,000 رمز إدخال و8,000 رمز إخراج (شاملًا التفكير) يكلف 0.06 دولار للإدخال و0.12 دولار للإخراج، أي 0.18 دولار بالسعر المعلن.

دع وكيل البرمجة لديك يقارن بين Neon وHydrogen باستخدام Apidog CLI

هل يستحق Neon ضِعف سعر Hydrogen على موجّهاتك؟ دع وكيل البرمجة لديك (Claude Code أو Codex أو Cursor) يبني حالة اختبار واحدة ويشغّلها على النموذجين باستخدام Apidog CLI.

أجرِ الإعداد مرة واحدة:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted
Enter fullscreen mode Exit fullscreen mode

ثم أعطِ الوكيل موجّهًا واحدًا:

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY,
MODEL (default "gemini-4-hydrogen") and THINKING (default "high"). Add an
endpoint for POST /v1beta/interactions with the x-goog-api-key header from
GEMINI_API_KEY. Create a test case that sends model {{MODEL}}, our code-review
prompt and generation_config.thinking_level {{THINKING}}, and asserts: HTTP 200,
status is "completed", a non-empty model_output step, and usage.total_tokens
exists. Run it for gemini-4-hydrogen and gemini-4-neon, then compare
usage.total_thought_tokens and usage.total_output_tokens.
Enter fullscreen mode Exit fullscreen mode

يقرأ الوكيل مخطط كل حمولة ويتحقق من صحة JSON قبل كتابة أي شيء:

apidog environment create gemini --project <projectId> --base-url https://generativelanguage.googleapis.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-hydrogen" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-neon" -r cli,json
Enter fullscreen mode Exit fullscreen mode

اضرب رموز كل تشغيل في سعر النموذج وستحصل على تكلفة حقيقية لكل مهمة على موجّهك تحديدًا، لا متوسطًا من إعلان الإطلاق. أضف --upload-report لعرض التشغيل في تطبيق Apidog، أو استبدل -r cli,json بـ -r junit لتضمين التحقق نفسه في CI. يعرض دليل Apidog CLI لخطوط CI/CD بنية المسار، ويغطي Apidog CLI في Claude Code إعداد الوكيل. تغطي الخطة المجانية من Apidog حتى 4 مستخدمين.

الأسئلة الشائعة

ما هو معرّف نموذج Gemini 4 Neon؟ gemini-4-neon. ويعمل مع كل من واجهة Interactions API وgenerateContent.

هل واجهة Gemini 4 Neon API مجانية؟ لا. متاح Neon على الفئة المدفوعة من Gemini API فقط، بسعر 3 دولارات لكل مليون رمز إدخال و15 دولارًا لكل مليون رمز إخراج. ويمكن لمشتركي Google AI Pro وUltra تجربته في محادثة AI Studio.

هل يعمل كود Hydrogen لديّ مع Neon؟ نعم. تقول Google إن الانتقال بين نماذج Gemini 4 لا يتطلب أي تغييرات في مخطط الطلب. حدِّث سلسلة model، ثم قرر ما إذا كنت تريد مستوى التفكير الافتراضي high.

ما الحد الأقصى للمخرجات في واجهة Gemini 4 Neon API؟ 65,536 رمزًا لكل طلب متزامن. وبتعيين background على true مع قيمة أعلى من max_output_tokens، يمكن للنموذج Neon توليد ما يصل إلى نافذة 1,048,576 رمزًا مطروحًا منها حجم الإدخال.

هل يدعم Gemini 4 Neon معامل temperature؟ لا. يتجاهل الخادم القيم في النطاق من temperature وtop_p وtop_k، ويُرجع الخطأ 400 للقيم خارج النطاق. استخدم thinking_level للموازنة بين الجودة من جهة والسرعة والتكلفة من جهة أخرى.

هل يدعم النموذج Neon التخزين المؤقت الصريح للسياق؟ لا. احذف cached_content من طلباتك. ويبقى التخزين المؤقت الضمني مطبَّقًا تلقائيًا على الموجّهات التي تبلغ 4,096 رمزًا أو أكثر، بخصم 95% على الإدخال المخزَّن مؤقتًا.

Top comments (0)