كيف تستخدم Grok 4.7 API: دليل خطوة بخطوة باستخدام curl وPython وJavaScript

أنشئ مفتاح xAI API وأرسل أول طلب إلى Grok 4.7، ثم أضف مستوى التفكير والأسئلة المتابِعة والبحث على الويب وتتبّع التكلفة وإرشادات المحتوى.

Graphic of a terminal window sending a request to a cloud and getting a reply, for a guide to the Grok 4.7 API

Grok 4.7 هو أحدث نموذج على xAI API وأقواها، ويمكنك استدعاؤه من الطرفية أو من سكربت قصير خلال دقائق. يرشدك هذا الدليل إلى إنشاء مفتاح، وإرسال أول طلب باستخدام curl وPython وJavaScript، ثم استخدام الميزات التي ستحتاجها بعد ذلك: مستوى التفكير، والأسئلة المتابِعة، والبحث المباشر على الويب، وتتبّع التكلفة، وإرشادات المحتوى الجديدة. تتبع الأوامر التوثيق الرسمي على docs.x.ai، وقد راجعناه في 15 نوفمبر 2026.

أهم النقاط

  • Grok 4.7 هو أقوى نموذج على xAI API، بنافذة سياق تبلغ 500,000 توكن.
  • أنشئ مفتاحًا على console.x.ai، واحفظه باسم XAI_API_KEY، ثم استدعِ Responses API باستخدام curl أو OpenAI SDK.
  • اضبط مستوى التفكير من low إلى xhigh، وتابع المحادثات باستخدام previous_response_id، وأضف أداة web_search للحصول على إجابات محدّثة.
  • تذكر كل استجابة سعرها الدقيق في cost_in_usd_ticks، ويمكن لإرشادات اختيارية أن ترفض محتوى nsfw أو violence أو profanity.

ملاحظة حول الاسم: يسمّي التوثيق الشركة الآن SpaceXSI، لكن الخدمة ما زالت تُسمّى “the xAI API”، والعنوان ما زال api.x.ai، ومتغير المفتاح ما زال XAI_API_KEY.

ما تحتاج إليه

  • حساب على console.x.ai مع رصيد مشحون. يطلب دليل البدء السريع شحن الرصيد قبل استخدام الـ API.
  • طرفية فيها curl. هذا يكفي للدليل كله.
  • اختياري: Python مع pip، أو Node.js مع npm، إذا أردت استدعاء الـ API من الكود.

Grok 4.7 في لمحة

هذه الأرقام مأخوذة من صفحة Grok 4.7 وصفحة الأسعار بتاريخ 15 نوفمبر 2026. الأسعار تتغير، فتحقق منها قبل وضع ميزانيتك.

الخاصيةالقيمة
اسم النموذجgrok-4.7
نافذة السياق500,000 توكن
حدّ المعرفةمايو 2026
المدخلاتنصوص وصور
المخرجاتنص
السعر، للطلبات الأقل من 200 ألف توكن2.00 دولار للمدخلات، و0.50 دولار للمدخلات المخزّنة مؤقتًا، و6.00 دولار للمخرجات لكل مليون توكن
السعر، للطلبات من 200 ألف توكن فأكثر4.00 دولار للمدخلات، و1.00 دولار للمدخلات المخزّنة مؤقتًا، و12.00 دولار للمخرجات لكل مليون توكن
مستوى التفكيرlow أو medium أو high (الافتراضي) أو xhigh

بالأرقام

500,000 توكننافذة السياق

2.00 دولارللمدخلات لكل مليون توكن، أقل من 200 ألف

6.00 دولارللمخرجات لكل مليون توكن، أقل من 200 ألف

الخطوة 1: أنشئ مفتاح API

  1. سجّل الدخول إلى console.x.ai وأضف رصيدًا.
  2. افتح صفحة API Keys وأنشئ مفتاحًا.
  3. احفظه في متغير بيئة حتى لا يظهر أبدًا في الكود:
الطرفية
export XAI_API_KEY="your_api_key"

في Windows PowerShell، استخدم بدلًا من ذلك $env:XAI_API_KEY="your_api_key". تعامل مع المفتاح كما تتعامل مع كلمة المرور، فلا تلصقه في مستندات مشتركة ولا ترفعه إلى مستودع.

الخطوة 2: أرسل أول طلب باستخدام curl

يوصي التوثيق باستخدام Responses API على العنوان https://api.x.ai/v1/responses. هذا هو مثال دليل البدء السريع:

الطرفية
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}"
  }'

النتيجة المتوقعة: كائن JSON. توجد الإجابة داخل قائمة output، في عنصر من النوع message يكون محتواه من النوع output_text. ويحتوي الكائن نفسه على id (ستستخدمه في الخطوة 5) وكتلة usage فيها أعداد التوكنات.

مخطط انسيابي من شحن رصيد xAI وإنشاء مفتاح API حتى قراءة أول استجابة من Grok 4.7

الخطوة 3: استدعِه من Python أو JavaScript

تعمل الـ API مع حزم OpenAI SDK إذا وجّهتها إلى عنوان URL الأساسي الخاص بـ xAI. ثبّت إحداها:

الطرفية
pip install openai
الطرفية
npm install openai

Python:

الكود
import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.7",
    input="Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}",
)

print(response.output_text)

JavaScript (احفظه في ملف .mjs حتى يعمل import وawait في المستوى الأعلى داخل Node.js):

الكود
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',
  input: 'Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}',
});

console.log(response.output_text);

كلاهما يطبع نص النموذج فقط. لدى xAI أيضًا حزمة Python خاصة بها (pip install xai-sdk)، ويقول التوثيق إنه لا بأس بالجمع بين الاثنتين.

الخطوة 4: اختر مقدار تفكير النموذج

يفكّر Grok 4.7 دائمًا قبل أن يجيب. لا يمكنك إيقاف ذلك، لكن دليل التفكير يتيح لك ضبط مقدار الجهد. القيمة الافتراضية هي high. استخدم low للطلبات السريعة والبسيطة، وxhigh لأصعب المسائل حين تكون الإجابة الأبطأ مقبولة.

الطرفية
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.7",
    "reasoning": {"effort": "low"},
    "input": "Summarise the difference between TCP and UDP in three bullet points."
  }'

يسمح الخيار -m 3600 للطلب بالاستمرار حتى ساعة كاملة قبل أن يتوقف curl. يستخدمه التوثيق في أمثلة التفكير لأن التفكير العميق قد يستغرق وقتًا. وفي Python يكون الإعداد نفسه reasoning={"effort": "low"}.

مستويات التفكير في Grok 4.7 من low إلى xhigh، مع تمييز high بوصفه المستوى الافتراضي

الخطوة 5: اطرح سؤالًا متابِعًا دون إعادة إرسال المحادثة

بحسب دليل توليد النصوص، تحفظ Responses API افتراضيًا كل تبادل على خوادم xAI لمدة 30 يومًا. وهذا يتيح لك متابعة المحادثة بتمرير id الخاص بالاستجابة السابقة:

الطرفية
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.7",
    "previous_response_id": "The previous response ID",
    "input": [
        {
            "role": "user",
            "content": "How do stars form?"
        }
    ]
}'

استبدل العنصر النائب بقيمة id من استجابتك السابقة. وإذا كنت تفضّل ألا تُحفظ الطلبات، فأضف "store": false إلى الطلب واحتفظ بالسجل بنفسك.

هل تعلم؟

تحفظ Responses API افتراضيًا كل تبادل على خوادم xAI لمدة 30 يومًا. أضف “store”: false إلى الطلب إذا كنت تفضّل الاحتفاظ بسجل المحادثة بنفسك.

الخطوة 6: دع Grok يبحث على الويب

تقولها صفحة النماذج بوضوح: من دون أدوات البحث، لا يعرف Grok شيئًا يتجاوز بيانات تدريبه. وللحصول على إجابات محدّثة، أضف أداة البحث على الويب:

الطرفية
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": "What were the main technology headlines this week?"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}'

يقرّر Grok بنفسه عدد عمليات البحث. وحتى 15 نوفمبر 2026، تكلّف أداة البحث على الويب 5 دولارات لكل 1,000 استدعاء إضافةً إلى رسوم التوكنات العادية، لذا يكلّف الطلب الذي يحتاج إلى بحث كثير أكثر من الطلب البسيط.

الخطوة 7: اعرف تكلفة كل طلب

تذكر كل استجابة سعرها الدقيق في حقل اسمه cost_in_usd_ticks، وهو موصوف في دليل تتبّع التكلفة. الدولار الأمريكي الواحد يساوي 10,000,000,000 tick. إذا كان jq مثبتًا لديك، فهذا الأمر يطبع الرقم لطلب واحد:

الطرفية
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Say hello"
  }' | jq '.usage.cost_in_usd_ticks'

اقسم النتيجة على 10,000,000,000 لتحصل على المبلغ بالدولار. مثال التوثيق نفسه: 37756000 tick تساوي نحو 0.0038 دولار.

هل تعلم؟

تحتسب xAI الطلبات بوحدة tick: الدولار الأمريكي الواحد يساوي 10,000,000,000 tick. ومثال التوثيق البالغ 37756000 tick يعادل نحو 0.0038 دولار.

الخطوة 8 (اختيارية): أضف إرشادات المحتوى

في أكتوبر 2026 أضافت xAI أدوات إشراف مخصّصة. ترفق قائمة guidelines بالطلب، فيرفض Grok هذا النوع من المحتوى أثناء الكتابة. هناك ثلاث فئات هي nsfw وviolence وprofanity، والسلوك الوحيد المتاح اليوم هو decline.

الطرفية
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Write a short story about a knight.",
    "guidelines": [
      { "type": "policy", "category": "violence", "behavior": "decline" },
      { "type": "policy", "category": "nsfw", "behavior": "decline" }
    ]
  }'

لا تنطبق الإرشادات إلا على الطلب الذي يحملها، لذا أرسلها في كل مرة. ومع OpenAI Python SDK، مرّر القائمة داخل extra_body، لأن هذه الحزمة لا تحتوي على معامل guidelines خاص بها.

الأخطاء الشائعة وحلولها

رموز الحالة أدناه مأخوذة من صفحة تصحيح الأخطاء لدى xAI ومن الأدلة المذكورة أعلاه.

ما تراهالسبب المحتملالحل
401 Unauthorizedلا توجد ترويسة تفويض، أو المفتاح غير صالحأرسل Authorization: Bearer <your key>، وتأكد من ضبط المتغير باستخدام echo $XAI_API_KEY
400 Bad Requestوسيط غير صالح في جسم الطلب أو في عنوان URL، أو مفتاح API غير صحيحراجع الـ JSON وعنوان نقطة النهاية والمفتاح
403 Forbiddenمفتاحك أو فريقك لا يملك الصلاحية، أو أنه محظوراطلب الصلاحية من مسؤول فريقك
404 Not Foundلم يُعثر على النموذج المحدد في الطلب، أو أن عنوان URL مكتوب خطأتحقق من كتابة grok-4.7 ومن عنوان نقطة النهاية
415 Unsupported Media Typeجسم الطلب فارغ، أو ترويسة Content-Type: application/json مفقودةأضف الترويسة وجسم طلب صالحًا
422 Unprocessable Entityأحد الحقول بصيغة غير صالحة، مثل فئة guidelines غير معروفةقارن الحقل بالتوثيق. وفي حالة الإرشادات، تعرض رسالة الخطأ القيم الصالحة
429 Too Many Requestsبلغت حدّ معدل الطلباتأبطئ وأعد المحاولة مع زيادة مدة الانتظار تدريجيًا. ترتفع الحدود تلقائيًا مع إجمالي إنفاق فريقك
خطأ عند ضبط stop أو عقوبة الحضور أو عقوبة التكرارنماذج التفكير لا تقبل هذه المعاملاتاحذفها
تنتهي مهلة الطلباستغرق التفكير وقتًا أطول مما يسمح به العميل لديكارفع مهلة العميل (تستخدم أمثلة التوثيق 3,600 ثانية) أو اخفض مستوى التفكير

إذا فشل كل شيء دفعة واحدة، فراجع status.x.ai قبل أن تبدأ تصحيح كودك.

الخلاصة

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

إذا كنت تقارن بين المزوّدين، فإن دليلنا إلى Gemini 4 Hydrogen API يتبع الخطوات نفسها مع نموذج Google. وإذا كنت تفضّل إبقاء كل شيء على جهازك، فاطّلع على كيفية تشغيل نموذج محليًا باستخدام Ollama. وإذا أردت Grok في مكالماتك بدلًا من كودك، فإليك كيفية إضافة Grok إلى Zoom أو Google Meet أو Teams.

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

كم تكلّف Grok 4.7 API؟

للطلبات الأقل من 200 ألف توكن: 2.00 دولار للمدخلات، و0.50 دولار للمدخلات المخزّنة مؤقتًا، و6.00 دولار للمخرجات لكل مليون توكن. والطلبات من 200 ألف توكن فأكثر تكلّف الضعف. ويضيف البحث على الويب 5 دولارات لكل 1,000 استدعاء. الأسعار بتاريخ 15 نوفمبر 2026.

هل يمكنني استخدام OpenAI SDK مع Grok API؟

نعم. وجّه OpenAI SDK الخاص بـ Python أو JavaScript إلى عنوان URL الأساسي https://api.x.ai/v1 مع XAI_API_KEY الخاص بك، واستدعِ responses.create مع النموذج grok-4.7. لدى xAI أيضًا حزمة xai-sdk الخاصة بها، ويقول التوثيق إنه لا بأس بالجمع بينهما.

لماذا تنتهي مهلة طلبي إلى Grok API؟

يفكّر Grok 4.7 دائمًا قبل أن يجيب، والتفكير العميق قد يستغرق وقتًا. ارفع مهلة العميل (تستخدم أمثلة التوثيق 3,600 ثانية) أو اخفض مستوى التفكير.

هل يمكن إيقاف التفكير في Grok 4.7؟

لا. يفكّر Grok 4.7 دائمًا قبل أن يجيب. يمكنك فقط ضبط مقدار الجهد على low أو medium أو high أو xhigh، والقيمة الافتراضية هي high.

اختبار سريع

ما مستوى التفكير الافتراضي في Grok 4.7؟

  • low (منخفض)
  • medium (متوسط)
  • high (مرتفع)

يحدّد دليل التفكير high بوصفه القيمة الافتراضية.

كم tick يساوي دولارًا أمريكيًا واحدًا؟

  • 10,000,000,000
  • 1,000,000
  • 37,756,000

يقول دليل تتبّع التكلفة إن الدولار الأمريكي الواحد يساوي 10,000,000,000 tick.

ماذا يعني خطأ 401 Unauthorized عادةً؟

  • بلغت حدّ معدل الطلبات
  • ترويسة مفقودة أو مفتاح غير صالح
  • اسم النموذج مكتوب خطأ

تذكر صفحة تصحيح الأخطاء لدى xAI أن السبب هو غياب ترويسة التفويض أو عدم صلاحية المفتاح.

المصادر

آخر تحقق من الروابط في 15 نوفمبر 2026.

بقلم Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

عن Mindloop Experience

الردود

اكتب ردًّا

المزيد من Mindloop Experience

كل مقالات Mindloop Experience

يمكنك التصفيق حتى 50 مرة.