طلب واستخدام واجهة برمجة تطبيقات Grok Chat Completion

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

عملية الطلب

لاستخدام واجهة برمجة تطبيقات Grok Chat Completion، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. ستتلقى رصيدًا مجانيًا عند الطلب الأول، يمكنك تجربته مجانًا؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في لوحة التحكم.

📘 الوثيقة الكاملة: Grok Chat Completion API →

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

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

عند استخدام هذه الواجهة لأول مرة، نحتاج على الأقل إلى ملء ثلاثة محتويات، أحدها هو 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-4",
  "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، ويمكنك ملاحظة التفاصيل كما هو موضح في الصورة.

يمكنك رؤية أن حقل 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": "ood?"}, "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": " Rea"}, "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": "dy t"}, "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": "o di"}, "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": "ve i"}, "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": "nto "}, "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": "ever"}, "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": "pond"}, "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": "erin"}, "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": "g ab"}, "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": "out "}, "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": "y?"}, "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}} 

البيانات: [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 بسهولة. نأمل أن تساعدك هذه الوثيقة في دمج واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

طلب واستخدام واجهة برمجة تطبيقات Grok Chat Completion

عملية الطلب

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

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

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

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

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

الخاتمة

​عملية الطلب

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

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

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

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

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

​الخاتمة

عملية الطلب

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

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

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

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

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

الخاتمة