واجهة برمجة تطبيقات Gemini 4 Carbon: معرّف النموذج والتسعير وأول طلب لك

اعتبارًا من 11 نوفمبر 2026، تستخدم واجهة Gemini 4 Carbon API من Google مُعرّف النموذج gemini-4-carbon وتكلف 2 دولار لكل مليون رمز إدخال و10 دولارات لكل مليون رمز إخراج حتى 30 نوفمبر 2026، ثم 4 دولارات و20 دولارًا. أتاحت Google النموذج للعموم في 10 نوفمبر 2026، على الفئة المدفوعة من واجهة Gemini API فقط.

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

ما هو مُعرّف نموذج Gemini 4 Carbon؟

مُعرّف نموذج Gemini 4 Carbon هو gemini-4-carbon. تمرّره في حقل model ضمن طلب إلى نقطة نهاية Interactions في واجهة Gemini API، أو عبر حزمة Python أو JavaScript SDK، أو في مطالبة داخل Google AI Studio. تصف Google Carbon على أنه أقوى نماذجها في الاستدلال وتوصي به للمهام الصعبة، بينما يبقى Gemini 4 Argon هو الخيار الافتراضي للعمل اليومي.

لمعرفة المزيد عن النموذج نفسه، ابدأ بـ ما هو Gemini 4 Carbon.

كيف تحصل على مفتاح Gemini API لاستخدام Gemini 4 Carbon؟

لا يعمل Carbon إلا على الفئة المدفوعة، لذا فالمفتاح وحده لا يكفي. تحتاج إلى مفتاح على مشروع مرتبط به حساب Cloud Billing:

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

تغطي مقالة الخيارات المجانية لـ Gemini 4 Carbon المسارات التي لا تحتاج إلى مفتاح API من الأساس.

كيف ترسل أول طلب API إلى Gemini 4 Carbon؟

يستخدم الدليل السريع من Google لنموذج Carbon واجهة Interactions API: طلب POST إلى /v1beta/interactions مع model وinput في جسم الطلب. ضع اسم النموذج في متغير حتى يكون التبديل بين Carbon وArgon لاحقًا مجرد تعديل لسطر واحد.

باستخدام curl:

export GEMINI_MODEL="gemini-4-carbon"

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": "Find the race condition in this retry loop and rewrite the lock safely.",
    "generation_config": {
      "thinking_level": "medium"
    }
  }'

باستخدام Python SDK (pip install -U google-genai):

import os
from google import genai

MODEL = os.environ.get("GEMINI_MODEL", "gemini-4-carbon")

client = genai.Client()  # reads GEMINI_API_KEY from the environment

interaction = client.interactions.create(
    model=MODEL,
    input="Find the race condition in this retry loop and rewrite the lock safely.",
    generation_config={"thinking_level": "medium"},
)

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

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

ثلاثة تفاصيل من ملاحظات الترحيل الخاصة بـ Google توفر عليك جلسة تصحيح أخطاء:

• احذف معاملات أخذ العينات. يتجاهل Carbon المعاملات temperature وtop_p وtop_k، لذا أزلها.
• ارفع مهل انتهاء الانتظار. قد تستغرق المطالبات الصعبة عدة دقائق. تقترح Google التنفيذ في الخلفية أو مهل انتظار HTTP لا تقل عن 15 دقيقة.
• احتفظ بالحالة على الخادم. مرّر previous_interaction_id للمحادثات متعددة الأدوار واستدعاء الدوال بدلًا من إعادة إرسال سجل المحادثة.

هل تستخدم Argon بالفعل؟ يستخدم دليل Gemini 4 Argon API لدينا بنية الطلب نفسها.

كيف تقرأ رموز الاستخدام والتفكير في الاستجابة؟

تُعيد كل تفاعل كائن usage. وهذه الحقول هي التي تهم من حيث التكلفة:

• total_input_tokens: ما أرسلته، بما في ذلك تعليمات النظام وإعلانات الأدوات.
• total_thought_tokens: الرموز التي أنفقها النموذج في التفكير قبل الإجابة.
• total_output_tokens: الإجابة المرئية.
• total_tokens: المجموع.

الحقل الذي يجب الانتباه إليه هو total_thought_tokens. يقول دليل التفكير من Google إن تسعير الاستجابة هو مجموع رموز الإخراج ورموز التفكير، أي أن التفكير يُحاسب بسعر الإخراج البالغ 10 دولارات. تذكر Google أيضًا أن Carbon «ينفق رموز تفكير أكثر» في كل دورة مقارنة بـ Argon لاستكشاف عمله والتحقق منه. في المطالبات الصعبة، قد يشكّل التفكير معظم الفاتورة.

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

• المهام العادية: أبقِ القيمة الافتراضية 65,536.
• التطبيقات ذات الحد الأقل من 32 ألفًا: ارفعها إلى 32,768 على الأقل.
• الاستدلال والبرمجة المعقدان: اضبط background: true وقيمة 131,072 أو 262,144 رمزًا.

مع background: true، تُكمل خوادم Google الاستجابة على دفعات من 64 ألف رمز. تستطلع حالة التفاعل حتى يتغير وضعها من in_progress أو queued، ثم تجمع النص من كل خطوة model_output.

أي مستوى تفكير في Gemini 4 Carbon يجب أن تستخدم؟

مستوى التفكير هو أداة التحكم الرئيسية لديك في الجودة وزمن الاستجابة والتكلفة. وفقًا لتوجيهات Google في دليل التفكير ووثائق Carbon:

توصي Google بتشغيل تقييماتك على المستويات الثلاثة جميعًا والإبقاء على أدناها الذي يحقق معايير الجودة لديك. في Carbon، الفجوة بين low وhigh هي المكان الذي تذهب إليه ميزانيتك.

متى يجب أن تسلّم المهمة إلى Gemini 4 Carbon بدلًا من Argon؟

Google صريحة في هذا الشأن: «يظل Argon الخيار الأمثل لمعظم أعمال هندسة البرمجيات والمعرفة». يتشارك النموذجان نافذة السياق البالغة مليون رمز، والأدوات المدمجة، وسعر الإطلاق نفسه لكل رمز، لذا فإن الفرق يكمن في عدد الرموز الذي ينفقه كل منهما في كل دورة. استخدم Carbon لتصحيح الأخطاء المعقدة وتحليل الأسباب الجذرية، وتصميم البُنى، والتوليف متعدد الوسائط المكثف، والإثباتات، ومراجعات الأمان. واترك Argon للبرمجة التفاعلية، والميزات اليومية، وحلقات الإنتاج السريعة. يتعمق مقارنة Gemini 4 Carbon مقابل Argon لدينا أكثر في هذا الموضوع، وإذا كنت تُوازن بين Carbon وأحدث نموذج من Anthropic، فاطلع على Gemini 4 Carbon مقابل Claude Fable 5.2 ودليل Claude Fable 5.2 API.

كم تكلفة استدعاء واحد عبر Gemini 4 Carbon API؟

تكلف واجهة Gemini 4 Carbon 2 دولار لكل مليون رمز إدخال و10 دولارات لكل مليون رمز إخراج (بما في ذلك التفكير) حتى 30 نوفمبر 2026، ثم 4 دولارات و20 دولارًا، وفقًا لـ Google.

لتقدير ذلك على استدعاء واحد، خذ طلبًا توضيحيًا يضم 2,000 رمز إدخال، و6,000 رمز تفكير، و1,500 رمز إخراج. هذه أرقام افتراضية للشرح وليست قياسًا فعليًا:

• الإدخال: 2,000 × 2 دولار / مليون = 0.004 دولار
• التفكير مع الإخراج: 7,500 × 10 دولارات / مليون = 0.075 دولار
• الإجمالي: حوالي 0.079 دولار اليوم، وحوالي 0.158 دولار اعتبارًا من 1 ديسمبر

يختلف التفكير كثيرًا حسب المطالبة، لذا اقرأ كائن usage الخاص بك. للاطلاع على الحساب الكامل للسعر، والقفزة في ديسمبر، والتكلفة لكل مهمة، راجع تسعير Gemini 4 Carbon.

دع وكيل البرمجة يختبر Carbon 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>, add an endpoint for
POST https://generativelanguage.googleapis.com/v1beta/interactions
with the x-goog-api-key header read from the GEMINI_API_KEY variable in
environment <envId>. Create a test case that sends model "gemini-4-carbon",
a short prompt and thinking_level "low", and asserts: HTTP 200, status is
"completed", usage.total_thought_tokens exists, and usage.total_tokens is
below 20000. Run it and summarize any failures.

يُبقي استخدام low في الاختبار تكلفة كل تشغيل منخفضة. يقرأ الوكيل المخططات، ويتحقق من صحة حمولاته، ويشغّل حالة الاختبار:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog test-case category --project <projectId>
apidog cli-schema get test-case-create
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> -r cli,json

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

إذا أردت أن يجهز الوكيل كل شيء من الصفر، قل له: «اقرأ https://apidog.com/apidog-cli-installation-guide.md وثبّت Apidog CLI».

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

هل واجهة Gemini 4 Carbon API مجانية؟ لا. تقول وثائق Google إن Gemini 4 Carbon غير متاح على الفئة المجانية من واجهة Gemini API. تحتاج إلى مشروع على الفئة المدفوعة مرتبط بحساب Cloud Billing وبأرصدة مدفوعة مسبقًا لا تقل عن 5 دولارات. أما على صعيد المستهلكين، فتعمل Google على طرح Carbon للمشتركين في Google AI Ultra عبر تطبيق Gemini ووضع AI Mode وAntigravity.

هل يتوفر Gemini 4 Carbon على Vertex AI؟ يذكر منشور الإطلاق من Google واجهة Gemini API، وGoogle AI Studio، وAndroid Studio، وGemini for business، وAntigravity، وCodeMender. لا يذكر Vertex AI، لذا تحقق من قائمة نماذج Google Cloud قبل بناء خططك على ذلك.

ما هي نافذة سياق Gemini 4 Carbon؟ 1,048,576 رمزًا، مشتركة بين الإدخال والتفكير والإخراج. تتوقف الاستجابة المتزامنة عند 65,536 رمزًا؛ ومع التنفيذ في الخلفية يمكن أن تمتد الاستجابة حتى مليون رمز ناقص الإدخال الخاص بك.

هل يمكنني استخدام generateContent بدلًا من واجهة Interactions API؟ يستخدم الدليل السريع من Google لنموذج Carbon واجهة Interactions API، وتشير وثائقه إلى واجهة GenerateContent API لمتابعة فك التشفير الطويل من جهة العميل. إذا كان تطبيقك يستخدم generateContent بالفعل، فاختبر تبديل مُعرّف النموذج هناك قبل الترحيل.

كيف أتحول من Gemini 4 Argon إلى Carbon؟ غيّر سلسلة النموذج من gemini-4-argon إلى gemini-4-carbon. تقول Google إنه لا توجد حاجة لأي تغييرات في مخطط الطلب. ارفع قيمة max_output_tokens ومهل انتظار HTTP لديك، لأن Carbon يفكر لفترة أطول، وأبقِ thinking_level على medium ما لم تتطلب المهمة high.