كيفية استخدام Grok 4.7 API

لاستدعاء Grok 4.7، أرسل طلب POST إلى https://api.x.ai/v1/responses مع "model": "grok-4.7" ومفتاح xAI الخاص بك كرمز حامل (Bearer token). تبلغ تكلفته 2 دولار لكل مليون رمز إدخال، و0.50 دولار لكل مليون رمز إدخال مخزن مؤقتًا، و6 دولارات لكل مليون رمز إخراج للموجهات التي تقل عن 200,000 رمز، مع نافذة سياق بحجم 500,000 رمز. شحنت SpaceXAI (الشركة التي كانت تُسمى سابقًا xAI) هذا الإصدار في 21 سبتمبر 2026 بنفس سعر Grok 4.6، لذا فإن الترقية لمعظم عمليات التكامل الحالية هي تغيير سطر واحد.

أدناه: الطلب الأول، جهد الاستدلال وتأثيره على فاتورتك، الاستدلال المشفر، التخزين المؤقت، البث، الأدوات، حدود المعدل، وإعداد اختبار قابل لإعادة الاستخدام في Apidog. للحصول على معلومات أساسية حول النموذج، اقرأ ما هو Grok 4.7 وما الذي تغير؛ المرجع الرسمي هو صفحة Grok 4.7 في وثائق xAI.

نظرة سريعة على واجهة برمجة تطبيقات Grok 4.7

الخطوة 1: الحصول على مفتاح وتحميل أرصدة

أنشئ حسابًا على console.x.ai، وقم بتحميل أرصدة إليه (الواجهة البرمجية مسبقة الدفع)، وأنشئ مفتاحًا. يرشدك دليل مفتاح Grok API الخاص بنا عبر شاشات لوحة التحكم. احتفظ بالمفتاح خارج الكود الخاص بك:

export XAI_API_KEY="your-key-here"

الخطوة 2: قم بإجراء طلبك الأول

واجهة برمجة تطبيقات الاستجابات (Responses API) هي نقطة النهاية الأساسية والتي تستخدمها كل الأمثلة في وثائق xAI:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "input": "Review this function for bugs: function median(a){a.sort();return a[a.length/2]}"
  }'

تعمل واجهة برمجة التطبيقات مع OpenAI SDK. وجّه العميل إلى عنوان URL الأساسي لـ xAI واستدعِ responses.create:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.responses.create({
  model: "grok-4.7",
  reasoning: { effort: "medium" },
  input: [
    { role: "system", content: "You are a senior backend reviewer." },
    { role: "user", content: "Find the bug in: function median(a){a.sort();return a[a.length/2]}" },
  ],
});

console.log(response.output_text);

إذا كنت تفضل عميلاً آخر، فإن نفس النموذج هو grok-4.7 في حزمة تطوير البرمجيات Python SDK لـ xAI (xai_sdk)، و xai.responses('grok-4.7') في Vercel AI SDK، و xai/grok-4.7 في LiteLLM. ملاحظتان حول التوافق: تصنف xAI الآن Chat Completions كنقطة نهاية قديمة، وتم إهمال توافقها مع Anthropic SDK بالكامل. يجب أن يستهدف الكود الجديد /v1/responses.

الخطوة 3: اختر مستوى جهد الاستدلال

Grok 4.7 دائمًا ما يستدل. لا يمكنك إيقافه، ولكن يمكنك التحكم في مدى صعوبة تفكيره باستخدام reasoning.effort في واجهة برمجة تطبيقات الاستجابات (Responses API) (وreasoning_effort في xAI SDK): منخفض لاستدعاءات الأدوات الحساسة للكمون، متوسط للتحليل والسياقات الطويلة، مرتفع (الافتراضي) للمشاكل الصعبة متعددة الخطوات، ومرتفع جدًا عندما تكون الجودة أهم من وقت الاستجابة.

هذا الإعداد هو أكبر عامل يؤثر على فاتورتك. تنشر صفحة إصدار SpaceXAI نتائج CursorBench 4.0 لكل مستوى جهد، والتباين واسع:

الانتقال من منخفض إلى مرتفع جدًا يشتري 13.2 نقطة ويكلف حوالي 3.8 ضعفًا لكل مهمة، لأن النموذج يكتب حوالي 4.5 ضعفًا من الرموز الإخراجية. ابدأ من متوسط، وانتقل إلى مستوى أعلى فقط عندما تظهر اختباراتك الخاصة أن الجودة الإضافية مهمة.

قيد آخر: ترفض نماذج الاستدلال presencePenalty و frequencyPenalty و stop. إذا كان غلاف قديم لا يزال يرسل أيًا منها، سيعيد الطلب خطأ.

الخطوة 4: التعامل مع الاستدلال المشفر في الاستدعاءات متعددة الأدوار

هذا هو التغيير السلوكي الأكثر احتمالًا لمفاجأتك. في واجهة برمجة تطبيقات الاستجابات (Responses API)، يعيد grok-4.7 دائمًا reasoning.encrypted_content، حتى عندما لا تطلب قائمة include الخاصة بك ذلك. لا يمكنك قراءة الاستدلال، ولكن يمكنك نقله.

للمحادثات متعددة الأدوار، مرر عناصر الاستدلال من الاستجابة السابقة مرة أخرى دون تغيير في input الطلب التالي. هذا يحافظ على استدلال النموذج سليمًا عبر الأدوار. لا تقم بتحرير أو تقليم أو إعادة ترتيب هذه العناصر. إذا كان الكود الخاص بك يقوم بتصفية مصفوفة output لتقتصر على عناصر message قبل بناء الدور التالي، فإنه سيهمل الآن السياق الذي يتوقع Grok 4.7 استعادته. سلوك Chat Completions لم يتغير.

الخطوة 5: اجعل التخزين المؤقت يعمل لصالحك

يكلف الإدخال المخزن مؤقتًا 0.50 دولار لكل مليون رمز مقابل 2 دولار للإدخال الجديد، بخصم 75%. المشكلة: تحتاج عملية الاستفادة من التخزين المؤقت (cache hit) إلى وصول طلبك إلى خادم يحمل البادئة بالفعل. توصي SpaceXAI “بشدة” بتعيين prompt_cache_key في استدعاءات واجهة برمجة تطبيقات الاستجابات (Responses API) (أو رأس x-grok-conv-id في Chat Completions). يقوم هذا بتوجيه طلبات المحادثة إلى نفس الخادم؛ وبدونه، تحذر xAI، فإنك غالبًا ما تدفع سعر الإدخال الكامل على خادم غير مخزن مؤقتًا.

رتّب الموجه لإعادة الاستخدام: موجه النظام، ومخططات الأدوات، والمستندات المرجعية أولاً، ثم رسالة المستخدم الجديدة أخيرًا. أي شيء يتغير بالقرب من الأعلى يكسر البادئة والخصم معها.

الخطوة 6: بث الاستجابات

أضف "stream": true لتلقي الأحداث المرسلة من الخادم بدلاً من جسم JSON واحد في النهاية. نظرًا لأن الاستدلال يعمل دائمًا، يمكن للنموذج أن يفكر لبعض الوقت قبل أول رمز للإجابة، وقد يبدو الاستدعاء غير المتدفق معلقًا أو يتسبب في مهلة HTTP قصيرة. يبث Grok 4.7 ملخصات الاستدلال، حتى تتمكن من إظهار التقدم أثناء تفكيره.

استدعاءات الدوال هي الاستثناء: وفقًا لوثائق xAI، يصل استدعاء الدالة كاملاً في كتلة واحدة. قم بتحليله عندما تصل تلك الكتلة بدلاً من تجميع الوسائط من الفروقات. يوضح دليلنا حول اختبار واجهات برمجة تطبيقات LLM التي تبث عبر SSE كيفية فحص تسلسل الأحداث الخام في Apidog.

الخطوة 7: إضافة أدوات

يستخدم استدعاء الدالة تنسيق أداة واجهة برمجة تطبيقات الاستجابات (Responses API). أنت تصف الدالة، يعيد Grok عنصر function_call، تقوم بتشغيله، ثم تعيد function_call_output مع call_id المطابق:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "input": [{"role": "user", "content": "Has order 10482 shipped yet?"}],
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the fulfillment status of an order",
      "parameters": {
        "type": "object",
        "properties": { "order_id": {"type": "string"} },
        "required": ["order_id"]
      }
    }]
  }'

النتائج المهيكلة مدعومة أيضًا، لذا يمكنك الاحتفاظ بالإجابة النهائية وفقًا لمخطط JSON.

تعمل الأدوات من جانب الخادم على جانب xAI: {"type": "web_search"}، بحث X، وتنفيذ الكود. يتم تحصيل رسومها بالإضافة إلى الرموز: بحث الويب يكلف 5 دولارات لكل 1000 استدعاء، وبحث X يكلف 5 دولارات لكل 1000 منشور، وتنفيذ الكود يكلف 5 دولارات لكل 1000 استدعاء، لذا فإن الوكيل الذي يبحث في كل دور يدفع هذه الرسوم في كل دور. يقبل بحث الويب allowed_domains و excluded_domains (حتى خمسة لكل منهما). بدون أداة بحث، لا يملك Grok 4.7 بيانات حية؛ تتوقف معرفته عند مايو 2026.

احترس من منحدر التسعير عند 200 ألف

يحتوي جدول الأسعار على صفين لسبب وجيه. بمجرد أن يصل الموجه إلى 200,000 رمز، يتم احتساب رسوم الطلب بالكامل بالسعر الأعلى: 4 دولارات للإدخال، دولار واحد للمخزن مؤقتًا، 12 دولارًا للإخراج. ليست الرموز التي تتجاوز هذا الحد هي فقط التي تكلف أكثر.

يكلف موجه بحجم 190,000 رمز مع إجابة بحجم 4,000 رمز حوالي 0.40 دولار. ويكلف موجه بحجم 210,000 رمز مع نفس الإجابة حوالي 0.89 دولار. ما يقرب من 10% زيادة في الإدخال تزيد الفاتورة بأكثر من الضعف.

احسب الرموز قبل الإرسال، ولخص السجل عندما تقترب المحادثة من الحد، واستخدم ضغط السياق من xAI للحلقات الطويلة للوكلاء. الجزء الرخيص من نافذة الـ 500,000 رمز ينتهي عند 200,000.

حدود المعدل وأخطاء 429

تتغير الحدود بناءً على إنفاقك التراكمي وتطابق حدود Grok 4.6:

تحتسب الرموز المخزنة مؤقتًا ضمن الرموز في الدقيقة. إذا تجاوزت الحد، ستحصل على HTTP 429. أعد المحاولة باستخدام التراجع الأسي (exponential backoff) والارتعاش (jitter) بدلاً من الضغط المستمر على نقطة النهاية؛ يغطي دليلنا لأخطاء تجاوز حد المعدل هذه الأنماط.

الترحيل من Grok 4.6

تحتاج معظم عمليات التكامل إلى تغيير واحد: grok-4.6 يصبح grok-4.7. السعر، نافذة السياق، حدود المعدل، ومستويات الجهد متطابقة. أعد اختبار ثلاثة أشياء قبل نقل حركة مرور الإنتاج:

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

لا يزال دليلنا لواجهة برمجة تطبيقات Grok 4.6 ساريًا لكل ما لم يتغير. ملاحظتان: https://us.api.x.ai/v1 يحافظ على الاستدلال في الولايات المتحدة بزيادة قدرها 10%، و Grok 4.7 Fast (ضعف السعر) متاح فقط في Cursor و Grok Build، وليس في واجهة برمجة التطبيقات العامة.

اختبار واجهة برمجة تطبيقات Grok 4.7 في Apidog

الطلب المحفوظ والقابل للتكرار يتفوق على أمر curl في سجل أوامرك عند مقارنة مستويات الجهد أو التحقق من ترقية.

1. أنشئ بيئة في Apidog مع تعيين base_url إلى https://api.x.ai/v1 وتخزين XAI_API_KEY كمتغير سري. أضف بيئة ثانية لنقطة النهاية الأمريكية إذا كنت بحاجة إليها.
2. احفظ الطلب: POST {{base_url}}/responses مع رأس Authorization: Bearer {{XAI_API_KEY}} وموجهك الحقيقي في الجسم.
3. أضف تأكيدات: الحالة 200، model يساوي grok-4.7، usage موجود، و output يحتوي على عنصر message. هذه تلتقط مفتاحًا خاطئًا، معرف نموذج خاطئ، أو شكل استجابة متغير قبل أن يفعل تطبيقك ذلك.
4. استنسخه لكل مستوى جهد (منخفض، متوسط، مرتفع، مرتفع جدًا) وقم بتشغيل الأربعة كسيناريو اختبار واحد. تحصل على وقت الاستجابة واستخدام الرمز جنبًا إلى جنب لموجهك الخاص، وليس لمقياس أداء.
5. قم بمحاكاة نقطة النهاية بمجرد استقرار شكل الاستجابة، بحيث يستمر العمل على الواجهة الأمامية دون إنفاق أرصدة.

عندما يتم شحن النموذج التالي، قم بتغيير متغير واحد وأعد التشغيل. قم بتنزيل Apidog لإعداده.

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

ما هو معرف نموذج Grok 4.7؟ grok-4.7. على منصات الشركاء يكون spacexai/grok-4.7 (Vercel AI Gateway) و x-ai/grok-4.7 (OpenRouter).

كم تكلف واجهة برمجة تطبيقات Grok 4.7؟ 2 دولار لكل مليون رمز إدخال، و0.50 دولار للمخزن مؤقتًا، و6 دولارات للإخراج للموجهات التي تقل عن 200,000 رمز، وضعف ذلك عند 200,000 فما فوق. لا يوجد خصم على الدفعات لـ 4.7.

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

هل توجد واجهة برمجة تطبيقات Grok 4.7 مجانية؟ تعمل واجهة برمجة تطبيقات xAI على أرصدة مدفوعة مسبقًا. يغطي دليلنا حول كيفية استخدام Grok 4.7 مجانًا الطرق المجانية المتاحة.

كيف يقارن Grok 4.7 بـ GPT-6 Sol و Claude Opus 5.5؟ لديه أقل سعر إخراج من بين الثلاثة ويتأخر عن Opus 5.5 في معايير الترميز التي يقدمها كلا البائعين. يحتوي المقارنة الثلاثية على الأرقام.

ابدأ بطلب واحد محفوظ

أرسل طلب curl أعلاه، ثم احفظه في Apidog مع تأكيدات وسيناريو مستوى الجهد. تحصل على تكلفة أساسية لكل مهمة على موجهاتك الخاصة قبل نقل حركة المرور. لاختيار مستوى جهد افتراضي، اقرأ تحليل معايير Grok 4.7 لاحقًا.