دليل ربط Kimi API: Base URL وأسماء الطرازات وأول استدعاء (2026)

تتوافق Kimi API مع واجهة OpenAI، وعند الترحيل يكفي عادةً تغيير ثلاثة أشياء: Base URL ومفتاح API واسم الطراز. لكن تفاصيل واجهة 2026 تحمل عدة مزالق: الطرازات القديمة أُوقفت، وmax_tokens أصبح مهملًا، وK3 يستخدم أعلى درجة استدلال افتراضيًا، ولا يُعاد استخدام الطلبات المتدفقة إلا في الكتلة الأخيرة.

تسير المقالة عبر الربط من الصفر: تأكيد الموقع والبروتوكول، ثم اختيار الطراز، ثم أول استدعاء عبر curl وPython، وأخيرًا قائمة الترحيل ومقارنة الأخطاء. تُعتمد الطرازات والأسعار على أسعار الطرازات داخل الموقع.

ملاحظة: Moonshot وKimi علامتان تجاريتان مملوكتان لمالكيهما، وهذه المقالة للشرح التقني فقط. قد تتغير قائمة الطرازات وطول السياق وقواعد المعاملات، فيُرجى الاعتماد على الإصدار الحالي من الوثائق الرسمية.

أولًا: تأكيد ثلاثة أمور قبل الربط

1. الموقع: الموقع الصيني يستخدم platform.kimi.com، والدولي platform.kimi.ai. الحسابات والأرصدة والمفاتيح في الموقعين مستقلة تمامًا.
2. البروتوكول: معظم المشاريع تستخدم Chat Completions المتوافق مع OpenAI؛ والمشاريع التي تملك Anthropic SDK يمكنها استخدام مدخل Messages المتوافق.
3. الطراز: تأكد أولًا من الطرازات التي يراها حسابك، ثم اكتبها في الشيفرة. لا تنسخ شرحًا عمره أشهر.

نطاق الطلبات في الموقع الصيني هو https://api.moonshot.cn، وفي الدولي https://api.moonshot.ai. يجب أن يتطابق النطاق والمفتاح، وهذا من أكثر أسباب 401 شيوعًا.

ثانيًا: Base URL ومسارات الواجهة

البروتوكول	Base URL	مسار الواجهة
OpenAI Chat Completions	https://api.moonshot.cn/v1	/chat/completions
OpenAI Responses	https://api.moonshot.cn/v1	/responses
Anthropic Messages	https://api.moonshot.cn/anthropic	/v1/messages
قائمة الطرازات	https://api.moonshot.cn/v1	/models
استعلام الرصيد	https://api.moonshot.cn/v1	/users/me/balance

في الموقع الدولي يُستبدل النطاق بـapi.moonshot.ai مع بقاء المسارات. يُكتب base_url في OpenAI SDK حتى /v1، ويتولى SDK إضافة /chat/completions؛ أما curl فيحتاج المسار الكامل. خلط الاثنين يؤدي إلى طبقة /v1 زائدة أو ناقصة، ويظهر ذلك كخطأ 404.

مدخل التوافق مع Anthropic لا يحمل /v1 في Base URL، وهذا يختلف عن مدخل OpenAI. عند الربط عبر Claude Code أو Anthropic SDK آخر، اكتب https://api.moonshot.cn/anthropic وفق المثال الرسمي.

ثالثًا: كيف تختار اسم الطراز

اسم الطراز	السياق	المهام المناسبة	ملاحظة
kimi-k3	1M	الاستدلال المعقد وهندسة البرمجيات والعمل المعرفي والمستندات الطويلة جدًا	reasoning_effort الافتراضي max
kimi-k2.7-code	256K	توليد الشيفرة والأسئلة عن المستودعات والوكلاء	التزام أفضل بالتعليمات في السياق الطويل
kimi-k2.7-code-highspeed	256K	الإكمال منخفض التأخير والبرمجة التفاعلية	الطراز نفسه بسرعة أعلى
kimi-k2.6	256K	المحادثة العامة والاستخراج والمدخلات المرئية والنصية	يدعم وضعي التفكير وغير التفكير

أُوقفت الطرازات القديمة: عائلة moonshot-v1 كاملة وkimi-k2.5 توقف دعمهما في 31 أغسطس 2026، وسلسلة kimi-k2 في 25 مايو 2026، وkimi-latest قبل ذلك. المشاريع التي ما زالت تستخدم هذه الأسماء تنتقل مباشرة إلى kimi-k3 أو سلسلة K2، ولا تبحث عن وثائق قديمة.

لا يلزم اختيار K3 افتراضيًا للمهام العامة. فقدرته عالية، لكن درجة الاستدلال الافتراضية مرتفعة، فيزداد التأخير ورموز الإخراج؛ وغالبًا يكون kimi-k2.6 أنسب للتصنيف البسيط والاستخراج بتنسيق ثابت. أما مهام الشيفرة فتنظر في سلسلة K2.7 Code.

رابعًا: أول استدعاء عبر curl

export MOONSHOT_API_KEY="مفتاحك"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "أجب فقط: تم الربط بنجاح"}
    ],
    "max_completion_tokens": 64
  }'

إذا عاد 200 وكان المحتوى متوقعًا، فالعناصر الأربعة سليمة: المفتاح والموقع واسم الطراز والمسار. إذا عاد 401 فافحص تطابق الموقع والمفتاح أولًا؛ وإذا عاد 404 فافحص اسم الطراز و/v1؛ وإذا عاد 400 فابحث في رسالة الخطأ عن ذكر السياق أو حد الإخراج.

خامسًا: Python SDK والإخراج المتدفق

ثبّت OpenAI SDK بإصدار 1.0 أو أحدث، وغيّر base_url والمفتاح فقط:

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "اشرح في ثلاث نقاط أي الفرق تناسبها بوابة API"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\nالاستخدام:", chunk.usage)

الاستجابة المتدفقة هي SSE، يبدأ كل سطر بـdata: وينتهي بـdata: [DONE]. عند تفعيل include_usage تُعاد قبل النهاية كتلة إضافية تحتوي choices فارغة وusage فقط. إذا انقطع الاتصال في المنتصف فقد لا تصل هذه الكتلة، لذا لا تعتمد إحصاء الاستخدام على العميل وحده.

سادسًا: max_completion_tokens وقوة الاستدلال

أصبح max_tokens مهملًا، وتستخدم الشيفرة الجديدة max_completion_tokens موحدًا. وهو يمثل طول الإخراج المطلوب توليده، لا مجموع الإدخال والإخراج. القيمة الافتراضية في K3 هي 131072، والحد الأقصى 1048576؛ وإذا تجاوز الإدخال مضافًا إليه نافذة السياق، يعيد الطلب invalid_request_error.

قاعدتان عمليتان:

• اضبط قيمة صغيرة في الاختبار والمهام ذات التنسيق الثابت، مثل 256 إلى 1024، لتجنب الإطالة.
• عند بلوغ الحد تكون finish_reason بقيمة length، وعند الانتهاء الطبيعي تكون stop. لا تعد المحاولة فور رؤية length، بل حدد أولًا هل الإخراج يحتاج طولًا فعليًا أم أن المطالبة مفتوحة أكثر من اللازم.

يملك K3 أيضًا معاملًا أعلى المستوى هو reasoning_effort، بقيم low وhigh وmax، والافتراضي max. خفضه إلى low في المهام البسيطة يقلل التأخير واستهلاك الرموز، ويرفع للمهام المعقدة. عند استخدام OpenAI SDK، إذا لم يكن الإصدار يدعم المعامل، مرره عبر extra_body. يوجد محتوى تفكير K3 في reasoning_content، ويجب إعادته كما هو في المحادثات متعددة الأدوار واستدعاء الأدوات.

سابعًا: الترحيل من OpenAI أو Moonshot القديم

1. اجرد كل أسماء الطرازات القديمة في الشيفرة والإعدادات، وأنشئ جدول استبدال.
2. عدّل base_url: الموقع الصيني https://api.moonshot.cn/v1، والدولي https://api.moonshot.ai/v1.
3. استبدل المفتاح بمفتاح الموقع المقابل، ولا تعده استخدامه بين الموقعين.
4. استبدل أسماء الطرازات، وفضّل kimi-k3 أو الإصدارات الحالية من سلسلة K2.
5. غيّر max_tokens إلى max_completion_tokens.
6. غيّر إعداد thinking في K2.x إلى reasoning_effort في K3، ولا ترسلهما معًا.
7. أضف stream_options={"include_usage": True} إلى الطلبات المتدفقة.
8. شغّل اختبار انحدار على مجموعة مهام حقيقية، وسجّل الجودة والتأخير وfinish_reason والاستخدام.
9. احتفظ بالإعداد القديم لدورة إصدار واحدة، واحذفه بعد التأكد.

لا تحوّل كل الحركة دفعة واحدة. ابدأ ببيئة الاختبار، ثم الأعمال منخفضة المخاطر، وأخيرًا المسار الأساسي، مع مفتاح تراجع في كل خطوة.

ثامنًا: مقارنة الأخطاء الشائعة

رمز الحالة	نوع الخطأ	السبب الشائع	المعالجة
400	invalid_request_error	معامل خاطئ، سياق طويل، تجاوز حد الإخراج	عدّل الطلب
400	content_filter	المدخل أو المخرج خالف سياسة المحتوى	عدّل المطالبة
401	invalid_authentication_error	مفتاح غير صالح أو موقع غير مطابق	غيّر المفتاح أو النطاق
404	resource_not_found_error	اسم طراز أو مسار خاطئ	راجع قائمة الطرازات
429	rate_limit_reached_error	تجاوز التزامن أو RPM أو TPM أو TPD	خفّض السرعة أو ارفع المستوى
429	exceeded_current_quota_error	تأخر سداد أو رصيد غير كافٍ	اشحن
504	Gateway Time-out	انتظار طويل في طلب غير متدفق	استخدم البث

قد يعيد الطلب غير المتدفق 504 إذا تجاوز الانتظار على الخادم 900 ثانية. يُستحسن استخدام البث في توليد النصوص الطويلة وتحليل المستندات الطويلة ووكلاء الشيفرة، فهو يبقي العميل يتلقى بيانات ويقلل هدر «الانتظار حتى المهلة ثم إعادة المحاولة».

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

إلى أي مستوى يُكتب Base URL؟

في OpenAI SDK اكتب https://api.moonshot.cn/v1 دون /chat/completions. أما curl فيحتاج https://api.moonshot.cn/v1/chat/completions كاملًا. وفي Anthropic SDK اكتب https://api.moonshot.cn/anthropic.

لماذا لا يعمل max_tokens؟

أصبح المعامل مهملًا، وقد تتجاهله بعض الطرازات أو تعيد خطأ. استخدم max_completion_tokens، وتذكر أنه حد الإخراج لا حد الإدخال المضاف.

لماذا يستغرق K3 أطول من المتوقع؟

لأن reasoning_effort الافتراضي max، فيجري استدلالًا أعمق. خفّضه إلى low أو high في المهام البسيطة، وحدّ طول الإخراج، فتحسن التأخير عادةً بوضوح.

لماذا لا يظهر usage بعد نهاية البث؟

يجب ضبط stream_options={"include_usage": True} صراحةً. وحتى مع الضبط قد لا تصل الكتلة الأخيرة عند انقطاع الاتصال، لذا يجب على بيئة الإنتاج حساب الاستخدام على الخادم أيضًا.

ماذا نعدّل أيضًا عند الترحيل من OpenAI؟

معظم الشيفرة تغيّر Base URL والمفتاح واسم الطراز فقط. راجع أيضًا max_tokens واستخدام البث وتحويل أنواع الأخطاء وسياسة إعادة المحاولة، خصوصًا تصنيف 429.

الخطوة التالية

أنشئ مفتاح اختبار في بوابة ZSQH AI، وشغّل مهمة حقيقية واحدة على kimi-k3 وأخرى على kimi-k2.6، ثم اربط الإنتاج بعد التأكد. الطرازات المتاحة والفوترة وفق أسعار الطرازات.

قراءات ذات صلة:

• أسعار Kimi API والفوترة
• دليل ربط Qwen API: Base URL والطرازات وأول استدعاء
• الأسعار والخطط