> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-6ce01df5.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# مقدمة

> التوثيق المرجعي لـ Venice API

تقدم Venice API واجهات REST وstreaming قائمة على HTTP لبناء تطبيقات الذكاء الاصطناعي بنماذج بدون قيود واستدلال خاص. يمكنك الإبداع مع توليد النصوص وإنشاء الصور و embeddings والمزيد، كل ذلك دون سياسات محتوى مقيِّدة. أمثلة التكامل وحِزَم SDK متاحة في [التوثيق](/overview/getting-started). مرجع API الخاص بنا متوفر أيضًا كـ [مواصفات OpenAPI YAML.](https://api.venice.ai/doc/api/swagger.yaml)

## المصادقة

تستخدم Venice API مفاتيح API للمصادقة. أنشئ وأدر مفاتيح API الخاصة بك في [إعدادات API الخاصة بك](https://venice.ai/settings/api).

تتطلب جميع طلبات API مصادقة HTTP Bearer:

```
Authorization: Bearer VENICE_API_KEY
```

<Note>
  مفتاح API الخاص بك سري. لا تشاركه أو تكشفه في أي كود من جانب العميل.
</Note>

## التوافق مع OpenAI

تنفّذ Venice API مواصفات OpenAI API، مما يضمن التوافق مع عملاء وأدوات OpenAI الموجودة. يتيح لك هذا التكامل مع Venice باستخدام واجهة OpenAI المألوفة بينما تصل إلى ميزات Venice الفريدة ونماذجها بدون قيود.

### الإعداد

اضبط عميلك لاستخدام base URL الخاص بـ Venice (`https://api.venice.ai/api/v1`) وقم بإرسال طلبك الأول:

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "venice-uncensored",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```javascript JavaScript theme={"system"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.VENICE_API_KEY,
    baseURL: "https://api.venice.ai/api/v1",
  });

  const response = await client.chat.completions.create({
    model: "venice-uncensored",
    messages: [{ role: "user", content: "Hello!" }]
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python theme={"system"}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ.get("VENICE_API_KEY"),
      base_url="https://api.venice.ai/api/v1"
  )

  response = client.chat.completions.create(
      model="venice-uncensored",
      messages=[{"role": "user", "content": "Hello!"}]
  )

  print(response.choices[0].message.content)
  ```
</CodeGroup>

## ميزات خاصة بـ Venice

### System Prompts

توفر Venice system prompts افتراضية مصمَّمة لضمان استجابات النماذج بدون قيود وطبيعية. لديك خياران للتعامل مع system prompts:

1. **السلوك الافتراضي**: تتم إضافة system prompts الخاصة بك إلى الافتراضات الخاصة بـ Venice
2. **السلوك المخصص**: عطّل system prompts الخاصة بـ Venice بالكامل

#### تعطيل system prompts الخاصة بـ Venice

استخدم خيار `venice_parameters` لإزالة system prompts الافتراضية لـ Venice:

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "venice-uncensored",
      "messages": [
        {"role": "system", "content": "Your custom system prompt"},
        {"role": "user", "content": "Why is the sky blue?"}
      ],
      "venice_parameters": {
        "include_venice_system_prompt": false
      }
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const completion = await client.chat.completions.create({
    model: "venice-uncensored",
    messages: [
      {
        role: "system",
        content: "Your custom system prompt",
      },
      {
        role: "user",
        content: "Why is the sky blue?",
      },
    ],
    venice_parameters: {
      include_venice_system_prompt: false,
    },
  });
  ```

  ```python Python theme={"system"}
  response = client.chat.completions.create(
      model="venice-uncensored",
      messages=[
          {"role": "system", "content": "Your custom system prompt"},
          {"role": "user", "content": "Why is the sky blue?"}
      ],
      extra_body={
          "venice_parameters": {
              "include_venice_system_prompt": False
          }
      }
  )
  ```
</CodeGroup>

### معاملات Venice

كائن `venice_parameters` يسمح لك بالوصول إلى ميزات خاصة بـ Venice غير متوفرة في OpenAI API القياسية:

| المعامل                              | النوع   | الوصف                                                                                                                                                                                                                                                                                                           | الافتراضي |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `character_slug`                     | string  | معرّف شخصية (slug) لشخصية Venice عامة (يمكن اكتشافه كـ "Public ID" في صفحة الشخصية المنشورة)                                                                                                                                                                                                                    | -         |
| `strip_thinking_response`            | boolean | إزالة كتل `<think></think>` من الاستجابة (النماذج التي تستخدم تنسيق علامة `<think>` القديم). راجع [نماذج الاستدلال](/guides/features/reasoning-models).                                                                                                                                                         | `false`   |
| `disable_thinking`                   | boolean | على نماذج الاستدلال المدعومة، عطّل التفكير وإزالة كتل `<think></think>` من الاستجابة                                                                                                                                                                                                                            | `false`   |
| `enable_web_search`                  | string  | تفعيل البحث في الويب لهذا الطلب (`off`، `on`، `auto` - يتم التفعيل التلقائي بناءً على تقدير النموذج)<br />ينطبق تسعير إضافي قائم على الاستخدام، راجع [التسعير](/overview/pricing#web-search-and-scraping).                                                                                                      | `off`     |
| `enable_web_scraping`                | boolean | تفعيل استخراج محتوى الويب لما يصل إلى 5 عناوين URL مكتشفة في رسالة المستخدم. المحتوى المُستخرَج يعزز الاستجابات ويتجاوز البحث في الويب. يتم احتساب الفوترة فقط لعناوين URL التي تم استخراج محتواها بنجاح.<br />ينطبق تسعير إضافي قائم على الاستخدام، راجع [التسعير](/overview/pricing#web-search-and-scraping). | `false`   |
| `enable_x_search`                    | boolean | تفعيل بحث xAI الأصلي (الويب + X/Twitter) لنماذج Grok المدعومة (مثل `grok-4-20-beta`). يوفر نتائج بحث بجودة أعلى باستخدام بنية بحث xAI التحتية. عند التفعيل، يتم تجاوز البحث القياسي في الويب من Venice.<br />ينطبق تسعير إضافي قائم على الاستخدام، راجع [التسعير](/overview/pricing#web-search-and-scraping).   | `false`   |
| `enable_web_citations`               | boolean | عند تفعيل البحث في الويب، اطلب من الـ LLM الاستشهاد بمصادره باستخدام تنسيق `[REF]0[/REF]`                                                                                                                                                                                                                       | `false`   |
| `include_search_results_in_stream`   | boolean | تجريبي: تضمين نتائج البحث في الـ stream كأول قطعة مُرسَلة                                                                                                                                                                                                                                                       | `false`   |
| `return_search_results_as_documents` | boolean | إظهار نتائج البحث في استدعاء أداة متوافق مع OpenAI باسم `venice_web_search_documents` لتكامل LangChain                                                                                                                                                                                                          | `false`   |
| `include_venice_system_prompt`       | boolean | ما إذا كان يتم تضمين system prompts الافتراضية الخاصة بـ Venice إلى جانب system prompts المحددة                                                                                                                                                                                                                 | `true`    |

<Note>
  يمكن أيضًا تحديد هذه المعاملات كلاحقات للنموذج تُضاف إلى اسم النموذج (مثل `zai-org-glm-5:enable_web_search=auto`). راجع [لواحق ميزات النموذج](/api-reference/endpoint/chat/model_feature_suffix) للحصول على التفاصيل.
</Note>

### Prompt Caching

تدعم Venice تخزين الـ prompt مؤقتًا على نماذج مختارة لتقليل زمن الاستجابة والتكاليف للمحتوى المتكرر. بالنسبة للنماذج المدعومة، تقوم Venice تلقائيًا بتخزين system prompts مؤقتًا — لا حاجة لتغييرات في الكود. يمكنك أيضًا وضع علامة يدويًا على المحتوى للتخزين المؤقت باستخدام خاصية `cache_control` في محتوى الرسالة.

| المعامل            | النوع  | الوصف                                                                                                                                                                          |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt_cache_key` | string | تلميح توجيه اختياري لتحسين معدلات إصابة الكاش. عند توفيره، توجه Venice الطلبات إلى نفس بنية الـ backend التحتية، مما يزيد من احتمال إصابات الكاش عبر المحادثات متعددة الجولات. |

راجع [Prompt Caching](/guides/features/prompt-caching) للحصول على تفاصيل حول كيفية عمل التخزين المؤقت، والفوترة، وأفضل الممارسات.

## مرجع رؤوس الاستجابة

تتضمن جميع استجابات Venice API رؤوس HTTP توفّر بيانات وصفية حول الطلب، وحدود المعدل، ومعلومات النموذج، ورصيد الحساب. بالإضافة إلى رموز الأخطاء المُعادة من استجابات API، يمكنك فحص هذه الرؤوس للحصول على المعرّف الفريد لطلب API معين، ومراقبة حدود المعدل، وتتبع رصيد حسابك.

توصي Venice بتسجيل معرّفات الطلب (header `CF-RAY`) في عمليات النشر الإنتاجية لاستكشاف الأخطاء بشكل أكثر كفاءة مع فريق الدعم لدينا، إذا اقتضت الحاجة.

يوفر الجدول أدناه مرجعًا شاملًا لجميع الرؤوس التي قد تواجهها:

| Header                                      | النوع  | الغرض                                                                            | متى تُعاد                                              |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **رؤوس HTTP القياسية**                      |        |                                                                                  |                                                        |
| `Content-Type`                              | string | نوع MIME لجسم الاستجابة (`application/json`، `text/csv`، `image/png`، إلخ)       | دائمًا                                                 |
| `Content-Encoding`                          | string | الترميز المستخدم لضغط جسم الاستجابة (`gzip`، `br`)                               | عندما يرسل العميل header `Accept-Encoding`             |
| `Content-Disposition`                       | string | كيف يجب عرض المحتوى (مثل `attachment; filename=export.csv`)                      | عند تنزيل الملفات أو التصديرات                         |
| `Date`                                      | string | طابع زمني بتنسيق RFC 7231 عند توليد الاستجابة                                    | دائمًا                                                 |
| **تعريف الطلب**                             |        |                                                                                  |                                                        |
| `CF-RAY`                                    | string | معرّف فريد لطلب API هذا، يُستخدم لاستكشاف الأخطاء وطلبات الدعم                   | دائمًا                                                 |
| `x-venice-version`                          | string | الإصدار/المراجعة الحالية لخدمة Venice API (مثل `20250828.222653`)                | دائمًا                                                 |
| `x-venice-timestamp`                        | string | طابع زمني للخادم عند معالجة الطلب (تنسيق ISO 8601)                               | عند تفعيل تتبع الطابع الزمني                           |
| `x-venice-host-name`                        | string | اسم المضيف للخادم الذي عالج الطلب                                                | استجابات الأخطاء وسيناريوهات التصحيح                   |
| **معلومات النموذج**                         |        |                                                                                  |                                                        |
| `x-venice-model-id`                         | string | المعرّف الفريد لنموذج الذكاء الاصطناعي المستخدم للطلب (مثل `venice-01-lite`)     | endpoints الاستدلال التي تستخدم نماذج الذكاء الاصطناعي |
| `x-venice-model-name`                       | string | الاسم الودي/المعروض لنموذج الذكاء الاصطناعي المستخدم (مثل `Venice Lite`)         | endpoints الاستدلال التي تستخدم نماذج الذكاء الاصطناعي |
| `x-venice-model-router`                     | string | خدمة الـ Router/Backend التي تعاملت مع استدلال النموذج                           | endpoints الاستدلال عند توفر معلومات التوجيه           |
| `x-venice-model-deprecation-warning`        | string | رسالة تحذير للنماذج المُجدوَلة للإيقاف                                           | عند استخدام نموذج مُهجَر                               |
| `x-venice-model-deprecation-date`           | string | التاريخ الذي سيُهجَر فيه النموذج (تاريخ ISO 8601)                                | عند استخدام نموذج مُهجَر                               |
| **معلومات حدود المعدل**                     |        |                                                                                  |                                                        |
| `x-ratelimit-limit-requests`                | number | الحد الأقصى لعدد الطلبات المسموح بها في النافذة الزمنية الحالية                  | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-remaining-requests`            | number | عدد الطلبات المتبقية في النافذة الزمنية الحالية                                  | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-reset-requests`                | number | طابع Unix الزمني عند إعادة تعيين حد معدل الطلبات                                 | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-limit-tokens`                  | number | الحد الأقصى لعدد الـ tokens (prompt + completion) المسموح به في النافذة الزمنية  | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-remaining-tokens`              | number | عدد الـ tokens المتبقية في النافذة الزمنية الحالية                               | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-reset-tokens`                  | number | المدة بالثواني حتى إعادة تعيين حد معدل الـ tokens                                | جميع الطلبات المُصادَقة                                |
| `x-ratelimit-type`                          | string | نوع حد المعدل المُطبَّق (`user`، `api_key`، `global`)                            | عندما يتم فرض حد المعدل                                |
| **رؤوس التقسيم على صفحات**                  |        |                                                                                  |                                                        |
| `x-pagination-limit`                        | number | عدد العناصر لكل صفحة                                                             | endpoints مُقسَّمة على صفحات                           |
| `x-pagination-page`                         | number | رقم الصفحة الحالية (يبدأ من 1)                                                   | endpoints مُقسَّمة على صفحات                           |
| `x-pagination-total`                        | number | العدد الإجمالي للعناصر عبر جميع الصفحات                                          | endpoints مُقسَّمة على صفحات                           |
| `x-pagination-total-pages`                  | number | العدد الإجمالي للصفحات                                                           | endpoints مُقسَّمة على صفحات                           |
| **معلومات رصيد الحساب**                     |        |                                                                                  |                                                        |
| `x-venice-balance-diem`                     | string | رصيد DIEM token الخاص بك قبل معالجة الطلب                                        | جميع الطلبات المُصادَقة                                |
| `x-venice-balance-usd`                      | string | رصيد الاعتمادات بالدولار الأمريكي قبل معالجة الطلب                               | جميع الطلبات المُصادَقة                                |
| **رؤوس أمان المحتوى**                       |        |                                                                                  |                                                        |
| `x-venice-is-blurred`                       | string | يشير إلى ما إذا تم تمويه الصورة المُولَّدة بسبب سياسات المحتوى (`true`/`false`)  | توليد الصور مع تفعيل Safe Venice                       |
| `x-venice-is-content-violation`             | string | يشير إلى ما إذا كان المحتوى ينتهك سياسات محتوى Venice (`true`/`false`)           | endpoints توليد المحتوى                                |
| `x-venice-is-adult-model-content-violation` | string | يشير إلى ما إذا كان المحتوى ينتهك سياسات محتوى النماذج للبالغين (`true`/`false`) | endpoints توليد الصور                                  |
| `x-venice-contains-minor`                   | string | يشير إلى ما إذا كانت الصورة تحتوي على قاصرين (`true`/`false`)                    | endpoints تحليل الصور مع اكتشاف العمر                  |
| **معلومات العميل**                          |        |                                                                                  |                                                        |
| `x-venice-middleface-version`               | string | إصدار عميل Venice middleface                                                     | الطلبات من عملاء Venice middleface                     |
| `x-venice-mobile-version`                   | string | إصدار عميل تطبيق Venice للهاتف المحمول                                           | الطلبات من تطبيقات الهاتف المحمول                      |
| `x-venice-request-timestamp-ms`             | number | طابع زمني للطلب مقدَّم من العميل بالميلي ثانية                                   | عندما يقدم العميل طابع زمني في الطلب                   |
| `x-venice-control-instance`                 | string | معرّف instance التحكم للتصحيح                                                    | endpoints توليد الصور للتصحيح                          |
| **رؤوس المصادقة**                           |        |                                                                                  |                                                        |
| `x-auth-refreshed`                          | string | يشير إلى أنه تم تحديث token المصادقة أثناء الطلب (`true`/`false`)                | عند تحديث tokens المصادقة تلقائيًا                     |
| `x-retry-count`                             | number | عدد محاولات إعادة المحاولة للطلب                                                 | عند حدوث إعادة محاولات للطلب                           |

### ملاحظات مهمة

* **حالة أحرف اسم Header**: رؤوس HTTP غير حساسة لحالة الأحرف، لكن Venice تستخدم أحرفًا صغيرة مع شَرَطات للتناسق
* **القيم النصية**: قيم Boolean في الرؤوس تُعاد كسلاسل نصية (`"true"` أو `"false"`)
* **القيم الرقمية**: قد تُعاد الأرقام الكبيرة وقيم الرصيد كسلاسل نصية لمنع فقدان الدقة
* **الرؤوس الاختيارية**: لا تُعاد جميع الرؤوس في كل استجابة؛ يعتمد الوجود على endpoint وسياق الطلب
* **الضغط**: استخدم `Accept-Encoding: gzip, br` في الطلبات لتلقي استجابات مضغوطة عند الدعم

### مثال: الوصول إلى رؤوس الاستجابة

```javascript theme={"system"}
// بعد إجراء طلب API، يمكن الوصول إلى الرؤوس من كائن الاستجابة
const requestId = response.headers.get('CF-RAY');
const remainingRequests = response.headers.get('x-ratelimit-remaining-requests');
const remainingTokens = response.headers.get('x-ratelimit-remaining-tokens');
const usdBalance = response.headers.get('x-venice-balance-usd');

// التحقق من تحذيرات إيقاف النماذج
const deprecationWarning = response.headers.get('x-venice-model-deprecation-warning');
if (deprecationWarning) {
  console.warn(`Model Deprecation: ${deprecationWarning}`);
}
```

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

1. **حدود المعدل**: راقب رؤوس `x-ratelimit-remaining-requests` و `x-ratelimit-remaining-tokens` ونفّذ exponential backoff
2. **مراقبة الرصيد**: تتبع رؤوس `x-venice-balance-usd` و `x-venice-balance-diem` لتجنب انقطاع الخدمة
3. **System Prompts**: اختبر مع وبدون system prompts الخاصة بـ Venice للعثور على الأنسب لحالة استخدامك
4. **مفاتيح API**: احتفظ بمفاتيح API الخاصة بك آمنة وقم بتدويرها بانتظام
5. **تسجيل الطلبات**: سجّل قيم header `CF-RAY` لاستكشاف الأخطاء مع الدعم
6. **إيقاف النماذج**: تحقق من رؤوس `x-venice-model-deprecation-warning` عند استخدام النماذج

## الاختلافات عن OpenAI API

بينما تحافظ Venice على توافق عالٍ مع مواصفات OpenAI API، هناك بعض الاختلافات الرئيسية:

1. **venice\_parameters**: تكوينات إضافية مثل `enable_web_search` و `character_slug` و `strip_thinking_response` لوظائف ممتدة
2. **System Prompts**: تضيف Venice system prompts الخاصة بك إلى الافتراضات التي تُحسِّن للاستجابات بدون قيود (عطّل بـ `include_venice_system_prompt: false`)
3. **منظومة النماذج**: تقدم Venice [قائمة نماذجها](/overview/models) الخاصة بما في ذلك النماذج بدون قيود ونماذج الاستدلال - استخدم معرّفات نماذج Venice بدلًا من تعيينات OpenAI
4. **رؤوس الاستجابة**: رؤوس فريدة لتتبع الرصيد (`x-venice-balance-usd` و `x-venice-balance-diem`)، وتحذيرات إيقاف النماذج، وأعلام أمان المحتوى
5. **سياسات المحتوى**: سياسات أكثر تسامحًا مع نماذج بدون قيود مخصصة وتصفية محتوى اختيارية

## استقرار API

تحافظ Venice على التوافق الخلفي لـ v1 endpoints والمعاملات. لسياسة دورة حياة النموذج، وإشعارات الإيقاف، وإرشادات الانتقال، راجع [الإيقافات](/overview/deprecations).

## مواصفات OpenAPI والبيانات الخام

للوصول البرمجي إلى وثائق وبيانات Venice API — بما في ذلك الاستخدام مع RAG (Retrieval-Augmented Generation) — تتوفر الموارد التالية:

* [مواصفات OpenAPI (YAML)](https://api.venice.ai/doc/api/swagger.yaml) — مواصفات API الكاملة بتنسيق YAML
* [مصدر وثائق API](https://github.com/veniceai/api-docs/archive/refs/heads/main.zip) — جميع صفحات التوثيق (تنسيق `.mdx`) كأرشيف قابل للتنزيل

***

<sub>الحقول في الطلب التي لم تُذكَر في هذا التوثيق قد تُمرَّر، لكنها غير مُتحقَّقة ولا مضمونة العمل.</sub>