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

# إدارة مفاتيح API

> أنشئ مفاتيح Venice API وحدّد سقف إنفاقها وتتبّعها وحدّثها وألغِها من خلال الكود باستخدام مفتاح Admin.

يستطيع مفتاح Admin إدارة جميع مفاتيح API الأخرى الخاصة بك عبر API. امنح كل تطبيق أو بيئة أو عميل مفتاح Inference خاصاً به، وحدّد سقف ما يمكن لكل مفتاح إنفاقه، وتتبّع الاستخدام لكل مفتاح، وغيّر المفاتيح أو ألغِها دون فتح لوحة التحكم.

> [card] [إنشاء](#create-a-key)
>
> أصدِر مفتاحاً بسقف إنفاق

> [card] [تتبّع](#track-usage)
>
> اطّلع على ما ينفقه كل مفتاح

> [card] [تغيير](#change-limits-and-settings)
>
> ارفع السقف أو مدّد تاريخ انتهاء الصلاحية

> [card] [إلغاء](#revoke-or-rotate-a-key)
>
> أوقف مفتاحاً على الفور

## كيف يعمل

مفتاح Admin
مفتاح التحكم الخاص بك
ينشئ المفاتيح ويغيّرها ويلغيها
يقرأ الاستخدام والفوترة
يبقى على خادمك

Inference
cust:acme

50\$ / شهرياً
النماذج الخاصة فقط

Inference
cust:globex

5\$ / شهرياً
من 11.22.33.0/24 فقط

Inference
staging

10\$ / يومياً
تنتهي صلاحيته في 30 يونيو

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

| | Admin | Inference |
| - | :-: | :-: |
| استدعاء النماذج ونقاط نهاية الاستدلال الأخرى | ✓ | ✓ |
| التحقق من رصيده الخاص وحدود المعدل (`GET /api_keys/rate_limits`) | ✓ | ✓ |
| إنشاء المفاتيح وتحديثها وإلغاؤها (`/api_keys`) | ✓ | |
| قراءة الاستخدام والفوترة (`/billing/*`) | ✓ | |

> [!NOTE]
>
> أنشئ أول مفتاح Admin لك من لوحة التحكم: اتّبع دليل [إنشاء مفتاح API](https://docs.venice.ai/ar/guides/getting-started/generating-api-key.md) واختر **Admin** كنوع للمفتاح. احتفظ به في مخزن أسرار على جانب الخادم، وليس في الكود الذي يعمل على جانب العميل أبداً.

تقرأ الأمثلة في هذه الصفحة مفتاح Admin من `VENICE_ADMIN_KEY`:

```bash cURL theme={"system"}
export VENICE_ADMIN_KEY="your-admin-key"
```

```python Python theme={"system"}
import os
import requests

BASE = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_ADMIN_KEY']}"}
```

```javascript Node.js theme={"system"}
const BASE = "https://api.venice.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VENICE_ADMIN_KEY}`,
  "Content-Type": "application/json",
};
```

## إنشاء مفتاح

ينشئ هذا المثال مفتاح Inference لعميل واحد، بسقف إنفاق قدره 50 دولاراً شهرياً، وتنتهي صلاحيته في 30 يونيو 2027:

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50 },
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30"
  }'
```

```python Python theme={"system"}
resp = requests.post(f"{BASE}/api_keys", headers=HEADERS, json={
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": {"usd": 50},
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30",
})
resp.raise_for_status()
key = resp.json()["data"]
key_id, secret = key["id"], key["apiKey"]
```

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    apiKeyType: "INFERENCE",
    description: "cust:acme",
    consumptionLimit: { usd: 50 },
    limitPeriod: "MONTH",
    expiresAt: "2027-06-30",
  }),
});
const { data: key } = await res.json();
const { id: keyId, apiKey: secret } = key;
```

```json Response theme={"system"}
{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_...",
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50, "vcu": null, "diem": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "ALL",
    "expiresAt": "2027-06-30T00:00:00.000Z",
    "ipAllowlist": []
  }
}
```

> [!WARNING]
>
> `data.apiKey` هو القيمة السرية للمفتاح، وهذه الاستجابة هي المرة الوحيدة التي ستراها فيها. خزّنها فوراً. إذا فقدتها، فألغِ المفتاح وأنشئ مفتاحاً جديداً. احتفظ أيضاً بـ `data.id`: فكل الاستدعاءات الأخرى في هذه الصفحة تستخدمه.

### إعدادات المفتاح

اضبط هذه الإعدادات عند إنشاء المفتاح، أو غيّرها لاحقاً باستخدام `PATCH /api_keys`. جسم الطلب صارم، لذا يُرجع أي حقل غير معروف الخطأ `400`.

| الحقل | القيم | ما يفعله |
| - | - | - |
| `apiKeyType` | `INFERENCE` أو `ADMIN` | مطلوب عند الإنشاء. لا يمكن تغييره لاحقاً. |
| `description` | حتى 64 حرفاً | مطلوب عند الإنشاء. تستخدمه تحليلات الاستخدام لتسمية المفتاح، لذا ضع هنا معرّفك الخاص، مثل `cust:acme`. |
| `consumptionLimit` | `{ "usd": 50 }` | سقف الإنفاق لكل `limitPeriod`، بعملة `usd` أو `diem` أو كليهما. اترك العملة غير محددة، أو اضبطها على `null`، لإلغاء السقف. يحتسب سقف USD الدولار الأمريكي والأرصدة المجمّعة والأرصدة المكتسبة معاً. |
| `limitPeriod` | `EPOCH`، `MONTH`، `LIFETIME` | متى يُعاد ضبط السقف. القيمة الافتراضية `EPOCH` تُعيد الضبط يومياً عند 00:00 UTC، و`MONTH` في اليوم الأول من كل شهر (UTC)، و`LIFETIME` لا تُعيد الضبط أبداً. |
| `expiresAt` | `"2027-06-30"` | تاريخ، أو وقت بتوقيت UTC مثل `"2027-06-30T23:59:59Z"`. التاريخ وحده يعني الساعة 00:00 UTC من ذلك اليوم. اتركه غير محدد لمفتاح لا تنتهي صلاحيته أبداً. |
| `modelPrivacy` | `ALL`، `PRIVATE_TEXT`، `PRIVATE_ONLY` | القيمة الافتراضية `ALL` تسمح بأي نموذج. تشترط `PRIVATE_TEXT` استخدام نماذج نصوص وتضمينات من نوع Private أو TEE أو E2EE. وتشترط `PRIVATE_ONLY` ذلك لكل النماذج. |
| `ipAllowlist` | `["11.22.33.0/24"]` | حتى 100 عنوان IPv4 أو IPv6 عام أو نطاق CIDR. القائمة الفارغة تسمح بأي عنوان IP. |

يمكنك إنشاء ما يصل إلى 20 مفتاحاً في الدقيقة والاحتفاظ بما يصل إلى 500 مفتاح نشط. تواصل مع الدعم إذا كنت بحاجة إلى المزيد.

> [!TIP]
>
> هل تبني وكيلاً؟ يمكن لمحفظة تحتوي على VVV مُودَع (staked) على شبكة Base إصدار مفتاحها الخاص دون حساب Venice. راجع [إنشاء مفتاح API للوكيل المستقل](https://docs.venice.ai/ar/guides/integrations/generating-api-key-agent.md).

## تتبّع الاستخدام

| لمعرفة | استدعِ | اقرأ |
| - | - | - |
| ما أنفقه مفتاح واحد في هذه الفترة | `GET /api_keys/{id}` | `currentPeriodUsage` |
| ما أنفقه كل مفتاح في آخر 7 أيام | `GET /api_keys` | `usage.trailingSevenDays` |
| الإنفاق لكل مفتاح، حسب اليوم | `GET /billing/usage-analytics` | `byKey`، `byKeyDaily` |
| كل رسم، مع المفتاح الذي فُوتر عليه | `GET /billing/usage-history` | `apiKeyId` |
| ما إذا كان المفتاح يستطيع الإنفاق الآن | `GET /api_keys/rate_limits`، مستدعى بذلك المفتاح | `accessPermitted`، `balances` |
| المفاتيح التي تصطدم بحدود المعدل | `GET /api_keys/rate_limits/log` | `apiKeyId`، `modelId` |

### مفتاح واحد

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```python Python theme={"system"}
key = requests.get(f"{BASE}/api_keys/{key_id}", headers=HEADERS).json()["data"]
```

```javascript Node.js theme={"system"}
const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();
```

```json Response (trimmed) theme={"system"}
{
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "description": "cust:acme",
    "consumptionLimits": { "usd": 50, "diem": null, "vcu": null },
    "limitPeriod": "MONTH",
    "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" },
    "usage": { "trailingSevenDays": { "usd": "4.2000", "diem": "0.0000", "vcu": "0.0000" } },
    "lastUsedAt": "2026-11-03T14:05:00.000Z"
  }
}
```

استخدم هذا المفتاح 12.50 دولاراً من أصل 50 دولاراً المخصّصة له لهذا الشهر. لا يظهر `currentPeriodUsage` إلا في المفاتيح التي لها سقف بعملة USD أو DIEM، ومبالغ الاستخدام عبارة عن سلاسل نصية بأربع خانات عشرية. تُرجع الاستجابات `consumptionLimits` (بصيغة الجمع)، بينما ترسل الطلبات `consumptionLimit` (بصيغة المفرد).

### الإنفاق لكل مفتاح بمرور الوقت

تُرجع `GET /billing/usage-analytics` الإجماليات لكل مفتاح في `byKey` وصفاً واحداً لكل يوم في `byKeyDaily`، جاهزة للعرض في رسم بياني. مرّر `lookback` (القيمة الافتراضية `7d`، وحتى `90d`) أو زوجاً من `startDate` و`endDate` يغطي ما يصل إلى 90 يوماً. تُخزَّن النتائج مؤقتاً لمدة 10 دقائق.

```bash cURL theme={"system"}
curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```json Response (trimmed) theme={"system"}
{
  "byKey": [
    {
      "apiKeyId": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "description": "cust:acme",
      "totalUsd": 12.5,
      "totalDiem": 0,
      "totalUnits": 1830000
    }
  ]
}
```

### كل رسم، لكل مفتاح

تسرد `GET /billing/usage-history` كل رسم، ويحمل كل إدخال قيمة `apiKeyId` التي فُوتر عليها. استخدمها لمطابقة الإنفاق أو لفوترة عملائك. تُرجَع الإدخالات من الأقدم إلى الأحدث. أعِد إرسال `nextCursor` بصفته `cursor`، وحده، حتى تصبح قيمته `null`. أرسل `Accept: text/csv` للحصول على CSV بدلاً من ذلك.

```bash cURL theme={"system"}
curl -G https://api.venice.ai/api/v1/billing/usage-history \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  --data-urlencode "startTimestamp=2026-10-01T00:00:00Z" \
  --data-urlencode "endTimestamp=2026-11-01T00:00:00Z"
```

```python Python theme={"system"}
from collections import defaultdict

spend = defaultdict(float)
params = {"startTimestamp": "2026-10-01T00:00:00Z", "endTimestamp": "2026-11-01T00:00:00Z"}
while True:
    page = requests.get(f"{BASE}/billing/usage-history", headers=HEADERS, params=params).json()
    for entry in page["data"]:
        if entry["apiKeyId"]:
            spend[(entry["apiKeyId"], entry["currency"])] -= entry["amount"]
    if page["nextCursor"] is None:
        break
    params = {"cursor": page["nextCursor"]}
```

للرسوم قيمة `amount` سالبة، ولذلك تطرحها الحلقة للحصول على إجمالي موجب لكل مفتاح وعملة. الإدخالات التي لا تحتوي على `apiKeyId` مصدرها تطبيق Venice على الويب، أو هي إدخالات خاصة بالحساب مثل شراء الأرصدة.

### ما إذا كان المفتاح يستطيع الإنفاق الآن

تعمل `GET /api_keys/rate_limits` مع أي مفتاح وتقدّم تقريراً عن المفتاح الذي يستدعيها. يُشير `accessPermitted` إلى ما إذا كان المفتاح يستطيع الإنفاق الآن، ويُظهر `balances` ما تبقّى له لإنفاقه.

```bash cURL theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

تُرجع `GET /api_keys/rate_limits/log`، عند استدعائها بمفتاح Admin، آخر 50 مرة اصطدمت فيها بحدود المعدل، مع `apiKeyId` و`modelId` لكل منها.

## تغيير الحدود والإعدادات

أرسل `id` الخاص بالمفتاح والحقول التي تريد تغييرها فقط. يبقى كل شيء آخر كما هو. يرفع هذا المثال السقف إلى 100 دولار شهرياً:

```bash cURL theme={"system"}
curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "consumptionLimit": { "usd": 100 }
  }'
```

```python Python theme={"system"}
requests.patch(f"{BASE}/api_keys", headers=HEADERS, json={
    "id": key_id,
    "consumptionLimit": {"usd": 100},
}).raise_for_status()
```

```javascript Node.js theme={"system"}
await fetch(`${BASE}/api_keys`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ id: keyId, consumptionLimit: { usd: 100 } }),
});
```

أرسل أيّاً من هذه الحقول بدلاً من ذلك لإجراء تغييرات أخرى:

| من أجل | أرسل |
| - | - |
| إزالة السقف | `"consumptionLimit": { "usd": null }` |
| إعادة ضبط السقف شهرياً بدلاً من يومياً | `"limitPeriod": "MONTH"` |
| جعل السقف ميزانية لمرة واحدة | `"limitPeriod": "LIFETIME"` |
| تمديد تاريخ انتهاء الصلاحية | `"expiresAt": "2027-12-31"` |
| إزالة تاريخ انتهاء الصلاحية | `"expiresAt": null` |
| قبول الطلبات من خوادمك فقط | `"ipAllowlist": ["11.22.33.0/24"]` |
| قبول الطلبات من أي عنوان IP مجدداً | `"ipAllowlist": []` |
| السماح بالنماذج الخاصة فقط | `"modelPrivacy": "PRIVATE_ONLY"` |
| إعادة تسمية المفتاح | `"description": "cust:acme-prod"` |

تسري قيمة `limitPeriod` الجديدة على الفور، لذا فإن التبديل إلى `LIFETIME` يحتسب كل الإنفاق السابق للمفتاح ضمن السقف. لا يمكن تغيير `apiKeyType`؛ أنشئ مفتاحاً جديداً بدلاً من ذلك.

## إلغاء مفتاح أو تدويره

```bash cURL theme={"system"}
curl -X DELETE \
  "https://api.venice.ai/api/v1/api_keys?id=e28e82dc-9df2-4b47-b726-d0a222ef2ab5" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"
```

```python Python theme={"system"}
requests.delete(f"{BASE}/api_keys", headers=HEADERS, params={"id": key_id}).raise_for_status()
```

```javascript Node.js theme={"system"}
await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });
```

الاستجابة هي `{ "success": true }`. الإلغاء فوري: يتلقى الطلب التالي للمفتاح الخطأ `401 Authentication failed`، ويختفي المفتاح من `GET /api_keys`. تبقى رسومه السابقة في سجل الاستخدام.

لتدوير مفتاح دون انقطاع في الخدمة:

**1. أنشئ المفتاح البديل**

أنشئ مفتاحاً جديداً بالإعدادات نفسها وخزّن قيمته السرية.

**2. انشره**

حوّل تطبيقك إلى استخدام القيمة السرية الجديدة.

**3. ألغِ المفتاح القديم**

بمجرد أن تتوقف قيمة `lastUsedAt` للمفتاح القديم في `GET /api_keys` عن التغيّر، احذفه.

## الأخطاء التي قد يواجهها مستدعو API لديك

| الحالة | الرسالة | ما يجب فعله |
| - | - | - |
| `402` | `API key USD spend limit exceeded...`، أو الرسالة نفسها لـ DIEM | ارفع السقف أو أزله، أو انتظر الفترة التالية. قد يظل لدى الحساب نفسه رصيد. |
| `403` | النموذج غير مسموح به وفقاً لإعداد الخصوصية للمفتاح | استخدم نموذجاً من نوع Private أو TEE أو E2EE، أو غيّر `modelPrivacy`. |
| `403` | `This API key is restricted to configured IP addresses...` | أضف عنوان IP الخاص بالمستدعي إلى `ipAllowlist`. |
| `401` | `Authentication failed` | المفتاح ملغى أو منتهي الصلاحية أو مكتوب بشكل خاطئ. |
| `401` | `Admin API key required` | استدعى مفتاح Inference نقطة نهاية لإدارة المفاتيح أو للفوترة. |
| `429` | `Too many API key creation requests...` | إنشاء المفاتيح محدود بـ 20 مفتاحاً في الدقيقة. انتظر ثم أعد المحاولة. |
| `400` | `Maximum number of active API keys (500) reached...` | ألغِ المفاتيح التي لم تعد تستخدمها، أو تواصل مع الدعم. |

راجع [رموز الأخطاء](https://docs.venice.ai/ar/api-reference/error-codes.md) للاطلاع على القائمة الكاملة.

## أفضل الممارسات

* احتفظ بمفاتيح Admin على خادمك، ولا توزّع سوى مفاتيح Inference.
* امنح كل تطبيق وبيئة وعميل مفتاحاً خاصاً به، بحيث يمكن تتبّع كل منها وإلغاؤه بشكل مستقل.
* ضع معرّفك الخاص في `description`. تستخدمه تحليلات الاستخدام لتسمية المفاتيح.
* حدّد سقف إنفاق وتاريخ انتهاء صلاحية لكل مفتاح تمنحه لشخص آخر، وقيّد المفاتيح المستخدمة بين الخوادم بعناوين IP الخاصة بك باستخدام `ipAllowlist`.

## مرجع API

> [card] [إنشاء مفتاح API](https://docs.venice.ai/ar/api-reference/endpoint/api_keys/create.md)
>
> جميع الحقول المقبولة عند الإنشاء.

> [card] [تحديث مفتاح API](https://docs.venice.ai/ar/api-reference/endpoint/api_keys/update.md)
>
> غيّر الحدود وتاريخ انتهاء الصلاحية والخصوصية وعناوين IP.

> [card] [عرض قائمة مفاتيح API](https://docs.venice.ai/ar/api-reference/endpoint/api_keys/list.md)
>
> كل مفتاح نشط مع استخدامه.

> [card] [حذف مفتاح API](https://docs.venice.ai/ar/api-reference/endpoint/api_keys/delete.md)
>
> ألغِ مفتاحاً.

> [card] [تحليلات الاستخدام](https://docs.venice.ai/ar/api-reference/endpoint/billing/usage-analytics.md)
>
> الإنفاق حسب المفتاح والنموذج واليوم.

> [card] [سجل الاستخدام](https://docs.venice.ai/ar/api-reference/endpoint/billing/usage-history.md)
>
> كل رسم، مع مفتاح API الخاص به.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.