كيفية الحصول على مفتاح API لـ Grok وإجراء أول استدعاء (Grok 4.6)

مفتاح API الخاص بـ Grok هو بيانات الاعتماد التي تصدرها xAI من وحدة تحكم المطورين الخاصة بها حتى يتمكن الكود الخاص بك من استدعاء نماذج Grok عبر HTTPS. تقوم بإنشائه مرة واحدة، وترسله كرمز مميز (Bearer token) في كل طلب، وتقوم xAI بفوترة الرموز المميزة التي تستخدمها مقابل أرصدة فريقك المدفوعة مسبقًا. إذا كان المفهوم جديدًا، فإن ما هو مفتاح API يغطي الأساسيات؛ وهذا الدليل مخصص للمطورين الذين يرغبون في تشغيل المفتاح اليوم.

إليك التسلسل: أنشئ المفتاح على console.x.ai، قم بإجراء طلب واحد باستخدام curl وآخر باستخدام Python، ثم انقل المفتاح إلى Apidog لتتمكن من تخزينه بأمان، وإرسال الطلبات دون لصقه في سطر الأوامر، وتحويل هذا الطلب الأول إلى اختبار محفوظ. النموذج الرئيسي الحالي هو grok-4.6، وكل مثال أدناه يستخدمه.

زر

ما تحتاجه قبل أن تبدأ

حساب xAI. سجل الآن على console.x.ai.

أرصدة في الحساب. تعمل وحدة التحكم على الأرصدة المدفوعة مسبقًا، ودليل البدء السريع الرسمي يخبرك بتحميل الأرصدة فور التسجيل. مع رصيد صفري، يتم رفض الطلبات.
curl (يأتي مع macOS ومعظم توزيعات Linux) و Python 3.9 أو أحدث مع pip.
Apidog إذا كنت تريد حفظ الطلب واختباره ومشاركته. تغطي الخطة المجانية 4 مستخدمين، وهو ما يكفي لفريق صغير. قم بتنزيل Apidog قبل الخطوة 4.

الخطوة 1: إنشاء المفتاح في وحدة تحكم xAI

سجل الدخول وافتح الفواتير (Billing). تحت إدارة إنفاق API، اشترِ أرصدة بالبطاقة (تصل فورًا) أو بالتحويل البنكي (يومان إلى ثلاثة أيام عمل، حسب وثائق الفواتير).
افتح صفحة مفاتيح API. يربط دليل البدء السريع بها على console.x.ai/team/default/api-keys. الجزء الخاص بـ team مهم: المفاتيح تنتمي إلى فريق، وليس لتسجيل دخولك الشخصي.
انقر على "إنشاء مفتاح API" (Create API key) وأعطه اسمًا يمكنك التعرف عليه بعد ستة أشهر. "apidog-local-dev" أفضل من "key1".
انسخ المفتاح فور إنشائه. اعتبر هذه هي المرة الوحيدة التي سترى فيها القيمة الكاملة.
قم بتخزينه كمتغير بيئة بدلاً من تخزينه في الكود:

export XAI_API_KEY="ضع-مفتاحك-هنا"

XAI_API_KEY هو اسم المتغير الذي تستخدمه الوثائق الرسمية، لذا فإن حزمة تطوير البرمجيات (SDK) الخاصة بـ xAI ومعظم التكاملات المجتمعية تلتقطه دون تهيئة إضافية.

مفتاح واحد لكل بيئة هو عادة جيدة. وجود مفاتيح منفصلة للتطوير المحلي، والتكامل المستمر (CI)، والإنتاج يعني أنه يمكن حذف مفتاح مسرب من جهاز كمبيوتر محمول دون التأثير على أي شيء آخر.

الخطوة 2: إجراء مكالمتك الأولى باستخدام curl

نقطة نهاية النص الأساسية لـ xAI هي POST https://api.x.ai/v1/responses. أرسل المفتاح في ترويسة Authorization، وبيانات JSON في الجسم، ومعرف النموذج في حقل model:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "instructions": "أنت مهندس خلفية كبير. أجب في ثلاث جمل.",
    "input": "واجهة برمجة التطبيقات الخاصة بي ترجع 429 لعميل يعيد المحاولة فورًا. ماذا يجب أن يغير العميل؟"
  }'

الاستجابة الناجحة تكون بتنسيق JSON مع مصفوفة output. يوجد النص في output[].content[].text مع "type": "output_text"، ويبلغ كائن usage عن input_tokens، وoutput_tokens، وtotal_tokens، بالإضافة إلى تفصيلات لرموز الاستدلال (reasoning) والرموز المخزنة مؤقتًا (cached tokens). هذه الأرقام الاستخدام هي ما يتم محاسبتك عليه، لذا قم بتسجيلها من اليوم الأول.

تفصيلان يستحقان المعرفة:

instructions هي المطالبة النظامية. يمكنك أيضًا تمرير input كمصفوفة من رسائل {role, content} إذا كنت تفضل شكل الدردشة.
إذا كان لديك كود موجود بنمط OpenAI، فإن POST https://api.x.ai/v1/chat/completions لا يزال يعمل بنفس المفتاح ومعرف النموذج. تصنفه xAI على أنه نقطة نهاية قديمة وتقوم بشحن الميزات الجديدة إلى Responses أولاً، لذا ابدأ المشاريع الجديدة على /v1/responses.

للبث (streaming)، واستدعاءات الأدوات (tool calls)، وإدخال الصور (image input) على نفس نقطة النهاية هذه، راجع كيفية استخدام Grok 4.6 API.

الخطوة 3: نفس الاستدعاء من Python

واجهة برمجة تطبيقات REST الخاصة بـ xAI متوافقة مع OpenAI SDK، لذا لا تحتاج إلى مكتبة عميل جديدة. وجه base_url إلى xAI واقرأ المفتاح من بيئة التشغيل:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.6",
    instructions="أنت مهندس خلفية كبير. أجب في ثلاث جمل.",
    input="واجهة برمجة التطبيقات الخاصة بي ترجع 429 لعميل يعيد المحاولة فورًا. ماذا يجب أن يغير العميل؟",
)

print(response.output_text)
print(response.usage.input_tokens, response.usage.output_tokens)

قم بتثبيت SDK باستخدام pip install openai. قراءة os.environ["XAI_API_KEY"] تثير KeyError واضحًا إذا كان المتغير مفقودًا، وهو أفضل من إرسال ترويسة Bearer فارغة وتصحيح خطأ 401.

تنشر xAI أيضًا حزمة SDK Python أصلية (xai-sdk) مع نقل gRPC وميزات إضافية مثل المجموعات (Collections) وواجهة برمجة تطبيقات الصوت (Voice API). لإجراء أول مكالمة، يعد عميل OpenAI هو المسار الأقصر.

الخطوة 4: تخزين واختبار المفتاح في Apidog

لصق مفتاح في الطرفية يعمل مرة واحدة. مشاركة الطلب مع زميل، أو إعادة تشغيله بعد تحديث النموذج، أو وضعه في CI هو المكان الذي يثبت فيه عميل API قيمته. إليك سير العمل في Apidog.

احفظ المفتاح كقيمة محلية. افتح "البيئات" (Environments)، أنشئ بيئة باسم "xAI"، وأضف متغيرين: baseUrl بالقيمة المشتركة https://api.x.ai/v1، وXAI_API_KEY بقيمة نائبة كقيمته المشتركة ومفتاحك الحقيقي كقيمته المحلية. تتم مزامنة القيم المشتركة مع زملاء الفريق؛ وتبقى القيم المحلية في ذاكرة التخزين المؤقت لعميلك على جهازك ولا تصل أبدًا إلى خوادم Apidog. يُشحن اسم المتغير مع المشروع، بينما لا يتم شحن السر. تغطي بيئات Apidog والمتغيرات السرية الانقسام بين المشترك والمحلي بعمق، بما في ذلك كيفية حقن CI لمفتاحه الخاص.

أرسل الطلب الأول. أنشئ نقطة نهاية جديدة: POST {{baseUrl}}/responses. في علامة تبويب "المصادقة" (Auth) اختر "رمز مميز لحامله" (Bearer Token) وأدخل {{XAI_API_KEY}}. الصق نص JSON من الخطوة 2، حدد بيئة xAI، واضغط على "إرسال" (Send). تعرض لوحة الاستجابة الحالة والتوقيت والنص المحلل، بحيث يمكنك النقر على output وusage بدلاً من قراءة JSON الخام.

احفظه كاختبار. في معالجات ما بعد (Post Processors)، أضف خطوة تأكيد (Assert): رمز الحالة يساوي 200، وفحص JSONPath يتأكد أن $.model يساوي grok-4.6. أضف تأكيدًا ثانيًا بأن $.usage.output_tokens أكبر من 0. احفظ نقطة النهاية، افتح "الاختبارات" (Tests)، أنشئ سيناريو اختبار، واستورد نقطة النهاية إليه. من ثم، بنقرة واحدة يتم إعادة تشغيل الاستدعاء ويخبرك ما إذا كان المفتاح ومعرف النموذج وشكل الاستجابة لا يزال يعمل.

اختياري: محاكاته (mock). احفظ الاستجابة الحقيقية كمثال على نقطة النهاية وقم بالتبديل إلى عنوان URL الوهمي (mock URL) الخاص بـ Apidog. يمكن تشغيل عمل الواجهة الأمامية واختبارات الوحدة مقابل استجابة Grok وهمية دون إنفاق أرصدة أو الوصول إلى حدود المعدل.

الحدود، الأرصدة، والتسعير

الفوترة. الأرصدة مدفوعة مسبقًا لكل فريق. يمكن للتعبئة التلقائية (Auto top-up) شراء المزيد عندما ينخفض رصيدك عن حد تحدده (5 دولارات كحد أدنى لكل تعبئة)، مع سقف شهري وتحذير عند 80% منه. الفوترة الشهرية موجودة ولكنها غير مفعلة افتراضيًا وتتم عبر مبيعات xAI؛ مع حد الفاتورة الافتراضي 0 دولار، يتم رفض الطلبات في اللحظة التي تنفد فيها الأرصدة المدفوعة مسبقًا.

تسعير Grok 4.6 لكل مليون رمز، من صفحة التسعير الرسمية:

حجم المطالبة	الإدخال	الإدخال المخزن مؤقتًا	الإخراج
أقل من 200 ألف رمز	$2.00	$0.50	$6.00
200 ألف رمز أو أكثر	$4.00	$1.00	$12.00

نافذة السياق هي 500 ألف رمز. يتم احتساب الطلب الذي تتجاوز مطالبته حد الـ 200 ألف بسعر أعلى لجميع رموزه، وليس فقط الفائض.

حدود المعدل (Rate limits). تحدد xAI الطلبات في الثانية والرموز في الدقيقة. تعتمد الأرقام على مستواك: خمسة مستويات (0 إلى 4) بالإضافة إلى Enterprise، يتم فتحها تلقائيًا من خلال الإنفاق التراكمي منذ 1 يناير 2026، ولا ينخفض المستوى أبدًا. توجد حدود فريقك الحالية في صفحة النماذج في وحدة التحكم. يتم احتساب كل رمز ضمن TPM، بما في ذلك رموز الاستدلال ورموز المطالبة المخزنة مؤقتًا.

أرصدة مجانية. تصف وثائق xAI نموذجًا مدفوعًا مسبقًا ولا تعلن عن طبقة مجانية دائمة لواجهة برمجة التطبيقات (API). ظهرت أرصدة ترويجية في وحدة التحكم أحيانًا؛ تحقق من صفحة الفواتير الخاصة بك بدلاً من الاعتماد على منشور مدونة.

الأخطاء الشائعة وكيفية إصلاحها

401 غير مصرح به. كان المفتاح مفقودًا، أو مشوهًا، أو محذوفًا. تحقق من أن الترويسة تقرأ Authorization: Bearer <key> بمسافة واحدة، وأن $XAI_API_KEY مضبوط في سطر الأوامر الذي يشغل curl (echo $XAI_API_KEY | wc -c يجب أن يطبع أكثر من 1)، وأن المفتاح لا يزال موجودًا في وحدة التحكم. السطر الجديد الزائد بعد النسخ واللصق هو سبب كلاسيكي.

403 محظور. المفتاح صالح ولكن غير مسموح له بالقيام بما طلبته. الأسباب المحتملة: المفتاح أو الفريق محظور، الأرصدة مستنفدة بحد فاتورة 0 دولار، أو الفريق لا يملك حق الوصول إلى النموذج. تحقق من الفواتير (Billing) أولاً، ثم المفتاح في صفحة مفاتيح API.

429 عدد كبير جدًا من الطلبات. لقد وصلت إلى سقف RPS أو TPM لمستواك. أضف تراجعًا أسيًا مع اهتزاز (jitter)، وحدد التزامن (concurrency)، وقلص حجم المطالبة، وانقل العمليات المجمعة إلى Batch API. إذا كنت تصل إلى السقف طوال اليوم، فالحل هو مستوى الإنفاق، وليس الكود.

400 طلب سيء. عادةً ما يكون معرف نموذج خاطئ (grok-4.6، وليس grok-4-6) أو JSON غير صالح. يحدد نص الخطأ الحقل.

يتوفر شرح مفصل لقراءة هذه الاستجابات، بما في ذلك البث (streaming) وفشل استدعاء الأدوات (tool-call failures)، في كيفية اختبار وتصحيح أخطاء طلبات Grok 4.6 API.

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

هل يوجد مفتاح API مجاني لـ Grok؟

ليس كعرض دائم موثق. تعمل واجهة برمجة التطبيقات على أرصدة مدفوعة مسبقًا، ويخبرك دليل البدء السريع بتحميل الأرصدة قبل المكالمة الأولى. إذا كان هدفك هو تجربة Grok بدلاً من البناء عليه، فإن كيفية استخدام Grok مجانًا تغطي طرق الاستخدام الاستهلاكي التي لا تحتاج إلى مفتاح.

هل يعمل مفتاح API الخاص بـ Grok مع OpenAI SDK؟

نعم. قم بتعيين base_url="https://api.x.ai/v1" ومرر مفتاح xAI الخاص بك كـ api_key. كل من client.responses.create() و client.chat.completions.create() القديم يعملان مع model="grok-4.6".

أي معرف نموذج يجب أن أضعه في الطلبات؟

grok-4.6 للنموذج الرئيسي. الاسم المستعار grok-4.6-latest يتتبع أحدث مراجعة. لا تزال المعرفات القديمة مثل grok-4.5 و grok-4.3 مدرجة بتسعيرها الخاص، ولكن يجب أن يبدأ العمل الجديد على 4.6.

ماذا أفعل إذا تسرب مفتاحي؟

احذفه من صفحة مفاتيح API فورًا، وأنشئ بديلاً، وحدث متغير البيئة في كل مكان يتم استخدامه فيه. ثم ابحث في مستودعاتك وسجلات CI عن القيمة القديمة. في خطة Apidog Enterprise، يقوم Secret Scanner بوضع علامة على المفاتيح الموجودة في الطلبات، والمتغيرات، والسكريبتات، والوثائق، مما يكتشف الحالة التي قام فيها شخص ما بلصق مفتاح في قيمة مشتركة بدلاً من قيمة محلية.

الخطوة التالية

لديك الآن مفتاح API عامل لـ Grok، واستدعاء ناجح بـ curl و Python، والطلب محفوظ في Apidog كاختبار قابل للتكرار. وجه هذا الاختبار إلى مطالباتك الحقيقية، راقب أرقام usage، وستعرف إنفاقك وحدود معدل استهلاكك قبل أن يفعل ذلك حركة المرور الإنتاجية.