كيفية استخدام واجهة برمجة التطبيقات Gemini 4 Hydrogen API؟

تستخدم واجهة Gemini 4 Hydrogen API مُعرّف النموذج gemini-4-hydrogen. تستدعيه بطلب POST إلى https://generativelanguage.googleapis.com/v1beta/interactions، مع وضع مفتاحك في الترويسة x-goog-api-key، والحقلين model وinput في جسم الطلب بصيغة JSON. يعمل النموذج على الخطة المجانية والخطة المدفوعة (1.50 دولار للمدخلات و7.50 دولار للمخرجات لكل مليون رمز)، ومستوى التفكير الافتراضي له هو high.

يغطي هذا الدليل المسار الكامل: المفتاح، أول طلب، مستوى التفكير، التعامل مع ملف PDF، استدعاء الدوال، البث، ومعالجة الأخطاء. جميع أسماء الحقول مأخوذة من وثائق Google.

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

تحتاج إلى مفتاح Gemini API، ومُعرّف النموذج gemini-4-hydrogen، ونقطة نهاية Interactions. أطلقت Google نموذج Hydrogen في 12 نوفمبر 2026 كنموذج Gemini 4 السريع إلى جانب Carbon وArgon (ما هو Gemini 4 Hydrogen).

تصف وثائق Google واجهة generateContent بأنها قديمة، لذا تستخدم هذه الأمثلة واجهة Interactions.

كيف تحصل على مفتاح Gemini API لنموذج Hydrogen؟

نموذج Hydrogen متاح على الخطة المجانية، لذا يمكنك البدء دون تفعيل الفواتير:

1. افتح صفحة مفاتيح API في Google AI Studio.
2. انقر على Create API key. المفاتيح الجديدة المُنشأة في AI Studio هي مفاتيح تفويض مرتبطة بحساب خدمة.
3. صدّر المفتاح: export GEMINI_API_KEY="YOUR_API_KEY". تقرأ أدوات SDK المتغير GEMINI_API_KEY أو GOOGLE_API_KEY؛ وإذا تم تعيين كليهما، فالأولوية لـ GOOGLE_API_KEY.
4. قد يحتاج مشروع Cloud المُنشأ خارج AI Studio إلى التحقق من المشروع قبل أن تعمل الخطة المجانية.

تنشر Google أرقام الخطة المجانية على صفحة حدود المعدل، لا في دليل الإطلاق. يغطي دليل Gemini 4 Hydrogen المجاني ما تحصل عليه بصفر دولار.

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

أرسل الحقلين model وinput إلى نقطة نهاية Interactions. احفظ اسم النموذج في متغير ليكون تبديل النماذج مجرد تغيير سطر واحد.

export GEMINI_MODEL="gemini-4-hydrogen"

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_MODEL"'",
    "input": "Write a Python function that retries an HTTP call with exponential backoff."
  }'

نفس الطلب باستخدام SDK الخاص ببايثون (pip install -U google-genai):

import os
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model=os.environ.get("GEMINI_MODEL", "gemini-4-hydrogen"),
    input="Write a Python function that retries an HTTP call with exponential backoff.",
)

print(interaction.output_text)
print(interaction.usage)

يتضمن الرد مُعرّفًا id وحالة status ومصفوفة steps. يوجد النص في خطوات model_output، والاستدلال في خطوات thought، ويجمع حقل output_text في الـ SDK النص نيابةً عنك. يحتوي كائن usage على total_input_tokens وtotal_thought_tokens وtotal_output_tokens وtotal_tokens.

تتبع هذه المقتطفات دليل البدء السريع من Google. لم ننفذها عند إعداد هذه المقالة (لا يوجد مفتاح Gemini على جهاز الاختبار لدينا)، لذا تحقق من البنية مقارنةً بأول رد تحصل عليه بنفسك.

كيف تضبط مستوى التفكير في Gemini 4 Hydrogen؟

اضبط thinking_level داخل generation_config. مستوى Hydrogen الافتراضي هو high، ويضيف مستوى جديدًا هو xhigh، ويرفض minimal مع إرجاع خطأ.

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-hydrogen",
    "input": "Audit this payment retry queue for race conditions.",
    "generation_config": {
      "thinking_level": "medium",
      "max_output_tokens": 65536
    }
  }'

هناك قاعدتان مهمتان. الحقل max_output_tokens يحدد سقفًا مشتركًا للتفكير والمخرجات معًا، لذا قد يقطع السقف المنخفض القديم (مثل 8,192) الإجابات قبل اكتمالها؛ وتوصي Google برفعه إلى 65,536 وخفض مستوى التفكير بدلًا من ذلك. وتُحتسب رموز التفكير بسعر المخرجات البالغ 7.50 دولارات، لذا يكلّف xhigh أكثر حتى لو بقي طول الإجابة المرئية كما هو. يعرض تفصيل أسعار Gemini 4 Hydrogen الأرقام لكل مستوى.

تقول Google أيضًا إن الخادم يتجاهل temperature وtop_p وtop_k على Hydrogen، لذا احذفها من طلباتك.

كيف ترسل ملف PDF إلى Gemini 4 Hydrogen؟

أضف عنصر document إلى مصفوفة input، بجانب عنصر text يحتوي على تعليماتك. للملفات الصغيرة، أرسل ملف PDF مضمّنًا بترميز base64:

PDF_PATH="invoice.pdf"
B64=$(base64 < "$PDF_PATH" | tr -d '\n')

curl -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-hydrogen",
    "input": [
      {"type": "document", "data": "'"$B64"'", "mime_type": "application/pdf"},
      {"type": "text", "text": "Extract the line items as a table."}
    ]
  }'

للملفات الأكبر أو لإعادة الاستخدام عبر محادثات متعددة، ارفع الملف مرة واحدة عبر Files API (مجاني، ويُحتفظ بالملف لمدة 48 ساعة) ومرّر بدلًا من ذلك {"type": "document", "uri": "<file uri>", "mime_type": "application/pdf"}. وفقًا لدليل معالجة المستندات، يمكن أن يصل حجم ملفات PDF إلى 50 ميغابايت أو 1,000 صفحة، ويقرأ النموذج الرسوم البيانية والجداول والصور داخلها، وليس النص فقط.

كيف يعمل استدعاء الدوال مع Gemini 4 Hydrogen؟

عرّف دوالك في الحقل tools. لا ينفّذ النموذج شيئًا بنفسه؛ بل يُرجع خطوة function_call، ثم يشغّل كودك الدالة، وتعيد أنت النتيجة في function_result. إليك الخطوة الأولى، من دليل استدعاء الدوال من Google:

curl -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-hydrogen",
    "input": "What'\''s the temperature in London?",
    "tools": [{
      "type": "function",
      "name": "get_current_temperature",
      "description": "Gets the current temperature for a given location.",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city name"}
        },
        "required": ["location"]
      }
    }]
  }'

ابحث عن الخطوة التي تكون فيها type تساوي function_call واقرأ منها name وarguments وid. شغّل دوالك، ثم أعد النتيجة على نفس الجلسة:

fc = next(s for s in interaction.steps if s.type == "function_call")
result = get_current_temperature(**fc.arguments)

final = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[{
        "type": "function_result",
        "name": fc.name,
        "call_id": fc.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
    tools=[weather_function],
    previous_interaction_id=interaction.id,
)
print(final.output_text)

يحفظ الحقل previous_interaction_id حالة المحادثة والتفكير على خوادم Google، فلا تحتاج إلى إعادة إرسال السجل. وتحذير واحد من ملاحظات الترحيل لدى Google: مطالبة النموذج بطباعة "استدعاءات أدوات" بصيغة JSON خام دون تعريف أي أدوات قد تُرجع الخطأ MALFORMED_FUNCTION_CALL. عرّف الأدوات بشكل أصلي أو استخدم المخرجات المهيكلة.

كيف تبث ردود Gemini 4 Hydrogen؟

أضف "stream": true إلى جسم الطلب. تجيب الواجهة بأحداث Server-Sent Events:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Explain idempotency keys in three short paragraphs.",
    "stream": true
  }'

وفقًا لدليل البث من Google، تحصل على interaction.created، ثم step.start وstep.delta وstep.stop لكل خطوة (thought أولاً ثم model_output)، ثم interaction.completed مع usage النهائية. اجمع قيم delta.text من خطوات model_output لبناء الإجابة. البث لا يرفع السقف: كل خطوة تتوقف عند 65,536 رمزًا. للحصول على مخرجات أطول، اضبط "background": true مع max_output_tokens أعلى من 65,536 واستعلم دوريًا عبر GET /v1beta/interactions/{id} حتى تخرج status من in_progress أو queued.

كيف تتعامل مع أخطاء Gemini 4 Hydrogen API؟

تظهر الأخطاء غير المتدفقة كحالة HTTP مع كائن error يحتوي على code وmessage. وفي البث، تحصل على حدث error بنفس الحقول. الأكواد الأكثر شيوعًا، من صفحة أخطاء API لدى Google:

توصي بدليل استكشاف الأخطاء وإصلاحها من Google بإعادة المحاولة فقط للأكواد 429 و408 و5xx، مع تراجع تدريجي أُسّي مع عشوائية (jitter) وسقف لعدد المحاولات، وعدم إعادة المحاولة أبدًا للأكواد 400 و402 و403. كما تعيد حزمة بايثون SDK المحاولة تلقائيًا للأخطاء العابرة حتى أربع مرات.

دع وكيل البرمجة الخاص بك يختبر واجهة Hydrogen API باستخدام Apidog CLI

بدلًا من قراءة JSON بعد كل تعديل على المطالبة أو مستوى التفكير، دع وكيل البرمجة الخاص بك (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

ثم أعطِ وكيلك مطالبة واحدة:

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY and
THINKING (default "low"). 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
"gemini-4-hydrogen", a short prompt and generation_config.thinking_level
{{THINKING}}, and asserts: HTTP 200, status is "completed", steps contains a
non-empty model_output, and usage.total_tokens exists. Run it at low and at high,
then compare usage.total_thought_tokens.

يتحقق الوكيل من كل حمولة مقابل مخططات الـ CLI قبل كتابة أي شيء:

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 "THINKING=low" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "THINKING=high" -r cli,json

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

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

ما هو مُعرّف نموذج Gemini 4 Hydrogen؟ gemini-4-hydrogen. يعمل مع واجهة Interactions API ومع generateContent.

هل واجهة Gemini 4 Hydrogen API مجانية؟ نعم، ضمن حدود معينة. تدرج Google نموذج Hydrogen في الخطة المجانية لواجهة Gemini API وAI Studio، مع حدود لمعدل الطلبات. أما الاستخدام المدفوع فيكلّف 1.50 دولار لكل مليون رمز إدخال و7.50 دولارات لكل مليون رمز إخراج.

كيف أرحّل من Gemini 3.8 Flash؟ غيّر اسم النموذج، وارفع سقوف max_output_tokens المنخفضة، وأزل temperature وtop_p وtop_k والتخزين المؤقت الصريح (cachedContents)، واستبدل مستوى التفكير minimal بـ low أو medium.

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

ما الفرق بين Hydrogen وGemini 4 Argon في الواجهة البرمجية؟ نفس مخطط الطلب. يفترض Hydrogen المستوى high ويضيف xhigh، بينما يفترض Argon المستوى medium. راجع دليل Gemini 4 Argon API ودليل Gemini 4 Carbon API وGemini 4 Hydrogen Orchestrator لمعرفة كيفية دمج النماذج.