# الاستعلام عن الرصيد باستخدام مفتاح API

> استعلم عن الحصة المتبقية للمفتاح الحالي باستخدام مفتاح API من نوع sk-: يعيد GET /v1/user/balance الحقول is_active / balance / unit، ويعيد GET /v1/credits الحقلين total_credits / total_usage بأسلوب OpenRouter. متوافق مع الاستعلام الدوري من عملاء الطرف الثالث مثل cc-switch.

URL: https://docs.lmuai.com/ar/docs/api/balance



باستخدام مفتاح API يبدأ بـ `sk-` يمكنك الاستعلام مباشرةً عن **الحصة المتبقية لهذا المفتاح وحالة توفره**. هذا مناسب لعملاء الطرف الثالث التي تعرض الرصيد في واجهتها، أو للسكربتات التي تراقب الرصيد.

<Callout type="info">
  **هذه الواجهات للقراءة فقط**: لا تتم فوترتها ولا تستهلك حصة. تتحقق المصادقة من المفتاح نفسه فقط، لذا يمكنك قراءة الحصة المتبقية حتى عندما تكون الحصة مستنفدة وتُرفض طلبات العمل (في هذه الحالة تكون `is_active` هي `false`).
</Callout>

***

## 1. نظرة عامة على الواجهات [#1-نظرة-عامة-على-الواجهات]

| الواجهة                | تنسيق العميل الذي تدعمه                | ما تعيده                                                                                       |
| ---------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET /v1/user/balance` | قالب الرصيد العام في cc-switch         | `is_active` / `balance` / `unit`، بالإضافة إلى `used` / `total` عندما يكون للمفتاح حصة إجمالية |
| `GET /user/balance`    | مثل السابق، لعنوان Base URL بدون `/v1` | مطابق تمامًا للسطر أعلاه                                                                       |
| `GET /v1/credits`      | بأسلوب OpenRouter                      | `data.total_credits` / `data.total_usage`                                                      |

| العنصر                | القيمة                           |
| --------------------- | -------------------------------- |
| Base URL              | `https://api.lmuai.com`          |
| المصادقة              | `Authorization: Bearer <sk-...>` |
| تنسيق الاستجابة       | JSON                             |
| هل يلزم تسجيل الدخول؟ | لا، مفتاح API يكفي               |

<Callout type="warn">
  `/user/balance` هو اسم بديل لـ `/v1/user/balance` (يُستخدم عندما يُضبط Base URL لدى العميل بدون `/v1`). أما `/v1/credits` فليست له **أي** نسخة على المسار الجذري، ويجب تضمين `/v1`.
</Callout>

***

## 2. أي رصيد يتم إعادته [#2-أي-رصيد-يتم-إعادته]

`balance` ليس بالضرورة رصيد محفظة الحساب، بل هو **الحصة المتبقية المتاحة فعليًا للمفتاح الحالي**، ويُحدد بالترتيب التالي:

| الترتيب | حالة المفتاح                    | معنى `balance`                                                       |
| ------- | ------------------------------- | -------------------------------------------------------------------- |
| 1       | للمفتاح حصة إجمالية خاصة به     | الحصة المتبقية لهذا المفتاح (`total - used`)                         |
| 2       | المفتاح ينتمي إلى مجموعة اشتراك | الحصة المتبقية للاشتراك (`unit` تكون `requests` عند الاحتساب بالطلب) |
| 3       | لا ينطبق أي مما سبق             | رصيد محفظة الحساب                                                    |

كما يشير `is_active` إلى ما إذا كان المفتاح **قابلًا للاستخدام الآن في طلبات العمل**: يكون `true` عندما يكون المفتاح نشطًا وغير منتهي الصلاحية ولم تُستنفد حصته الإجمالية؛ ويكون أيضًا `false` عندما ينتمي المفتاح إلى مجموعة اشتراك بلا اشتراك سارٍ.

***

## 3. `GET /v1/user/balance` [#3-get-v1userbalance]

```http
GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```

**الاستجابة — وضع رصيد المحفظة** (المفتاح بلا حصة ولا ينتمي إلى مجموعة اشتراك):

```json
{
  "is_active": true,
  "balance": 1575.13,
  "unit": "USD"
}
```

**الاستجابة — للمفتاح حصة إجمالية** (في هذه الحالة يُعاد أيضًا `used` و `total`):

```json
{
  "is_active": true,
  "balance": 6,
  "unit": "USD",
  "used": 4,
  "total": 10
}
```

**الاستجابة — مجموعة اشتراك بالاحتساب حسب الطلب**:

```json
{
  "is_active": true,
  "balance": 842,
  "unit": "requests"
}
```

### حقول الاستجابة [#حقول-الاستجابة]

| الحقل       | النوع  | الوصف                                                                       |
| ----------- | ------ | --------------------------------------------------------------------------- |
| `is_active` | bool   | ما إذا كان المفتاح قابلًا للاستخدام الآن في طلبات العمل                     |
| `balance`   | number | الحصة المتبقية؛ راجع `unit` لمعرفة الوحدة                                   |
| `unit`      | string | `USD` (الافتراضي)، أو `requests` لمجموعات الاشتراك المحتسبة حسب الطلب       |
| `used`      | number | **يظهر فقط عندما يكون للمفتاح حصة إجمالية**: الحصة المستخدمة من هذا المفتاح |
| `total`     | number | **يظهر فقط عندما يكون للمفتاح حصة إجمالية**: الحصة الإجمالية لهذا المفتاح   |

<Callout type="info">
  `used` / `total` لهما قيم ذات معنى في وضع الحصة الخاصة بالمفتاح فقط. لا يعيد وضعا رصيد المحفظة والاشتراك هذين الحقلين — اعتمد على `balance` ولا تستنتجه من `total - used`.
</Callout>

***

## 4. `GET /v1/credits` [#4-get-v1credits]

تنسيق رصيد بأسلوب OpenRouter؛ تعرض العملاء الحصة المتبقية على أنها `total_credits - total_usage`.

```http
GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```

**الاستجابة:**

```json
{
  "data": {
    "total_credits": 20,
    "total_usage": 4
  }
}
```

| الحقل                | النوع  | الوصف                                                                                  |
| -------------------- | ------ | -------------------------------------------------------------------------------------- |
| `data.total_credits` | number | **المستخدم + المتبقي**، بحيث يساوي `total_credits - total_usage` الحصة المتبقية تمامًا |
| `data.total_usage`   | number | الحصة المستخدمة                                                                        |

<Callout type="warn">
  `total_credits` قيمة مركّبة من «المستخدم + المتبقي» و**ليست** القيمة الحرفية لحد الحصة. في وضع رصيد المحفظة تكون `total_usage` هي `0` ويساوي `total_credits` الرصيد؛ وعند استنفاد الحصة تُقيَّد الحصة المتبقية عند `0`، لذا يساوي `total_credits` في هذه الحالة الكمية المستخدمة.
</Callout>

***

## 5. الضبط في عملاء الطرف الثالث [#5-الضبط-في-عملاء-الطرف-الثالث]

| العميل / السيناريو                                     | كيفية الضبط                                                                                              |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| قالب الرصيد العام في cc-switch                         | يعمل Base URL ‏`https://api.lmuai.com` (بدون `/v1`) أو `https://api.lmuai.com/v1` (مع `/v1`) على حد سواء |
| عملاء متوافقون مع OpenRouter (Kelivo وRikkaHub وغيرها) | Base URL ‏`https://api.lmuai.com/v1`؛ وسيطلب العميل `/v1/credits`                                        |
| سكربت خاص بك                                           | استدعِ `/v1/user/balance` مباشرةً؛ حقوله أسهل في القراءة                                                 |

```bash
curl -s https://api.lmuai.com/v1/user/balance \
  -H "Authorization: Bearer sk-xxxxxxxx"
```

***

## 6. استجابات الخطأ [#6-استجابات-الخطأ]

يستخدم الاستعلام عن الرصيد مصادقة مفتاح API القياسية في البوابة، لذا تُعاد الأخطاء بالتنسيق نفسه المستخدم في استدعاءات API الأخرى. عندما لا يتضمن الطلب مفتاحًا:

```json
{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}
```

| رمز الحالة | `code`             | السيناريو                                                                                                                                                     |
| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`      | —                  | استجابة طبيعية؛ كما تعيد الحصة المستنفدة أو المفتاح منتهي الصلاحية أو الاشتراك المفقود `200`، مع `is_active: false` للدلالة على أن المفتاح غير قابل للاستخدام |
| `401`      | `API_KEY_REQUIRED` | لا يتضمن الطلب مفتاح API                                                                                                                                      |
| `401`      | `INVALID_API_KEY`  | المفتاح غير موجود أو بتنسيق غير صحيح                                                                                                                          |
| `401`      | `API_KEY_DISABLED` | تم تعطيل المفتاح                                                                                                                                              |
| `403`      | `ACCESS_DENIED`    | للمفتاح قائمة IP مسموح بها / محظورة، وعنوان IP الحالي غير مسموح به                                                                                            |

للاطلاع على الأخطاء العامة، راجع [رموز الأخطاء](/ar/docs/guide/errors).

***

## 7. الفرق عن «تصدير تفاصيل الاستخدام» [#7-الفرق-عن-تصدير-تفاصيل-الاستخدام]

|               | واجهات الرصيد في هذه الصفحة         | [تصدير تفاصيل الاستخدام](/ar/docs/api/usage-export) |
| ------------- | ----------------------------------- | --------------------------------------------------- |
| المصادقة      | مفتاح API من نوع `sk-`              | الحساب وكلمة المرور مقابل JWT                       |
| مستوى التفصيل | الحصة المتبقية للمفتاح الحالي       | تفاصيل لكل طلب على مستوى الحساب                     |
| الاستخدام     | عرض الرصيد في العميل، مراقبة الرصيد | تصدير الفواتير، المطابقة، التحميل إلى BI            |

تقع `GET /v1/usage` بين الاثنين: فهي تقبل أيضًا مفتاح `sk-` وتعيد إحصاءات استخدام اليوم والاستخدام التراكمي ومعلومات الحصة للمفتاح الحالي، بحقول أكثر تفصيلًا.