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

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

إنشاء

أصدِر مفتاحاً بسقف إنفاق

تتبّع

اطّلع على ما ينفقه كل مفتاح

تغيير

ارفع السقف أو مدّد تاريخ انتهاء الصلاحية

إلغاء

أوقف مفتاحاً على الفور

كيف يعمل

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

Inferencecust:acme50$ / شهرياًالنماذج الخاصة فقط

Inferencecust:globex5$ / شهرياًمن 11.22.33.0/24 فقط

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

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

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

أنشئ أول مفتاح Admin لك من لوحة التحكم: اتّبع دليل إنشاء مفتاح API واختر Admin كنوع للمفتاح. احتفظ به في مخزن أسرار على جانب الخادم، وليس في الكود الذي يعمل على جانب العميل أبداً.

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

export VENICE_ADMIN_KEY="your-admin-key"

import os
import requests

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

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:

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

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

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;

Response

{
  "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": []
  }
}

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 مفتاح نشط. تواصل مع الدعم إذا كنت بحاجة إلى المزيد.

هل تبني وكيلاً؟ يمكن لمحفظة تحتوي على VVV مُودَع (staked) على شبكة Base إصدار مفتاحها الخاص دون حساب Venice. راجع إنشاء مفتاح API للوكيل المستقل.

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

لمعرفة	استدعِ	اقرأ
ما أنفقه مفتاح واحد في هذه الفترة	`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`

مفتاح واحد

curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

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

const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();

Response (trimmed)

{
  "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 دقائق.

cURL

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

Response (trimmed)

{
  "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 بدلاً من ذلك.

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"

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 ما تبقّى له لإنفاقه.

cURL

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 دولار شهرياً:

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

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

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؛ أنشئ مفتاحاً جديداً بدلاً من ذلك.

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

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

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

await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });

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

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

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

انشره

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

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

بمجرد أن تتوقف قيمة 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...`	ألغِ المفاتيح التي لم تعد تستخدمها، أو تواصل مع الدعم.

راجع رموز الأخطاء للاطلاع على القائمة الكاملة.

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

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

مرجع API

إنشاء مفتاح API

جميع الحقول المقبولة عند الإنشاء.

تحديث مفتاح API

غيّر الحدود وتاريخ انتهاء الصلاحية والخصوصية وعناوين IP.

عرض قائمة مفاتيح API

كل مفتاح نشط مع استخدامه.

حذف مفتاح API

ألغِ مفتاحاً.

تحليلات الاستخدام

الإنفاق حسب المفتاح والنموذج واليوم.

سجل الاستخدام

كل رسم، مع مفتاح API الخاص به.

التوثيق

البدء

النص والدردشة

الصورة

الفيديو

الصوت

البحث وRAG

الوكلاء والتكاملات

أدوات البرمجة

أدوات الوكلاء

حِزم SDK والأُطر

إنشاء

تتبّع

تغيير

إلغاء

كيف يعمل

إنشاء مفتاح

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

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

مفتاح واحد

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

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

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

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

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

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

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

مرجع API

إنشاء مفتاح API

تحديث مفتاح API

عرض قائمة مفاتيح API

حذف مفتاح API

تحليلات الاستخدام

سجل الاستخدام

إنشاء

تتبّع

تغيير

إلغاء

​كيف يعمل

​إنشاء مفتاح

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

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

​مفتاح واحد

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

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

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

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

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

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

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

​مرجع API

إنشاء مفتاح API

تحديث مفتاح API

عرض قائمة مفاتيح API

حذف مفتاح API

تحليلات الاستخدام

سجل الاستخدام

كيف يعمل

إنشاء مفتاح

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

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

مفتاح واحد

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

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

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

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

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

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

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

مرجع API