> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Kimi Chat Completion API 申请及使用 > Kimi API guide - Ace Data Cloud Kimi هو سلسلة نماذج الذكاء الاصطناعي التي أطلقتها "الوجه المظلم للقمر". النموذج الموصى به حاليًا هو `kimi-k3` الموجه للبرمجة طويلة المدى، والوكيل، والاستدلال المعقد، وأعمال المعرفة، ويمكن استدعاؤه من خلال واجهة برمجة التطبيقات المتوافقة مع OpenAI Chat Completions. تتناول هذه الوثيقة بشكل أساسي عملية استخدام واجهة برمجة تطبيقات Kimi Chat Completion، مما يتيح لنا استخدام وظيفة المحادثة الرسمية لـ Kimi بسهولة. \##申请流程 لاستخدام واجهة برمجة تطبيقات Kimi Chat Completion، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/5hmkdg.jpg) إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. **يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته مجانًا؛ عند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin). > 📘 الوثيقة الكاملة: [Kimi Chat Completion API →](https://platform.acedata.cloud/documents/kimi-chat-completions) ## 基本使用 يمكنك بعد ذلك ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

عند استخدام هذه الواجهة لأول مرة، تحتاج على الأقل إلى ملء ثلاثة محتويات: `authorization` يمكن اختياره مباشرة من القائمة المنسدلة؛ `model` لاختيار نموذج Kimi، يوصى باستخدام `kimi-k3`؛ `messages` هو مصفوفة رسائل المحادثة، تحتوي كل رسالة على `role` و `content`، حيث يدعم `role` القيم `user`، `assistant`، `system` و `tool`. يمكنك أيضًا ملاحظة أن هناك رمز استدعاء مطابق على الجانب الأيمن، يمكنك نسخ الرمز وتشغيله مباشرة، أو يمكنك النقر مباشرة على زر "Try" للاختبار.

فيما يلي استجابة K3 الحقيقية التي تم الحصول عليها باستخدام `reasoning_effort: max` (تم حذف الحقول الإضافية غير المستخدمة): ```json theme={null} { "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA", "object": "chat.completion", "created": 1784466588, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 86, "completion_tokens": 206, "total_tokens": 292 } } ``` تتضمن نتيجة العودة عدة حقول، كما هو موضح أدناه: * `id`، معرف المهمة الحوارية التي تم إنشاؤها، يستخدم لتحديد هذه المهمة بشكل فريد. * `model`، النموذج المختار من موقع Kimi الرسمي. * `choices`، معلومات الرد التي قدمها Kimi على السؤال. * `usage`، معلومات إحصائية عن التوكنات المستخدمة في هذه المحادثة. حيث أن `choices` تحتوي على معلومات رد Kimi، وداخلها `choices` هي المعلومات المحددة التي قدمها Kimi، كما هو موضح في الصورة.

يمكنك أن ترى أن حقل `content` داخل `choices` يحتوي على المحتوى المحدد الذي رد به Kimi؛ قد تعيد K3 أيضًا `reasoning_content`، للإشارة إلى عملية الاستدلال. ## K3 推理强度 `kimi-k3` دائمًا ما يكون مفعلًا للاستدلال. يدعم جسم الطلب في المستوى الأعلى حقل `reasoning_effort`، والقيمة الوحيدة المدعومة حاليًا هي `max`؛ عند حذف هذا الحقل، يتم استخدام `max` أيضًا. قد يتم قبول `standard`، `high` أو سلاسل أخرى بشكل غير رسمي من قبل بعض الأنظمة المتوافقة، ولكن لا تضمن تغيير سلوك الاستدلال، لذا لا تعتمد عليها. ```bash theme={null} curl https://api.acedata.cloud/kimi/chat/completions \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "kimi-k3", "messages": [{"role": "user", "content": "审查这段代码并给出修复方案"}], "reasoning_effort": "max" }' ``` عند استخدام OpenAI SDK، يمكنك تمرير هذا الحقل مباشرة: ```python theme={null} response = client.chat.completions.create( model="kimi-k3", messages=[{"role": "user", "content": "设计一个可靠的任务队列"}], reasoning_effort="max", ) ``` في المحادثات متعددة الجولات واستدعاءات الأدوات، يرجى إعادة إرسال الرسالة الكاملة للـ assistant من الجولة السابقة إلى `messages`، بما في ذلك `reasoning_content` و `tool_calls`. ### 官方参考 * [Thinking Effort](https://platform.kimi.ai/docs/guide/use-thinking-effort)：يوضح أن Kimi K3 دائمًا ما يكون مفعلًا للاستدلال، والقيمة الوحيدة المدعومة حاليًا لـ `reasoning_effort` هي `max`. * [Model Parameter Reference](https://platform.kimi.ai/docs/api/models-overview)：يقارن بين معلمات الاستدلال لـ K3 و K2، ونافذة السياق، واختلافات استدعاء الأدوات. * [Create Chat Completion](https://platform.kimi.ai/docs/api/chat)：طلبات واستجابات Moonshot الرسمية لـ Chat Completions وتعريفات حقول OpenAPI. ## 流式响应 تدعم هذه الواجهة أيضًا الاستجابة المتدفقة، وهو أمر مفيد جدًا لتكامل الويب، حيث يمكن أن يتيح للويب عرض النتائج حرفيًا. إذا كنت ترغب في إرجاع الاستجابة بشكل متدفق، يمكنك تغيير معلمة `stream` في رأس الطلب إلى `true`. تعديل كما هو موضح في الصورة، ولكن يجب أن يحتوي رمز الاستدعاء على التغييرات المناسبة لدعم الاستجابة المتدفقة.

بعد تغيير `stream` إلى `true`، ستقوم واجهة برمجة التطبيقات بإرجاع بيانات JSON سطرًا بسطر، وعلى مستوى الكود، نحتاج إلى إجراء التعديلات المناسبة للحصول على النتائج سطرًا بسطر. مثال على كود استدعاء Python: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"user","content":"Hello"}], "reasoning_effort": "max", "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` فيما يلي مقتطف من بداية، واستدلال، ونص، ونهاية، وبيانات الاستخدام من استجابة K3 Max المتدفقة الحقيقية: ```json theme={null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"reasoning_content":"ال"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"مرحبا"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[],"usage":{"prompt_tokens":172,"completion_tokens":168,"total_tokens":340}} data: [DONE] ``` يمكنك أن ترى أن هناك العديد من `data` في الاستجابة، و `data` تحتوي على `choices` التي تمثل أحدث محتوى للإجابة، وهو متوافق مع المحتوى المقدم أعلاه. `choices` هي محتوى الإجابة الجديد، يمكنك دمج النتائج في نظامك. كما أن نهاية الاستجابة المتدفقة تحدد بناءً على محتوى `data`، إذا كان المحتوى هو `[DONE]`، فهذا يعني أن إجابة الاستجابة المتدفقة قد انتهت بالكامل. تحتوي نتائج `data` على عدة حقول، كما هو موضح أدناه: * `id`، معرف فريد لمهمة المحادثة هذه. * `model`، النموذج المختار من موقع Kimi. * `choices`، معلومات الإجابة المقدمة من Kimi بناءً على الكلمات الاستفسارية. JavaScript مدعوم أيضًا، على سبيل المثال، كود الاستدعاء المتدفق لـ Node.js كما يلي: ```javascript theme={null} const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "kimi-k3", "messages": [{"role":"user","content":"مرحبا"}], "stream": true }) }; fetch("https://api.acedata.cloud/kimi/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` مثال على كود Java: ```java theme={null} JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "kimi-k3"); jsonObject.put("messages", [{"role":"user","content":"مرحبا"}]); 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/kimi/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: ```python theme={null} import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"assistant","content":"مرحبا! كيف يمكنني مساعدتك اليوم؟"},{"role":"user","content":"ما هو النموذج الذي تستخدمه؟"}], "reasoning_effort": "max" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` من خلال رفع عدة كلمات استفسارية، يمكنك بسهولة تحقيق محادثات متعددة الجولات. فيما يلي استجابة حقيقية من K3 Max (تم حذف الحقول الإضافية غير المستخدمة): ```json theme={null} { "id": "msg_Rqp8nPGBDHWwBlL4VpxuafOp", "object": "chat.completion", "created": 1784466628, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "أنا كيمي، مساعد ذكي تم تطويره بواسطة Moonshot AI (جانب القمر المظلم). ليس لدي معرف إصدار نموذج عام محدد لأشاركه من هنا." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 134, "completion_tokens": 346, "total_tokens": 480 } } ``` يمكنك أن ترى أن المعلومات الموجودة في `choices` تتوافق مع المحتوى الأساسي المستخدم، وهذا يتضمن ردود Kimi على عدة محادثات، مما يتيح لك الإجابة على الأسئلة بناءً على محتوى المحادثات المتعددة. ## معالجة الأخطاء عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال: * `400 token_mismatched`：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة. * `400 api_not_implemented`：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة. * `401 invalid_token`：غير مصرح به، رمز تفويض غير صالح أو مفقود. * `429 too_many_requests`：عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات. * `500 api_error`：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم. ### مثال على استجابة الخطأ ``` { "success": false, "error": { "code": "api_error", "message": "فشل في جلب البيانات" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## الخاتمة من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات Kimi Chat Completion لتحقيق محادثات عادية، استجابات متدفقة، محادثات متعددة الجولات، وكذلك كيفية التحكم في قوة الاستدلال لـ K3 من خلال `reasoning_effort`.