Kimi K3.1 Pro API: نقاط النهاية، استدعاء الأدوات، التخزين المؤقت والأخطاء

يعمل Kimi K3.1 Pro API على https://api.moonshot.ai/v1 مع معرّفات النماذج kimi-k3.1-pro وkimi-k3.1-pro-highspeed. ويدعم ثلاث صيغ اتصال: OpenAI Chat Completions، وResponses API، وAnthropic Messages، لذا تعمل حزم SDK التي تستخدمها بالفعل مع تغيير عنوان URL الأساسي. يُفتح النموذج بعد شحن رصيد بحد أدنى 1 دولار.

هذا هو المرجع لكتابة كود الإنتاج. لأول استدعاء لك، وللبث وإعدادات Codex أو Claude Code، اقرأ كيفية استخدام Kimi K3.1 Pro؛ وللتكاليف، راجع أسعار Kimi K3.1 Pro. المعلومات مأخوذة من دليل البدء السريع لـ K3.1 Pro من Moonshot والمستندات المرتبطة به، مقروءة في 24 أكتوبر 2026.

Kimi K3.1 Pro Responses API وAnthropic API وChat Completions

تتيح Moonshot الوصول إلى K3.1 Pro عبر ثلاث واجهات API. اختر الواجهة التي تتحدثها مكتبة العميل أو الوكيل لديك بالفعل؛ فالنموذج والمفتاح والفوترة واحدة في الثلاث جميعاً.

وهي تختلف في طريقة ضبط مدة صلاحية التخزين المؤقت (TTL) وفي المكان الذي تظهر فيه بيانات الاستخدام (انظر التخزين المؤقت أدناه). قادم من K3؟ لا يزال دليل Kimi K3 API الخاص بنا سارياً؛ فـ K3.1 Pro هو K3 مُدرَّب لاحقاً بنفس سياق الـ 1,048,576 رمزاً.

مفتاح Kimi K3.1 Pro API: فتح الوصول والتحقق منه

تحتاج إلى حساب مشحون بمفتاح من المنتج الصحيح. أربع خطوات:

1. اشحن 1 دولار على الأقل على منصة Kimi API. إن K3.1 Pro نموذج رائد لا يُفتح إلا بعد شحن ناجح.
2. أنشئ مفتاحاً في لوحة مفاتيح API وصدّره باسم MOONSHOT_API_KEY.
3. تأكد من أن النموذج مرئي لذلك المفتاح باستخدام GET /v1/models.
4. استدعِ kimi-k3.1-pro من الكود.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

إذا لم يكن النموذج مدرجاً، فأصلح ذلك أولاً. إن Kimi API وKimi Code وKimi Membership منتجات منفصلة: مفتاح Kimi Code لن يعمل على نقطة نهاية API، والعضوية لا تتحول إلى رصيد في API.

معاملات الطلب المهمة لـ K3.1 Pro

معظم معاملات OpenAI تتصرف كما تتوقع. وهذه هي المعاملات التي تختلف أو التي تفاجئ المستخدمين:

تُحتسب رموز التفكير ضمن استخدامك، لذا استخدم "low" للتصنيف والاستخراج. التفكير المحفوظ (Preserved Thinking) مُفعَّل دائماً، لذا تعود كل رسالة مساعد مع reasoning_content سليماً (دليل نماذج التفكير).

استدعاء الأدوات في Kimi K3.1 Pro: حلقة كاملة بلغة Python

تتبع حلقة الأدوات في بيئة الإنتاج على K3.1 Pro أربع قواعد من مستندات Moonshot:

• افرض استدعاء أداة في الدور الأول باستخدام tool_choice="required"، ثم انتقل إلى "auto".
• أضِف رسالة المساعد كاملة، بما في ذلك reasoning_content وtool_calls.
• أرسل رسالة tool واحدة لكل tool_call_id.
• حدّد سقفاً لعدد الأدوار حتى لا يتمكن نموذج مرتبك من التكرار إلى ما لا نهاية.

import json, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],
                base_url="https://api.moonshot.ai/v1")

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

الخطأ الكلاسيكي هو إضافة msg.content بدلاً من msg، ما يؤدي إلى إسقاط tool_calls وreasoning_content.

استدعاء الأدوات على نطاق واسع باستخدام search_tools

عندما يمتلك وكيلك عشرات أو مئات الأدوات، لا ترسل كل تعريف في كل طلب. ويوصي دليل أفضل ممارسات استدعاء الأدوات في K3 من Moonshot بهذا التسلسل:

1. عرّف دالة search_tools واحدة (ينفذها الخادم الخلفي لديك) إضافة إلى بضع أدوات أساسية.
2. اضبط tool_choice: "required" في الدور الأول حتى يسترجع النموذج المعلومات قبل الإجابة.
3. أدخل تعريفات الأدوات المطابقة عبر رسالة system تتضمن حقل tools.
4. دع النموذج يستدعي الأدوات المُحمَّلة في الأدوار اللاحقة، مع إعادة tool_choice إلى "auto".

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

تستخدم التعريفات المُدخَلة صيغة tools من المستوى الأعلى وتُطبَّق من تلك الرسالة فصاعداً. ولا يحتفظ الخادم بها، لذا أبقِ الرسالة في الطلبات اللاحقة. ولا يؤدي تغيير tool_choice ولا إضافة تعريف إلى كسر ذاكرة البادئة المؤقتة.

مدخلات الصور والفيديو

يقبل K3.1 Pro الصور والفيديو إلى جانب النص ويعيد نصاً. اجعل content مصفوفة من الأجزاء: جزء image_url (يرسل مثال البدء السريع رابط بيانات base64، ويشير إلى أن روابط الصور العامة غير مدعومة) أو جزء video_url يشير إلى ملف مرفوع بمعرّف ms://.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

مرّر content كرسالة المستخدم، واحذف الملف باستخدام client.files.delete(video.id) عند الانتهاء.

التخزين المؤقت للسياق في الكود

التخزين المؤقت تلقائي للبادئات المتكررة بمدة صلاحية افتراضية 5 دقائق. وتُحتسب إصابات التخزين المؤقت بسعر 0.20 دولار لكل مليون رمز مقابل 2.00 دولار للمدخلات غير المخزنة، وتكلف الكتابة لمدة ساعة 4.00 دولار مقابل 2.00 دولار لمدة 5 دقائق. وعلى بادئة من مليون رمز، تعوّض مدة الساعة الواحدة تكلفتها بعد إصابتين.

ضع المحتوى الثابت أولاً (موجه النظام، وتعريفات الأدوات، والمستندات)، والمحتوى المتغير أخيراً، ولا تضع طوابع زمنية في البادئة. مع حزمة openai SDK، مرّر مدة الصلاحية عبر extra_body:

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

تضبط Anthropic API مدة الصلاحية بحقل cache_control من المستوى الأعلى؛ أما العلامات داخل الرسائل فتُتجاهل:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

ويعتمد مكان ظهور استخدام التخزين المؤقت على الواجهة:

عند بث Chat Completions، اضبط stream_options.include_usage=true للحصول على بيانات الاستخدام في الجزء الأخير. وكل إصابة تجدّد مدة الصلاحية، التي تُثبَّت عند أول كتابة. القواعد الكاملة في دليل التخزين المؤقت للسياق.

أخطاء Kimi K3.1 Pro API وحلولها

تندرج معظم حالات الفشل ضمن ستة أنماط. افحص error.type في كل خطأ 429، لأن الحل يعتمد عليه.

انتبه لعمليات إعادة المحاولة. تعيد حزمة OpenAI SDK المحاولة مرتين افتراضياً عند أخطاء الاتصال، و408 و409 و429 و5xx، لذا قد يتحول الاستدعاء الواحد إلى ثلاثة طلبات تُحتسب على حد RPM لديك. في الفئات المنخفضة، اخفض max_retries لدى العميل وتولَّ التراجع بنفسك بناءً على error.type. والطلبات التي تقاطعها أخطاء 429 لا تُحتسب عليك.

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

حدود معدل Kimi K3.1 Pro حسب الفئة

يحدد إجمالي شحن رصيدك الفئة التي تنتمي إليها وفق صفحة الحدود:

تتيح الفئة Tier0 ثلاث طلبات في الدقيقة، وكل دور في حلقة أدوات هو طلب. فتشغيل وكيل من خمسة أدوار يتجاوز بالفعل دقيقة واحدة عند هذه الفئة، لذا خصص 10 دولارات كإجمالي شحن قبل اختبار الوكلاء بجدية.

اختبار العقد لـ Kimi API باستخدام Apidog CLI

يكشف اختبار العقد اليوم الذي يتوقف فيه وكيلك عن استقبال tool_calls. دع وكيل البرمجة لديك يبنيه باستخدام Apidog CLI. ثبّته وسجّل الدخول مرة واحدة:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

ثم وجّه Claude Code أو Codex أو أي وكيل تستخدمه:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

فيقرأ الوكيل المخطط، ويتحقق من صحة الحمولة، ويشغّل حالة الاختبار:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

تحتاج حالات الاختبار إلى فئة صالحة؛ ويسردها الأمر apidog test-case category --project <projectId>. وبمجرد نجاح التشغيل، استبدل -r cli,json بـ -r junit مع --out-dir، ليصبح الفحص نفسه بوابة لخط CI لديك، كما يوضح دليل Apidog CLI لخطوط CI/CD. أما إعداد الوكيل فتجده في Apidog CLI في Claude Code. وتغطي خطة Apidog المجانية حتى 4 مستخدمين.

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

ما هو عنوان URL الأساسي لـ Kimi K3.1 Pro API؟

https://api.moonshot.ai/v1 لـ Chat Completions وResponses API، وhttps://api.moonshot.ai/anthropic لـ Messages API المتوافقة مع Anthropic.

هل يدعم Kimi K3.1 Pro API المعامل thinking؟

لا. التفكير مُفعَّل دائماً. وتحكم فيه عبر حقل reasoning_effort من المستوى الأعلى ("low" أو "high" أو "max").

لماذا أتلقى خطأ 429 مباشرة بعد شحن الرصيد؟

اقرأ error.type. فـ engine_overloaded_error يعني سعة الخادم ولن يحلّه شحن الرصيد. أما rate_limit_reached_error فيعني حدود فئتك، والفئة Tier0 تتيح 3 طلبات في الدقيقة فقط.

كيف أعرف ما إذا كان التخزين المؤقت يعمل؟

قيمة غير صفرية في حقل قراءة التخزين المؤقت ضمن usage تعني حدوث إصابة: prompt_tokens_details.cached_tokens على Chat Completions أو cache_read_input_tokens على Messages.

هل توجد فئة مجانية لـ Kimi K3.1 Pro API؟

لا. يحتاج API إلى شحن بحد أدنى دولار واحد. والدردشة المجانية في تطبيق Kimi هي الطريق بسعر صفر، وهي مشروحة في كيفية استخدام Kimi K3.1 Pro مجاناً. ولمعرفة خلفية النموذج، راجع ما هو Kimi K3.1 Pro.