استخدام API عبر Postman

يمكنك تجربة Mibyan API من Postman دون كتابة برنامج. تحتاج فقط إلى مفتاح API خاص بمشروعك.

لا تشارك مفتاح API في لقطة شاشة أو ملف Collection عام، ولا تضعه مباشرة داخل الطلب المحفوظ. استخدم متغيرًا من نوع secret أو sensitive داخل Postman.

الطريقة السريعة: استيراد OpenAPI

افتح Postman واختر Import.
اختر Link.
أدخل الرابط:

https://api.mibyanai.com/openapi.yaml

اختر Import لإنشاء Collection تحتوي نقاط النهاية المتاحة.
افتح طلب POST /v1/chat/completions وأضف مفتاحك في تبويب Authorization كما هو موضح أدناه.

الإعداد اليدوي

1. إنشاء Environment

من Environments أنشئ بيئة باسم Mibyan وأضف المتغيرين:

Variable	Type	Value
`MIBYAN_BASE_URL`	default	`https://api.mibyanai.com/v1`
`MIBYAN_API_KEY`	secret	مفتاح المشروع الذي يبدأ عادةً بـ `mbn_test_` أو `mbn_live_`

احفظ البيئة ثم اخترها من أعلى Postman.

2. إنشاء الطلب

Method: POST
URL:

{{MIBYAN_BASE_URL}}/chat/completions

3. إضافة المصادقة

افتح تبويب Authorization ثم اختر:

Type: Bearer Token
Token: {{MIBYAN_API_KEY}}

لا تكتب كلمة Bearer داخل خانة Token؛ يضيفها Postman تلقائيًا.

4. إعداد Headers

أضف:

Key	Value
`Content-Type`	`application/json`

5. إضافة JSON Body

افتح Body → raw → JSON والصق:

{
  "model": "mibyan-4.1",
  "messages": [
    {
      "role": "user",
      "content": "هلا"
    }
  ],
  "stream": false,
  "max_tokens": 64
}

اضغط Send. يجب أن تستقبل استجابة مشابهة:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "mibyan-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "هلا بك!",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 206,
    "completion_tokens": 5,
    "total_tokens": 211
  }
}

قيم الاستخدام توضيحية وقد تختلف حسب الطلب والنموذج.

اختبار قائمة النماذج

أنشئ طلبًا ثانيًا:

Method: GET
URL: {{MIBYAN_BASE_URL}}/models
Authorization: نفس Bearer Token

يجب أن يظهر النموذج العام mibyan-4.1 ضمن data.

اختبار Streaming

غيّر stream إلى true. ستصل الاستجابة بصيغة Server-Sent Events وتنتهي بـ:

data: [DONE]

ابدأ دائمًا بـstream: false للتأكد من صحة الرابط والمفتاح وJSON. قد تعرض بعض إصدارات Postman أحداث البث مجمّعة في نافذة الاستجابة بدل إظهار كل حدث لحظة وصوله.

استكشاف الأخطاء

Status	السبب المعتاد	الحل
`400`	JSON أو parameter غير صالح	اختر Body من نوع JSON وتحقق من `model` و`messages`
`401`	المفتاح مفقود أو غير صالح	تحقق من Environment ومن اختيار Bearer Token
`403`	المفتاح لا يملك صلاحية endpoint أو model	راجع صلاحيات المفتاح داخل Mibyan Platform
`404`	رابط أو model غير صحيح	استخدم `/v1/chat/completions` و`mibyan-4.1`
`429`	تجاوز rate limit أو budget	راجع Usage وحدود المشروع ثم أعد المحاولة لاحقًا

كل استجابة تحتوي header باسم x-request-id. احتفظ بقيمته عند التواصل مع الدعم، لكن لا ترسل مفتاح API.

​الطريقة السريعة: استيراد OpenAPI

​الإعداد اليدوي

​1. إنشاء Environment

​2. إنشاء الطلب

​3. إضافة المصادقة

​4. إعداد Headers

​5. إضافة JSON Body

​اختبار قائمة النماذج

​اختبار Streaming

​استكشاف الأخطاء

الطريقة السريعة: استيراد OpenAPI

الإعداد اليدوي

1. إنشاء Environment

2. إنشاء الطلب

3. إضافة المصادقة

4. إعداد Headers

5. إضافة JSON Body

اختبار قائمة النماذج

اختبار Streaming

استكشاف الأخطاء