DEV Community

Cover image for كيفية استخدام Kimi K3 API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Kimi K3 API

أطلقت Moonshot AI نموذج Kimi K3 في 16 يوليو 2026، ووصفته بأنه أكثر نماذجها قدرة حتى الآن: أول نموذج مفتوح من فئة 3T في العالم، بتصميم Mixture-of-Experts بمعاملات 2.8T ونافذة سياق بحجم 1,048,576 رمزًا. ما يهم المطورين عمليًا ليس الحجم فقط، بل واجهة برمجة التطبيقات: يتوافق Kimi K3 مع OpenAI SDK، لذا يمكنك إعادة استخدام عميلك الحالي، وتغيير base_url وmodel إلى kimi-k3، ثم بدء بث الاستجابات خلال دقائق. يوضح هذا الدليل إعداد المفتاح، واستدعاءات Python وJavaScript وcURL، والبث، والأدوات، ووضع JSON، وreasoning_effort، والتخزين المؤقت للسياق، ثم اختبار الطلبات الخام في Apidog.

جرّب Apidog اليوم

ملخص سريع

  • معرّف النموذج على منصة Kimi هو kimi-k3. وعلى OpenRouter استخدم moonshotai/kimi-k3.
  • تتوافق نقطة النهاية مع OpenAI SDK: اضبط base_url وapi_key وmodel="kimi-k3".
  • تأكد من عنوان URL الأساسي في platform.kimi.ai. استخدمت Kimi تاريخيًا https://api.moonshot.ai/v1.
  • نافذة السياق تبلغ مليون رمز. الأسعار: 0.30 دولار لكل مليون رمز إدخال عند cache-hit، و3.00 دولارات عند cache-miss، و15.00 دولارًا لكل مليون رمز إخراج.
  • يدعم النموذج البث، واستدعاءات الأدوات، ووضع JSON، والإخراج المنظم، وreasoning_effort.
  • لاختبار الطلبات وتصحيحها، استورد أمر cURL إلى Apidog، واحفظ المفتاح كمتغير بيئة، وقارن بين kimi-k3 وkimi-k2-7-code.

أي نموذج Kimi يجب أن تستدعي؟

ابدأ باختيار النموذج وفقًا لحجم المهمة وتكلفتها:

  • استخدم kimi-k3 للبرمجة المعقدة، والوكلاء طويلة المدى، وسياق يصل إلى مليون رمز، وتنسيق الأدوات.
  • استخدم خط K2.7 Code للأعمال البرمجية الروتينية وعالية الحجم عندما تكون التكلفة لكل استدعاء أولوية.

Kimi K3 هو النموذج الرائد في العائلة، ويستهدف مهام البرمجة والاستدلال والسياق الطويل. لكنه يحمل تكلفة إخراج أعلى، وتشير مقالة الإطلاق من Moonshot إلى أنه يتأخر عن Claude Fable 5 وGPT-5.6 Sol في مقارناتهم الداخلية.

إذا كنت تبني مساعد برمجة عالي الحجم، أو مولد اختبارات CI، فابدأ بتقييم K2.7 Code:

استخدم kimi-k3 عندما تحتاج إلى استدلال أعمق، أو كامل نافذة السياق البالغة مليون رمز، أو تنسيق أدوات وكيلية.

احصل على مفتاح API من منصة Kimi

انتقل إلى platform.kimi.ai وسجّل الدخول. من لوحة التحكم يمكنك إنشاء المفاتيح، ومراقبة الاستخدام، وتأكيد عنوان URL الأساسي لحسابك.

  1. افتح قسم API Keys وأنشئ مفتاحًا جديدًا.
  2. انسخ المفتاح فورًا واحفظه في مكان آمن؛ لن تظهر قيمته الكاملة مرة أخرى.
  3. أضف رصيدًا أو تحقق من إعدادات الفوترة قبل تنفيذ استدعاءات kimi-k3.
  4. انسخ عنوان URL الأساسي من لوحة التحكم. استخدمت Kimi تاريخيًا: 
https://api.moonshot.ai/v1
Enter fullscreen mode Exit fullscreen mode

لا تضع المفتاح داخل الشيفرة أو مستودع Git. صدّره كمتغير بيئة:

export KIMI_API_KEY="sk-your-key-here"
export KIMI_BASE_URL="https://api.moonshot.ai/v1"
Enter fullscreen mode Exit fullscreen mode

ستستخدم القيمة نفسها لاحقًا كمتغير بيئة في Apidog بدل لصقها في كل طلب.

للحصول على شرح أسعار cache-hit وcache-miss، راجع دليل تسعير Kimi K3.

البدء السريع: أول استدعاء لـ kimi-k3

واجهة Kimi متوافقة مع عقد Chat Completions في OpenAI. عمليًا، تحتاج إلى تغييرين في عميل OpenAI:

  1. اضبط base_url أو baseURL.
  2. استخدم model="kimi-k3".

بايثون

ثبّت الحزمة أولًا:

pip install openai
Enter fullscreen mode Exit fullscreen mode

ثم نفّذ الطلب:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # تأكد من القيمة الدقيقة في لوحة platform.kimi.ai.
    base_url=os.environ.get("KIMI_BASE_URL", "https://api.moonshot.ai/v1"),
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a precise coding assistant."},
        {
            "role": "user",
            "content": "Explain what a token bucket rate limiter does in one paragraph.",
        },
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

جافاسكريبت / تايب سكريبت

ثبّت الحزمة:

npm install openai
Enter fullscreen mode Exit fullscreen mode

ثم نفّذ الطلب:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // تأكد من القيمة الدقيقة في لوحة platform.kimi.ai.
  baseURL: process.env.KIMI_BASE_URL || "https://api.moonshot.ai/v1",
});

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "system", content: "You are a precise coding assistant." },
    {
      role: "user",
      content: "Explain what a token bucket rate limiter does in one paragraph.",
    },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

cURL 

curl "$KIMI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {
        "role": "user",
        "content": "Explain what a token bucket rate limiter does in one paragraph."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

تشخيص الأخطاء الشائعة

الرمز السبب المحتمل الإجراء
401 المفتاح مفقود أو غير صالح تحقق من KIMI_API_KEY وإعدادات البيئة
404 عنوان URL الأساسي أو المسار غير صحيح انسخ base_url من لوحة Kimi
رفض الفوترة لا يوجد رصيد كافٍ أو مستوى الفوترة غير مفعّل تحقق من الرصيد وإعدادات الحساب

لمزيد من خيارات العميل، راجع وثائق OpenAI Python SDK. تنطبق خيارات العميل هنا لأن واجهة الاتصال متوافقة.

بث الاستجابات

في واجهات الدردشة أو الوكلاء طويلة المدى، فعّل البث للحصول على الرموز فور وصولها بدل انتظار اكتمال الرد.

البث في بايثون 

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Write a 6-line poem about flaky tests.",
        }
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

البث في جافاسكريبت 

const stream = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "user", content: "Write a 6-line poem about flaky tests." },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
Enter fullscreen mode Exit fullscreen mode

يستخدم البث خلف الكواليس أحداث SSE. كل إطار يصل عادةً كسطر data: يحتوي جزءًا من JSON، وينتهي التدفق بـ:

data: [DONE]
Enter fullscreen mode Exit fullscreen mode

تتعامل SDK مع هذه الإطارات تلقائيًا، لكن فحصها خامًا مفيد عند حدوث انقطاع أو خطأ أثناء البث.

استدعاءات الأدوات

يدعم Kimi K3 استدعاءات الأدوات وقيود اختيار الأداة وتحميل الأدوات الديناميكي. تصف الأداة باستخدام JSON Schema، ويعيد النموذج اسم الوظيفة وحججها؛ أما تنفيذ الوظيفة نفسها فيبقى مسؤوليتك.

1. عرّف الأداة وأرسل الطلب 

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. Singapore",
                    },
                },
                "required": ["city"],
            },
        },
    }
]

messages = [
    {
        "role": "user",
        "content": "What's the weather in Singapore right now?",
    }
]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = first.choices[0].message.tool_calls[0]

print(tool_call.function.name)       # get_weather
print(tool_call.function.arguments)  # {"city": "Singapore"}
Enter fullscreen mode Exit fullscreen mode

2. نفّذ الوظيفة وأعد النتيجة للنموذج

النموذج لا يشغّل get_weather بنفسه. نفّذ الاستدعاء في تطبيقك، ثم أرسل النتيجة في رسالة بدور tool:

import json

messages.append(first.choices[0].message)

messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps({
        "city": "Singapore",
        "temp_c": 31,
        "sky": "humid",
    }),
})

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

تقييد اختيار الأداة

لفرض استدعاء أي أداة:

tool_choice="required"
Enter fullscreen mode Exit fullscreen mode

ولفرض وظيفة محددة:

tool_choice={
    "type": "function",
    "function": {"name": "get_weather"},
}
Enter fullscreen mode Exit fullscreen mode

عند بناء وكيل متعدد الأدوار، أعد تمرير سجل الرسائل الكامل. تم تدريب K3 في وضع «تاريخ التفكير المحفوظ»، وقد يؤدي حذف أدوار المساعد الداخلية بين الجولات إلى سلوك غير مستقر.

وضع JSON والإخراج المنظم

عندما يحتاج تطبيقك إلى بيانات قابلة للمعالجة آليًا، اطلب JSON بدل تحليل نص حر.

وضع json_object 

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "system",
            "content": "Return only valid JSON. No prose, no markdown.",
        },
        {
            "role": "user",
            "content": "Extract name and role from: 'Ada Lovelace, mathematician'.",
        },
    ],
    response_format={"type": "json_object"},
)

print(response.choices[0].message.content)
# {"name": "Ada Lovelace", "role": "mathematician"}
Enter fullscreen mode Exit fullscreen mode

إخراج منظم باستخدام json_schema

إذا كانت نسخة SDK وحسابك يدعمانه، استخدم json_schema لتحديد الشكل المطلوب:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Extract name and role from: 'Ada Lovelace, mathematician'.",
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"},
                },
                "required": ["name", "role"],
            },
        },
    },
)
Enter fullscreen mode Exit fullscreen mode

تحقق من دعم json_schema في لوحة التحكم قبل استخدامه في الإنتاج. عند الشك، استخدم json_object ثم تحقق من البنية في تطبيقك.

جهد الاستدلال القابل للتكوين

يوفر Kimi K3 الحقل reasoning_effort للتحكم في مقدار التفكير قبل الإجابة. المستوى المتاح حاليًا هو max، وهو المستوى الافتراضي أيضًا.

استخدمه في المهام التي تستفيد من التخطيط العميق، مع الانتباه إلى أن التفكير الأعمق يزيد رموز الإخراج وزمن الاستجابة.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from REST to GraphQL for a 40-endpoint API.",
        }
    ],
    reasoning_effort="max",
)
Enter fullscreen mode Exit fullscreen mode

إذا رفضت نسخة OpenAI SDK الحقل، مرّره عبر extra_body:

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from REST to GraphQL.",
        }
    ],
    extra_body={"reasoning_effort": "max"},
)
Enter fullscreen mode Exit fullscreen mode

يتيح extra_body إرسال حقول خاصة بالمزوّد لا تدعمها SDK بعد.

اختبار وتصحيح أخطاء Kimi K3 في Apidog

تخفي SDK تفاصيل HTTP وSSE، وهذا مناسب في الحالات الطبيعية. لكن عند ظهور خطأ في استدعاء أداة أو انقطاع تدفق، تحتاج إلى رؤية الطلب والاستجابة الخامّين.

استخدم Apidog لإرسال طلب kimi-k3 نفسه، وفحص أحداث SSE إطارًا بإطار، وحفظ المفتاح كمتغير بيئة بدل وضعه في نص الطلب. للحصول على سير عمل عام، راجع دليل اختبار واجهات برمجة التطبيقات بدون Postman.

خطوات الاختبار

  1. أنشئ طلب HTTP جديدًا في Apidog.
  2. اضبط الطريقة إلى POST.
  3. استخدم عنوان الطلب: 
{{KIMI_BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. أنشئ بيئة في Apidog وأضف المتغيرات التالية: 
KIMI_API_KEY
KIMI_BASE_URL
Enter fullscreen mode Exit fullscreen mode
  1. أضف الرؤوس: 
Authorization: Bearer {{KIMI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. أرسل نص الطلب التالي: 
{
  "model": "kimi-k3",
  "messages": [
    {
      "role": "user",
      "content": "Explain what a token bucket rate limiter does in one paragraph."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode
  1. راقب الاستجابة واستخدام الرموز لتقييم سلوك cache-hit وcache-miss.
  2. لاختبار البث، أضف: 
{
  "stream": true
}
Enter fullscreen mode Exit fullscreen mode

ضمن نص الطلب، ثم افحص إطارات data: الواردة.

  1. لتصحيح استدعاءات الأدوات، راقب مصفوفة tool_calls في الاستجابة. إذا كانت الوسائط غير صحيحة، تحقق من JSON Schema ووصف الوظيفة.
  2. لإجراء مقارنة A/B، انسخ الطلب وغيّر حقل النموذج فقط: 
{
  "model": "kimi-k2-7-code"
}
Enter fullscreen mode Exit fullscreen mode

ثم قارن زمن الاستجابة وجودة الإخراج والتكلفة على المطالبة نفسها.

يمكنك أيضًا لصق أمر cURL مباشرةً في Apidog للحصول على طلب محفوظ وقابل لإعادة التشغيل. وإذا كان وكيلك يتصل بالنموذج عبر MCP، راجع دليل التصحيح المرئي باستخدام عميل Apidog MCP. يمكنك تنزيل Apidog لتطبيق الخطوات باستخدام مفتاحك.

حالات استخدام واقعية

وكلاء البرمجة على مستوى المستودع

استفد من سياق المليون رمز وتنسيق الأدوات لقراءة قاعدة كود كبيرة، وتشغيل الاختبارات، وتحليل السجلات، والتكرار على الإصلاحات. احتفظ بملخص ثابت للمستودع في بداية المطالبة لزيادة احتمالية التخزين المؤقت.

تحليل الوثائق الطويلة

مرر مواصفات كاملة أو عقودًا أو مجموعات بحث، ثم اطلب استخراجًا منظمًا باستخدام json_schema. ضع المحتوى المشترك في مقدمة المطالبة لتستفيد من التخزين المؤقت عند تكرار الاستعلامات.

تخطيط الترحيل وإعادة الهيكلة

استخدم reasoning_effort="max" في مرحلة التخطيط، حيث تكون تكلفة التفكير الإضافي منطقية. بعد وضع الخطة، يمكنك توجيه التعديلات الميكانيكية إلى نموذج أقل تكلفة.

إجابات تستند إلى بيانات حديثة

باستخدام البحث عبر الإنترنت واستدعاءات الأدوات، يمكن لـ K3 جلب بيانات جديدة واستخدامها في إجابات المساعدين الذين لا يمكنهم الاعتماد على معرفة التدريب فقط.

في جميع الحالات، اتبع الحلقة نفسها:

  1. ابنِ الطلب باستخدام SDK.
  2. تحقق من السلوك الخام في Apidog.
  3. اربطه بتطبيقك بعد التأكد من شكل الطلب والاستجابة.

خلاصة

يتطلب استدعاء Kimi K3 في عميل متوافق مع OpenAI ثلاثة إعدادات أساسية:

base_url
api_key
model="kimi-k3"
Enter fullscreen mode Exit fullscreen mode

بعد ذلك يمكنك استخدام البث، واستدعاءات الأدوات، ووضع JSON، والإخراج المنظم، وreasoning_effort ضمن عقد Chat Completions المعتاد.

ركز على نقطتين عمليتين:

  • حافظ على بادئة ثابتة للمطالبة والسياق المشترك لتحسين cache-hit وخفض تكلفة الإدخال من 3.00 دولارات إلى 0.30 دولار لكل مليون رمز لذلك الجزء.
  • وجّه المهام الروتينية وعالية الحجم إلى K2.7 عند الحاجة إلى تكلفة أقل، واستخدم K3 عندما تستحق المهمة سياقه الكبير واستدلاله الأعمق.

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

ما معرّف نموذج API لـ Kimi K3؟

استخدم kimi-k3 على منصة Kimi. وعبر OpenRouter استخدم:

moonshotai/kimi-k3
Enter fullscreen mode Exit fullscreen mode

راجع قائمة النموذج على openrouter.ai/moonshotai/kimi-k3.

ما عنوان URL الأساسي الذي يجب استخدامه؟

تحقق منه في platform.kimi.ai، لأنها مصدر الحقيقة لحسابك. استخدمت Kimi تاريخيًا:

https://api.moonshot.ai/v1
Enter fullscreen mode Exit fullscreen mode

احتفظ به في متغير بيئة بدل ترميزه داخل التطبيق.

هل Kimi K3 متوافق مع OpenAI SDK؟

نعم. تتبع واجهة API تنسيق OpenAI Chat Completions، لذا تعمل SDK الرسمية في Python وJavaScript بعد تغيير base_url وmodel. مرر الحقول الخاصة بالمزوّد عبر extra_body عند الحاجة.

كم تبلغ تكلفة API لـ Kimi K3؟

  • 0.30 دولار لكل مليون رمز إدخال عند cache-hit
  • 3.00 دولارات لكل مليون رمز إدخال عند cache-miss
  • 15.00 دولارًا لكل مليون رمز إخراج

راجع دليل تسعير Kimi K3 للتفاصيل.

ماذا يفعل التخزين المؤقت للسياق؟

عندما تتطابق الرموز الأولى في طلبك مع طلب سابق، تعيد نقطة النهاية استخدام الحالة المحسوبة بدل إعادة حسابها. لهذا تنخفض تكلفة الإدخال من 3.00 دولارات إلى 0.30 دولار لكل مليون رمز لذلك الجزء.

لتحسين النتائج، اجعل مطالبة النظام والسياق المشترك في بداية الطلب ومتطابقين بين الاستدعاءات.

هل يمكن التحكم في عمق تفكير النموذج؟

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

هل أستخدم Kimi K3 أم Kimi K2.7 Code؟

استخدم kimi-k3 للاستدلال العميق، وسياق المليون رمز، وتنسيق الأدوات الوكيلة. للأعمال البرمجية الروتينية وعالية الحجم، قد يكون K2.7 خيارًا أقل تكلفة.

راجع:

كيف أصحح استجابة بث أو استدعاء أداة معطّلًا؟

أرسل الطلب الخام في Apidog مع:

{
  "stream": true
}
Enter fullscreen mode Exit fullscreen mode

ثم افحص أحداث SSE إطارًا بإطار. بالنسبة للأدوات، افحص tool_calls لتحديد ما إذا كانت المشكلة في JSON الناتج من النموذج أو في مخطط الأداة ووصفها.

Top comments (0)