الانتقال إلى المحتوى الرئيسي
xAI Grok هو نظام محادثة AI قوي للغاية، حيث يمكنه توليد ردود طبيعية وسلسة في غضون ثوانٍ قليلة بمجرد إدخال كلمات التحفيز. يتميز Grok بأسلوبه الفكاهي الفريد وقدرته على الحصول على معلومات من الإنترنت في الوقت الفعلي، مما يجعله متميزًا في الصناعة. اليوم، بدأ Grok يظهر في العديد من المجالات الابتكارية، وتأثيره يتوسع بسرعة. سواء كان ذلك في المحادثات اليومية، الكتابة الإبداعية، أو التحليل الفني، أو تصحيح الأكواد، يمكن لـ Grok تقديم مساعدة ذكية غنية بالبصيرة، مما يوفر دعمًا جديدًا لقرارات المستخدمين وإبداعاتهم. تتناول هذه الوثيقة بشكل رئيسي عملية استخدام واجهة برمجة تطبيقات Grok Chat Completion، مما يتيح لنا استخدام وظيفة المحادثة الرسمية لـ Grok بسهولة.

عملية الطلب

لاستخدام واجهة برمجة تطبيقات Grok Chat Completion، يمكنك أولاً زيارة صفحة Grok Chat Completion API والنقر على زر “Acquire” للحصول على الشهادات المطلوبة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. عند الطلب لأول مرة، ستحصل على حصة مجانية يمكن استخدامها مجانًا.

الاستخدام الأساسي

بعد ذلك، يمكنك ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

عند استخدام هذه الواجهة لأول مرة، نحتاج على الأقل إلى ملء ثلاثة محتويات، أحدها هو authorization، والذي يمكن اختياره مباشرة من القائمة المنسدلة. المعامل الآخر هو model، حيث يمثل model فئة النموذج التي نختار استخدامها من موقع Grok الرسمي، وهنا لدينا 8 نماذج رئيسية، يمكن الاطلاع على التفاصيل في النماذج المقدمة. المعامل الأخير هو messages، حيث أن messages هو مصفوفة كلمات الاستفسار التي ندخلها، وهي مصفوفة تمثل إمكانية تحميل عدة كلمات استفسار في نفس الوقت، حيث تحتوي كل كلمة استفسار على role و content، حيث يمثل role دور المستفسر، وقد قدمنا ثلاثة هويات، وهي user و assistant و system. أما content فهو المحتوى المحدد لاستفسارنا. يمكنك أيضًا ملاحظة وجود كود استدعاء مطابق على الجانب الأيمن، يمكنك نسخ الكود وتشغيله مباشرة، أو يمكنك النقر على زر “Try” للاختبار. المعلمات الاختيارية الشائعة:
  • max_tokens: يحدد الحد الأقصى لعدد الرموز في الرد الواحد.
  • temperature: عشوائية التوليد، بين 0-2، كلما زادت القيمة، زادت العشوائية.
  • n: عدد الردود المرشحة التي يتم توليدها في مرة واحدة.

بعد الاستدعاء، نجد أن النتيجة المرجعة هي كما يلي:
{
  "id": "foaicmpl-13936918-cb99-49e1-b94c-bde98b482ed4",
  "model": "grok-3",
  "object": "chat.completion",
  "created": 1755839683,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Yo! What's up? 😎 Ready to dive into whatever you're pondering about today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 20,
    "total_tokens": 28,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}
تتضمن النتيجة المرجعة عدة حقول، كما هو موضح أدناه:
  • id، معرف المهمة الحوارية التي تم إنشاؤها، يستخدم لتحديد هذه المهمة بشكل فريد.
  • model، النموذج المختار من موقع Grok الرسمي.
  • choices، معلومات الرد التي قدمها Grok لكلمات الاستفسار.
  • usage: معلومات إحصائية حول الرموز المستخدمة في هذه المحادثة.
حيث أن choices تحتوي على معلومات رد Grok، ويمكن ملاحظة أن choices تحتوي على المعلومات المحددة للرد من Grok، كما هو موضح في الصورة.

يمكنك رؤية أن حقل content داخل choices يحتوي على المحتوى المحدد لرد Grok.

الاستجابة المتدفقة

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

بعد تغيير stream إلى true، ستقوم واجهة برمجة التطبيقات بإرجاع بيانات JSON سطرًا بسطر، وعلى مستوى الكود، نحتاج إلى إجراء التعديلات اللازمة للحصول على النتائج سطرًا بسطر. كود استدعاء Python كمثال:
import requests

url = "https://api.acedata.cloud/grok/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
نتيجة الإخراج كما يلي:
data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "Yo, "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "what"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data:
{"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'s g"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "جيد؟"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "حقيقي"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ت"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "أو دي"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "لدي"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "نتو "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ماذا"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "على الإطلاق"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "أنت"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'re "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "رد"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "إيرين"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ج اب"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "خارج "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "اليوم"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "؟"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} 

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}} 

data:
{"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 18, "total_tokens": 26, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}} 

data: [DONE]
يمكنك أن ترى أن الاستجابة تحتوي على العديد من data، وdata تحتوي على choices التي تمثل أحدث محتوى للإجابة، وهو متوافق مع المحتوى المقدم أعلاه. choices هو محتوى الإجابة الجديد، يمكنك دمجه في نظامك بناءً على النتائج. في الوقت نفسه، يتم تحديد نهاية الاستجابة المتدفقة بناءً على محتوى data، إذا كان المحتوى هو [DONE]، فهذا يعني أن إجابة الاستجابة المتدفقة قد انتهت بالكامل. تحتوي نتائج data على عدة حقول، كما هو موضح أدناه:
  • id، معرف المهمة الحوارية التي تم إنشاؤها، يستخدم لتحديد هذه المهمة بشكل فريد.
  • model ، النموذج المختار من موقع Grok الرسمي.
  • choices، معلومات الإجابة التي قدمها Grok بناءً على كلمات السؤال.
JavaScript مدعوم أيضًا، مثل كود الاستدعاء المتدفق لـ Node.js كما يلي:
const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": true
  })
};

fetch("https://api.acedata.cloud/grok/chat/completions", options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
كود مثال بلغة Java:
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "grok-3");
jsonObject.put("messages", [{"role":"user","content":"Hello"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/grok/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())
يمكنك إعادة كتابة الكود بلغات أخرى بنفس المبدأ.

محادثة متعددة الجولات

إذا كنت ترغب في دمج وظيفة المحادثة متعددة الجولات، تحتاج إلى رفع عدة كلمات سؤال في حقل messages، مثال على عدة كلمات سؤال موضحة في الصورة أدناه:

كود مثال لاستدعاء Python:
import requests

url = "https://api.acedata.cloud/grok/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"What model are you?"},{"role":"user","content":"What did I just say?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
من خلال رفع عدة كلمات سؤال، يمكنك بسهولة تحقيق محادثة متعددة الجولات، ويمكنك الحصول على إجابة مثل:
{
  "id": "foaicmpl-984ebc53-76b3-4d33-b0e8-0307ab4965af",
  "model": "grok-3",
  "object": "chat.completion",
  "created": 1755839996,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You said, \"Hello.\""
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 6,
    "total_tokens": 33,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}
يمكنك أن ترى أن المعلومات الموجودة في choices تتوافق مع المحتوى الأساسي المستخدم، وهذا يتضمن محتوى ردود Grok على عدة محادثات، مما يتيح لك الإجابة على الأسئلة بناءً على محتوى المحادثات المتعددة.

معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:
  • 400 token_mismatched:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented:طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token:غير مصرح به، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests:عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error:خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الخاتمة

من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات OpenAI Chat Completion لتحقيق وظيفة المحادثة الخاصة بـ OpenAI ChatGPT بسهولة. نأمل أن تساعدك هذه الوثيقة في دمج واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.