Grok API: استدعاء Grok من كودك الخاص

طريقتان لاستخدام Grok برمجياً

يمكن للمطورين استدعاء نماذج Grok بطريقتين رئيسيتين. الأولى هي xAI API، التي تديرها الشركة نفسها (التي تحمل الآن العلامة التجارية SpaceXSI)، باستخدام مفاتيح من console.x.ai. أما الطريقة الثانية فهي عبر موفر نماذج مجمّع (model router) مثل OpenRouter، الذي يتيح نماذج مزودين متعددين تحت مفتاح واحد وفاتورة واحدة. تدعم كلتا الطريقتين الطلبات بصيغة OpenAI Chat Completions، مما يعني أن حزم SDK الرسمية من OpenAI ستعمل بمجرد تغيير العنوان الأساسي (base address) واسم النموذج.

أي مسار تختار؟

• xAI API إذا كنت تريد تجربة جميع ميزات Grok أولاً بأول: القائمة الكاملة للنماذج، وواجهة Responses API، وأدوات البحث على الويب وX من جهة الخادم، وتوليد الصور والفيديو باستخدام Grok Imagine، والصوت، ومهام الدفعات (batch jobs)، وخصومات التخزين المؤقت للأوامر (cached prompts). رابط Base URL هو https://api.x.ai/v1.
• OpenRouter إذا كنت ترغب في التبديل بين Grok ونماذج من شركات أخرى دون الحاجة إلى عقود جديدة، أو إذا كان لديك حساب بالفعل على OpenRouter. رابط Base URL هو https://openrouter.ai/api/v1، مع بادئة x-ai/ لمعرّفات النماذج. خطوات الإعداد متوفرة في دليل تشغيل OpenRouter السريع.

في كلتا الحالتين، احتفظ بالمفتاح دائماً على الخادم أو في متغير بيئة (environment variable). إياك وتضمينه داخل صفحة ويب أو تطبيق جوال، حيث يمكن لأي شخص الاطلاع عليه.

طلبك الأول عبر xAI API

أنشئ مفتاحاً في لوحة التحكم، واحفظه باسم XAI_API_KEY، ثم أرسل طلباً إلى Grok 4.7:

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me three tips for a first marathon."}
    ]
  }'

Python، باستخدام مكتبة OpenAI

import os
from openai import OpenAI

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

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "Is 391 a prime number? Show your check."}],
)
print(answer.choices[0].message.content)

تحدد المعلمة reasoning_effort مدة التفكير التي يقضيها النموذج قبل الرد. يدعم Grok 4.3 الخيارات none وlow وmedium وhigh وxhigh، ويكون افتراضياً على low؛ بينما يدعم Grok 4.7 الخيارات low وmedium وhigh وxhigh، ويكون افتراضياً على high. أما بالنسبة لـ Grok 4.20، فتوفر xAI معرّفين منفصلين: grok-4.20-0309-reasoning وgrok-4.20-0309-non-reasoning.

تنفيذ نفس الأمر عبر OpenRouter

على OpenRouter، ضع المفتاح في متغير OPENROUTER_API_KEY واستخدم معرّفات النماذج التي تبدأ بـ x-ai/. يتحكم OpenRouter في وضع التفكير عبر كائن reasoning. يعمل كود JavaScript هذا على إصدار Node.js 18 أو الأحدث:

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "Rewrite this headline in a calmer tone: PRICES EXPLODE AGAIN" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

لتفعيل تفكير النموذج، أرسل reasoning: { effort: "low" } (أو medium أو high) بدلاً من ذلك. أضف exclude: true إذا كنت تريد من النموذج استخدام التفكير دون إعادته في الرد. اضبط stream: true لاستلام الإجابة أثناء كتابتها بشكل متزامن، مما يمنح تجربة استخدام أسرع بكثير في واجهات الدردشة.

إرسال صورة

تدعم نماذج Grok 4.20 و4.3 و4.7 قراءة الصور. استخدم بنية رسائل OpenAI التي تتضمن قائمة من الأجزاء (parts). تقبل وثائق xAI صور JPEG وPNG بحجم يصل إلى 20 ميجابايت (MiB)؛ وتعمل الروابط العامة أو روابط البيانات بترميز base64 بكفاءة.

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "List the items and the total on this receipt."}
    ]
  }]
}

معرّفات نماذج Grok وأسعارها

هذه هي نماذج النصوص الحالية المدرجة على OpenRouter التابعة لـ SpaceXAI، مع أحجام سياق الذاكرة والأسعار لكل مليون توكن (وفقاً لقائمة أسعار OpenRouter، أكتوبر 2026). تطبق xAI API نفس الأسعار الأساسية للأوامر التي تقل عن 200,000 توكن.

بعض التفاصيل الإضافية من صفحة النماذج والأسعار لدى xAI (قائمة أسعار xAI، أكتوبر 2026):

• الأوامر الطويلة تكلفتها أعلى. بمجرد وصول الأمر إلى 200,000 توكن، يُحاسب الطلب بالكامل بالسعر الأعلى: $4 / $12 لـ Grok 4.7، و$2.50 / $5 لـ Grok 4.3 و4.20.
• المدخلات المخزنة مؤقتاً أرخص: $0.50 لكل مليون لـ Grok 4.7 و$0.20 لـ Grok 4.3 و4.20، وذلك لبادئات الأوامر المكررة.
• معالجة الدفعات (Batch jobs) غير العاجلة تحصل على خصم، كما يدرج OpenRouter أيضاً نموذج x-ai/grok-4.3:batch بسعر $1 / $2.
• يختلف حجم سياق الذاكرة حسب المصدر: يدرج OpenRouter سعة 2,000,000 توكن لـ Grok 4.20، بينما توضح صفحة نماذج xAI الرسمية أنها 1,000,000.

تُحسب توكنات التفكير كمخرجات، لذا قد تبلغ تكلفة الرد الواحد لنماذج التفكير أكثر مما يوحي به سعر التوكن الفردي.

نصائح عملية

• ابدأ بـ Grok 4.20 بدون تفكير (non-reasoning) للمحادثات وإعادة الصياغة واستخراج البيانات؛ فهو سريع واقتصادي. وانتقل إلى Grok 4.3 أو 4.7 عندما تكون الجودة في المهام المعقدة أهم من السرعة.
• تذكر حدود المعرفة الزمنية. يعرف Grok 4.7 الأحداث حتى مايو 2026، بحسب xAI. لأي معلومات أحدث، مرر الحقائق مباشرة في نص الأمر، أو استخدم أدوات البحث على الويب وX من xAI عبر الخادم، والتي تُحسب تكلفتها لكل استدعاء.
• اكتب رسالة نظام (system message) واضحة تحدد الدور والنبرة وصيغة المخرجات المطلوبة، واطلب الرد بصيغة JSON مع مخطط (schema) محدد إذا كان الكود البرمجي سيقوم بمعالجة النتيجة.
• تعامل مع حدود معدل الطلبات (rate limits). أعد المحاولة بعد مهلة قصيرة عند تلقي استجابة برمز 429.
• التزم بالسياسات. تنطبق سياسة الاستخدام المقبول لـ xAI على استخدام الـ API، ويتيح لك حقل safety_identifier تصنيف الطلبات وتتبعها لكل مستخدم نهائي.

عند حدوث أخطاء

• 401 أو 403: المفتاح مفقود، أو تم إلغاؤه، أو تم تحميله في بيئة خاطئة. اطبَع أول بضعة أحرف منه على الخادم للتأكد من وجوده.
• النموذج غير موجود (Model not found): تأكد من البادئة؛ يطلب OpenRouter البادئة x-ai/grok-4.7، بينما تطلب xAI الاسم مباشرة grok-4.7.
• ردود فارغة أو بطيئة للغاية من نموذج التفكير تعني عادةً أنه استنفد ميزانية التوكنات المخصصة للإخراج أثناء التفكير. قلل مستوى التفكير (effort) أو ارفع قيمة max_tokens.
• رفض الصورة: حوّل الصورة إلى صيغة JPEG أو PNG وتأكد من بقائها تحت الحد الأقصى للحجم.

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

هل Grok API متوافق مع OpenAI SDK؟

نعم. وجّه الـ SDK إلى https://api.x.ai/v1 باستخدام مفتاح xAI، أو إلى OpenRouter باستخدام مفتاح OpenRouter، واستخدم معرّف أحد نماذج Grok.

هل تتوفر Grok API مجانية؟

لا تتوفر خطة مجانية دائمة. يتقاضى كل من xAI وOpenRouter مقابلاً لكل توكن، ومع ذلك فإن تكلفة الاختبارات القصيرة منخفضة للغاية.

هل يمكنني توليد الصور باستخدام Grok API؟

نعم، عبر نماذج Grok Imagine من xAI من خلال نقطة نهاية (endpoint) مخصصة للصور. راجع صفحة Grok Imagine لدينا. ميزة الدردشة على موقعنا لا تدعم توليد الصور.

ما هو نموذج Grok الذي يستخدمه Grok.Online؟

توفر الدردشة لدينا نموذج Grok 4.20 مع إيقاف التفكير، وGrok 4.3 بمستوى تفكير منخفض، وGrok 4.7 بما يصل إلى 10 رسائل يومياً، وجميعها تعمل عبر OpenRouter.