طريقة استخدام Gemini 4 Hydrogen عبر Gemini API (Python وJavaScript وcurl)

خطوة بخطوة: أنشئ مفتاح Gemini API، واستدعِ gemini-4-hydrogen من Python أو JavaScript أو curl، واضبط thinking_level، وأصلح الأخطاء الأكثر شيوعًا.

رسم توضيحي لمحرر أكواد يستدعي نموذج gemini-4-hydrogen مع شريط لمستوى التفكير

أطلقت Google نموذج Gemini 4 Hydrogen في 12 نوفمبر 2026. وهو النموذج السريع والأقل تكلفة في عائلة Gemini 4، وموجَّه إلى مهام البرمجة اليومية وعمل الوكلاء، ويمكنك استخدامه مجانًا ضمن حدود معيّنة. يرافقك هذا الدليل خطوة بخطوة: الحصول على مفتاح API، وإجراء أول استدعاء من Python أو JavaScript أو curl، ورفع مستوى التفكير أو خفضه، وإصلاح الأخطاء الأكثر شيوعًا.

التفاصيل مأخوذة من إعلان Google نفسها ومن توثيق Gemini API، وهي محدَّثة حتى 14 نوفمبر 2026.

ما هو Gemini 4 Hydrogen

  • معرّف النموذج: gemini-4-hydrogen. هذا معرّف ثابت، فلا تحتاج إلى لاحقة تاريخ.
  • نافذة السياق: 1,048,576 رمزًا (token)، أي نحو 1M. وتتقاسم مدخلاتك وتفكير النموذج وإجابته هذه النافذة الواحدة.
  • المخرجات: حتى 65,536 رمزًا في الاستدعاء العادي. أما المخرجات الأطول فتحتاج إلى وضع الخلفية (background mode).
  • المدخلات: نصوص وصور وفيديو وصوت وملفات PDF. ويجيب بالنص فقط.
  • تاريخ انتهاء المعرفة: مارس 2026، بحسب بطاقة النموذج من Google DeepMind.

يسرد توثيق المطورين من Google أسعار فئة Standard التالية:

الفئةالمدخلات، لكل 1M رمزالمخرجات، لكل 1M رمز (تشمل التفكير)
الفئة المجانيةمجاني، مع حدود للمعدلمجاني، مع حدود للمعدل
Standard (مدفوعة)$1.50$7.50
Batch أو Flex$0.75$3.75

السعر ثابت على امتداد نافذة السياق كاملة بحجم 1M، فلا ترتفع تكلفة الرمز الواحد في الموجّهات (prompts) الطويلة. لكن ثمة ملاحظة: في الفئة المجانية قد تستخدم Google موجّهاتك لتحسين منتجاتها. أما في الاستخدام المدفوع فلا تفعل ذلك.

خارج API، يتوفر Hydrogen في قائمة النماذج بتطبيق Gemini وفي Google AI Studio.

ما تحتاج إليه

  • حساب Google.
  • إصدار حديث من Python أو Node.js إن أردت استخدام حزم SDK. ويكفي curl وحده أيضًا.
  • طرفية.

الخطوة 1: أنشئ مفتاح API

  1. افتح صفحة API Keys في Google AI Studio: aistudio.google.com/api-keys.
  2. انقر على Create API key واتبع مربع الحوار. يحصل المستخدمون الجدد على مشروع ومفتاح مجهَّزين تلقائيًا.
  3. انسخ المفتاح.

منذ 28 مايو 2026، صار كل مفتاح جديد يُنشأ في AI Studio مفتاح تفويض (authorization key). وتقصر Google هذه المفاتيح على Gemini API افتراضيًا. وإن كان لديك مفتاح أقدم من نوع “Standard” يحمل وسم Unrestricted، فإن Gemini API يرفضه الآن. لمواصلة استخدامه، مرّر المؤشر فوق وسم Unrestricted، وانقر على Add restrictions، واختر Restrict to Gemini API only، ثم انقر على Restrict key. أو أنشئ مفتاحًا جديدًا ببساطة.

الخطوة 2: احفظ المفتاح كمتغير بيئة

تقرأ حزم SDK الرسمية المفتاح من GEMINI_API_KEY (أو من GOOGLE_API_KEY، وله الأولوية إن ضُبط الاثنان). على macOS أو Linux:

الطرفية
export GEMINI_API_KEY="YOUR_API_KEY"

في PowerShell على Windows:

الكود
$env:GEMINI_API_KEY = "YOUR_API_KEY"

لا تلصق المفتاح أبدًا في كود تودعه في Git. وإن تسرّب مفتاح فقد تحظره Google، وستظهر لك الرسالة “Your API key was reported as leaked.”

الخطوة 3: ثبّت حزمة SDK

Python:

الطرفية
pip install -U google-genai

JavaScript:

الطرفية
npm install @google/genai

الخطوة 4: أجرِ أول استدعاء

يعتمد دليل البدء السريع من Google على Interactions API. وهذه هي الأمثلة الرسمية، مع ضبط النموذج على Hydrogen.

Python (احفظ الملف باسم hello.py، ثم شغّل python hello.py):

الكود
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

JavaScript (احفظ الملف باسم hello.mjs، ثم شغّل node hello.mjs):

الكود
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-4-hydrogen",
  input: "Explain how AI works in a few words",
});
console.log(interaction.output_text);

curl:

الطرفية
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Explain how AI works in a few words"
  }'

الناتج المتوقع: جملة قصيرة أو جملتان عن كيفية تعلّم الذكاء الاصطناعي الأنماط من البيانات. تتغير الصياغة في كل مرة. وإن وصلتك إجابة، فمفتاحك وإعدادك يعملان.

الخطوة 5: تحكّم في عمق تفكيره

“يفكّر” Hydrogen قبل أن يجيب. وتحدد مقدار ذلك عبر thinking_level داخل generation_config. ثمة أربعة مستويات:

المستوىاستخدمه في
lowالمهام السريعة البسيطة التي تكون فيها السرعة والتكلفة أهم ما يعنيك
mediumإعداد وسط
highالإعداد الافتراضي في Hydrogen
xhighتصحيح الأخطاء الصعبة، ومراجعة الكود بعناية، والاستدلال متعدد الخطوات

مثال بلغة Python يطلب أعمق مستوى من التفكير:

الكود
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
    generation_config={
        "thinking_level": "xhigh"
    }
)
print(interaction.output_text)

وفي JavaScript الفكرة نفسها: generation_config: { thinking_level: "xhigh" }.

تُحتسب رموز التفكير في الفوترة كرموز مخرجات. ويمكنك معرفة عدد ما استهلكه الاستدعاء منها عبر interaction.usage.total_thought_tokens. وفي المهام البسيطة الكثيرة العدد، يبقى التحويل إلى low أسهل طريقة لخفض التكلفة وزمن الانتظار.

تريد رؤية استدلاله؟ ملخصات التفكير معطّلة افتراضيًا. أضف "thinking_summaries": "auto" إلى generation_config. عندها يتضمن الرد خطوات thought مع ملخص، تليها خطوة model_output التي تحمل الإجابة. وتجد في دليل التفكير من Google الحلقة الكاملة لقراءتها.

الخطوة 6: الانتقال من Gemini 3.8 Flash أو من نماذج أقدم

إن كان لديك كود يعمل على نموذج أقدم، فملاحظات الترحيل من Google تسرد التغييرات المطلوبة:

  1. غيّر سلسلة اسم النموذج، مثلًا من gemini-3.8-flash إلى gemini-4-hydrogen.
  2. احذف temperature وtop_p وtop_k. يذكر توثيق Google أن القيم الواقعة ضمن النطاق يجري تجاهلها، وأن القيم الخارجة عنه تُرجع خطأ 400.
  3. ارفع حدود max_output_tokens المنخفضة أو احذفها. فالحد يشمل الآن التفكير والإجابة معًا، حتى 65,536.
  4. احذف التخزين المؤقت الصريح (cached_content، caches.create). يدعم Hydrogen التخزين المؤقت التلقائي (الضمني) فقط، وهو يُطبَّق على الموجّهات التي تبلغ 4,096 رمزًا أو أكثر.
  5. توقّع أن تكون القيمة الافتراضية لـ thinking_level هي high لا medium، ولا تستخدم minimal.
  6. صرّح بالأدوات كما ينبغي داخل الطلب، بدل أن تطلب من النموذج كتابة استدعاءات الأدوات كنص عادي.

الأخطاء الشائعة وحلولها

خطأ عند استخدام minimal. لا يقبل Hydrogen القيمة thinking_level: "minimal". استخدم low بدلًا منها.

خطأ 400 بسبب temperature أو top_p. احذف هذين المعاملين. يتحكم Hydrogen في اختيار العيّنات (sampling) بنفسه.

خطأ 401 authentication، أو رفض المفتاح. تأكد من أن GEMINI_API_KEY مضبوط في الطرفية نفسها التي تشغّل فيها السكربت (echo $GEMINI_API_KEY على macOS أو Linux). وإن كان مفتاحًا قديمًا غير مقيَّد، فاقصره على Gemini API أو أنشئ مفتاحًا جديدًا (الخطوة 1).

خطأ 403 permission_denied / FREE_TIER_VERIFICATION_REQUIRED. يحتاج مشروعك إلى التحقق أو إلى إعداد الفوترة في AI Studio قبل أن يتمكن من إجراء الاستدعاءات. ولن تفيد إعادة المحاولة قبل إتمام ذلك.

خطأ 404 model_not_found. راجع طريقة كتابة الاسم: gemini-4-hydrogen، كله بأحرف صغيرة ومع شرطات.

خطأ 429 rate_limit_exceeded أو quota_exceeded. بلغت حدود الفئة المجانية. انتظر ثم أعد المحاولة مع تراجع تدريجي (backoff)، أو فعّل الفوترة. وحزمة Python SDK تعيد المحاولة من تلقاء نفسها بضع مرات عند أخطاء حد المعدل وأخطاء الخادم.

MALFORMED_FUNCTION_CALL. طلبت من النموذج إخراج استدعاءات الأدوات كنص من دون التصريح بأي أدوات. صرّح بدوالّك كأدوات داخل الطلب.

الإجابة تنقطع في منتصف الجملة. قيمة max_output_tokens لديك منخفضة جدًا، لأن التفكير يستهلك جزءًا من الحصة. ارفعها، أو اخفض thinking_level.

الخلاصة

للبدء مع Gemini 4 Hydrogen: أنشئ مفتاحًا في AI Studio، وصدّره باسم GEMINI_API_KEY، وثبّت google-genai أو @google/genai، واستدعِ interactions.create مع model="gemini-4-hydrogen". ثم اضبط thinking_level للموازنة بين الجودة من جهة والسرعة والتكلفة من جهة أخرى. وإن كنت تبني وكلاء، فالعادات نفسها تصلح مع مختلف الأدوات. ويوضح دليلانا إلى مهارات الوكيل في Claude Code وChrome DevTools MCP كيف تمنح وكيل البرمجة قدرات أكثر. وللمقارنة مع أحدث نماذج Anthropic، راجع شرح Claude Fable 5.2.

المصادر

آخر تحقق من الروابط: 15 نوفمبر 2026.

بقلم Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

عن Mindloop Experience

الردود

اكتب ردًّا

المزيد من Mindloop Experience

كل مقالات Mindloop Experience

يمكنك التصفيق حتى 50 مرة.