> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> إعداد Postman وإرسال أول طلب إلى Mibyan Chat Completions خطوة بخطوة

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

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

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

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

```text theme={null}
https://api.mibyanai.com/openapi.yaml
```

4. اختر **Import** لإنشاء Collection تحتوي نقاط النهاية المتاحة.
5. افتح طلب `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:

```text theme={null}
{{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** والصق:

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

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

```json theme={null}
{
  "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 وتنتهي بـ:

```text theme={null}
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.