Blog

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

استدعِ واجهة برمجة تطبيقات Kimi K3 باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ OpenAI: أدلة بدء سريعة لبايثون، وجافاسكريبت، وcURL، بالإضافة إلى البث، واستدعاءات الأدوات، ووضع JSON، وجهد الاستدلال، والتخزين المؤقت.

Ashley Innocent

Ashley Innocent

17 يوليو 2026

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

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

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

ملخص سريع

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

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

إذا كان عبء عملك هو مساعد برمجة عالي الحجم، أو كاتب اختبارات CI، أو أي شيء تدفع فيه مقابل كل استدعاء على نطاق واسع، فإن خط K2.7 Code الأقدم غالبًا ما يكون الأنسب من حيث التكلفة. ابدأ بـ دليل واجهة برمجة تطبيقات Kimi K2.7 Code ونظرة عامة على ما هو Kimi K2.7 Code لترى ما إذا كان هذا المستوى يغطي حالتك. لمقارنة شاملة بين القدرات والسعر، توضح مقارنة Kimi K3 vs Kimi K2.7 Code نقاط قوة كل منهما. الجأ إلى kimi-k3 عندما تحتاج إلى عمق استدلال إضافي، أو سياق 1 مليون كامل، أو تنسيق الأدوات الوكيلة؛ وانتقل إلى K2.7 عندما تكون المهمة روتينية وحجم العمل كبيرًا. إذا كنت ترغب في الحصول على نظرة عامة كاملة على القدرات أولاً، فإن شرح ما هو Kimi K3 يغطي البنية والمكان الذي يقع فيه النموذج.

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

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

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

صدر المفتاح كمتغير بيئة حتى لا يظهر أبدًا في التعليمات البرمجية المصدر الخاصة بك:

export KIMI_API_KEY="sk-your-key-here"

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

للحصول على تفصيل كامل لحسابات cache-hit مقابل cache-miss وكيفية ارتباطها بالفواتير الشهرية الحقيقية، راجع دليل تسعير Kimi K3.

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

تتبع واجهة برمجة تطبيقات Kimi عقد إكمال الدردشة الخاص بـ OpenAI، لذا تعمل حزم SDK الرسمية لـ OpenAI بتغييرين: base_url وmodel. قم بتثبيت حزمة SDK التي تفضلها، ثم قم بتشغيل أحد مقتطفات التعليمات البرمجية أدناه.

بايثون

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Kimi is OpenAI-SDK compatible. Confirm the exact base URL in the
    # console at platform.kimi.ai; Kimi has historically used the value below.
    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)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Confirm the base URL in the platform.kimi.ai console.
  baseURL: "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);

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."}
    ]
  }'

عيّن KIMI_BASE_URL إلى ما يظهره لوحة التحكم (على سبيل المثال https://api.moonshot.ai/v1). إذا أرجع أي من هذه استجابة 401، فالمفتاح خاطئ أو غير مضبوط. يشير رمز 404 على المسار عادةً إلى أن عنوان URL الأساسي خاطئ، وليس أن النموذج مفقود. تغطي وثائق OpenAI Python SDK خيارات العميل بتفصيل أكبر، وكل خيار هناك ينطبق هنا لأن تنسيق الاتصال هو نفسه.

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

لواجهات مستخدم الدردشة ومنعطفات الوكيل الطويلة، تريد الرموز فور وصولها بدلاً من انتظار اكتمال الرد بأكمله. اضبط stream=True وكرر عبر الفروق (deltas).

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)

خلف الكواليس، هذا هو تدفق أحداث مرسلة من الخادم (SSE): كل سطر هو إطار data: يحمل جزءًا صغيرًا من JSON، وينتهي التدفق بـ data: [DONE]. تخفي حزمة SDK هذا التأطير عنك، وهو أمر مريح حتى يحدث خطأ في منتصف التدفق وتحتاج إلى رؤية الإطارات الخام. هذا هو أحد الأماكن التي يثبت فيها قسم Apidog أدناه قيمته.

يعمل نفس العلم في JavaScript:

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 ?? "");
}

استدعاءات الأدوات (استدعاء الوظائف)

يدعم Kimi K3 استدعاءات الأدوات، وقيود اختيار الأدوات، وتحميل الأدوات الديناميكي، بحيث يمكنك ربطه بالوكلاء الذين يقرأون الملفات، أو يصلون إلى واجهات برمجة التطبيقات، أو يشغلون أوامر الطرفية. تصف وظائفك باستخدام JSON Schema، ويقرر النموذج متى يستدعي إحداها، وتعيد النتيجة في رسالة tool.

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"}

لا يقوم النموذج بتشغيل وظيفتك؛ بل يمنحك اسمًا وحجج JSON. تقوم بتنفيذ العمل الحقيقي، ثم تغذي المخرجات مرة أخرى حتى يتمكن النموذج من كتابة إجابة نهائية:

import json

# Append the assistant turn that asked for the tool, then the tool result.
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)

عيّن tool_choice="required" لفرض استدعاء أداة، أو مرر كائنًا محددًا {"type": "function", "function": {"name": "get_weather"}} لتثبيت وظيفة واحدة. تحافظ هذه القيود على الوكيل على المسار الصحيح عندما تعرف بالفعل الأداة التي يجب تشغيلها.

خدعة خاصة بـ K3 تستحق المعرفة مبكرًا: تم تدريب النموذج في وضع "تاريخ التفكير المحفوظ". إذا أسقط نظام الوكيل الخاص بك استدلال النموذج السابق بين الأدوار، فقد تصبح جودة التوليد غير مستقرة. عند بناء حلقة وكيل متعددة الأدوار، أعد تمرير سجل الرسائل الكامل بدلاً من تقليم الأدوار الداخلية للمساعد.

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

عندما تحتاج إلى إخراج قابل للقراءة آليًا، اطلب JSON مباشرة بدلاً من تحليل النثر. اضبط response_format على json_object واطلب من النموذج إرجاع JSON.

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"}

لضمانات أكثر صرامة، يدعم Kimi الإخراج المنظم مقابل مخطط (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"],
            },
        },
    },
)

تأكد من دعم json_schema لحسابك في لوحة التحكم قبل إطلاقه؛ عند الشك، يعتبر json_object بالإضافة إلى خطوة التحقق من جانبك هو الحل الآمن. تعرض Kimi أيضًا وضعًا جزئيًا وبحثًا عبر الإنترنت، مما يساعد عندما ترغب في ملء استجابة المساعد مسبقًا أو ترسيخ الإجابات على بيانات جديدة.

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

يعرض Kimi K3 معامل reasoning_effort الذي يتحكم في مقدار تفكير النموذج قبل الإجابة. المستوى المتاح اليوم هو max، وهو أيضًا الافتراضي؛ وقد ذكرت Moonshot أن مستويات أدنى وأعلى مخطط لها. التفكير الأعمق يكلف المزيد من رموز الإخراج ويضيف زمن استجابة، لذا فهو رافعة تقوم بضبطها لكل مهمة.

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",
)

إذا رفضت نسخة OpenAI SDK الخاصة بك الحقل على أنه غير معروف، فمرره عبر مخرج الطوارئ بدلاً من ذلك:

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

نمط extra_body هو كيفية إرسال أي حقل خاص بالمزود لا تدعمه حزمة SDK الأساسية بعد، وهو أمر شائع عندما تتحرك نقطة نهاية متوافقة بشكل أسرع من مكتبة العميل.

اختبار وتصحيح أخطاء kimi-k3 في Apidog

تخفي تعليمة SDK البرمجية تنسيق الاتصال، وهذا جيد حتى يعيد استدعاء أداة شكلًا خاطئًا أو ينقطع تدفق البيانات ولا يمكنك معرفة ما إذا كان الخطأ منك أم من نقطة النهاية. هذا هو المكان الذي يؤتي فيه عميل API الذي يتحدث HTTP الخام ثماره. يتيح لك Apidog إرسال طلب kimi-k3 الدقيق، ومشاهدة تدفق SSE إطارًا بإطار، وإبقاء مفتاحك خارج نص الطلب. إذا كنت تفضل اختبار استدعاءات API دون العيش في طرفية، فهذه حلقة أنظف من 'curl-and-squint'؛ يغطي دليل اختبار واجهات برمجة التطبيقات بدون Postman سير العمل العام.

إليك حلقة مركزة لـ kimi-k3:

  1. أنشئ طلب HTTP جديدًا في Apidog. اضبط الطريقة على POST وعنوان URL على عنوان URL الأساسي الخاص بك بالإضافة إلى /chat/completions.
  2. قم بتخزين مفتاحك كمتغير بيئة. في إعدادات بيئة Apidog، أضف KIMI_API_KEY، ثم اضبط رأس Authorization على Bearer {{KIMI_API_KEY}}. الآن تتم الإشارة إلى السر، وليس لصقه، ويمكنك التبديل بين مفاتيح الاختبار والإنتاج عن طريق تبديل البيئات.
  3. الصق نص JSON يحتوي على "model": "kimi-k3" ومصفوفة messages الخاصة بك. أرسله واقرأ الاستجابة الكاملة، بما في ذلك استخدام الرمز، حتى تتمكن من رؤية عدد cache-hit مقابل cache-miss في الاستدعاءات الحقيقية.
  4. قم بتغيير "stream": true وشاهد أحداث الخادم المرسلة وهي تصل كإطارات منفصلة. رؤية أجزاء data: الخام تجعل أخطاء البث واضحة بطريقة لا يفعلها المكرر المرتب لـ SDK.
  5. صحح أخطاء استدعاءات الأدوات عن طريق فحص مصفوفة tool_calls في الاستجابة. عندما تعود الوسائط بشكل خاطئ، يمكنك معرفة ما إذا كان النموذج قد أنتج JSON سيئًا أو أن المخطط الخاص بك كان غامضًا، وتصحيح الوصف هناك مباشرة.
  6. قم بإجراء اختبار A/B ضد kimi-k2-7-code. انسخ الطلب، وغير حقل model فقط، وقارن زمن الاستجابة وجودة الإخراج والتكلفة على نفس المطالبة. هذه هي أسرع طريقة صادقة لتحديد ما إذا كان الاستدلال الإضافي لـ K3 يستحق القفزة في السعر لمهمتك.

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

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

تتطابق بعض الأنماط بشكل واضح مع ما تم بناء kimi-k3 لأجله:

في كل من هذه الحالات، سير العمل هو نفسه: بناء الطلب باستخدام SDK، التحقق من السلوك الخام في Apidog، ثم ربطه بتطبيقك بمجرد أن تثق في الشكل.

خلاصة

يقتصر استدعاء Kimi K3 على ثلاثة إعدادات في عميل متوافق مع OpenAI: عنوان URL الأساسي من لوحة التحكم الخاصة بك، ومفتاح API الخاص بك، وmodel="kimi-k3". من هناك، يتبع البث، واستدعاءات الأدوات، ووضع JSON، والإخراج المنظم، وreasoning_effort جميعها عقد إكمال الدردشة الذي تعرفه بالفعل. الشيئان اللذان يستحقان الاستيعاب هما اقتصاديات التخزين المؤقت، حيث يؤدي الاحتفاظ ببادئة ثابتة إلى تحويل إدخال بقيمة 3.00 دولارات إلى إدخال بقيمة 0.30 دولار، والموازنة الصادقة التي يشتري بها K3 عمق الاستدلال بسعر حقيقي، لذا قم بتوجيه العمل الروتيني عالي الحجم إلى خط K2.7. ابنِ الطلب في التعليمات البرمجية، واختبره في Apidog، وستطلق kimi-k3 دون مفاجآت.

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

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل