Venice AI API: استدعاءات متوافقة مع OpenAI من curl و Python و n8n

تشغل Venice AI استدعاء API الاستدلال المتوافق مع OpenAI أمام نماذج مفتوحة الوزن وتابعة لجهات خارجية مع الخصوصية المعالجة في الطبقة الوكيل بدلاً من التعامل به لاحقاً. هذه المختبرة تحصل على مفتاح API عامل أول كمال الدردشة في curl و Python و خيارات Venice-only venice_parameters وتوليد الصور وطريقتان للاتصال من n8n.

احصل على مفتاح API

تسجيل الدخول في venice.ai افتح Settings → API (venice.ai/settings/api) ثم Generate New API Key. اختر Inference Only لاستدعاءات نموذج عادي؛ Admin فقط لمفاتيح تدير مفاتيح أخرى. يُظهر Venice المفتاح الكامل مرة — انسخه برأس حوار النسخ ثم خزنه كمتغير بيئة:

export VENICE_API_KEY=your-api-key-here

GET /models يعمل مع أو بدون مفتاح لذا أنه يثبت لا شيء. تحقق مع GET /api_keys/rate_limits بدلاً من ذلك:

curl --request GET \
  --url https://api.venice.ai/api/v1/api_keys/rate_limits \
  --header "Authorization: Bearer $VENICE_API_KEY"

مفتاح العمل يعود طبقتك والأرصدة و data.accessPermitted. 401 مع AUTHENTICATION_FAILED عادة يعني نسخ جزئي أو بادئة غير Bearer مخبأة في القيمة المخزنة أو مسافة زائدة.

طلبك الأول

تفاصيل عنوان URL الأساسي هو ما يسبب محاولات أول: https://api.venice.ai/api/v1 ليس حقل البريد venice.ai.

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-uncensored-1-2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

لأن نقطة النهاية تطبق مواصفات كمال الدردشة OpenAI، OpenAI SDK القياسي يعمل دون تغيير مرة يشير إلى Venice:

import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="zai-org-glm-5",
    messages=[{"role": "user", "content": "Why is privacy important?"}],
)
print(completion.choices[0].message.content)

دليل الهجرة الخاص بـ Venice يطر الكود OpenAI الموجود كتغيير متغيرين: احتفظ OPENAI_API_KEY و OPENAI_BASE_URL (بعض المكتبات لا تزال قراءة OPENAI_API_BASE) وأشير لهم في مفتاح Venice والخاص بك https://api.venice.ai/api/v1. أي أداة تقرأ بالفعل هذان المتغيران التقاط Venice مع لا تغيير الكود.

اختر نموذج دون تشفير معرف

GET /models?type=text قوائم نماذج نصية مع طول السياق و model_spec كائن؛ حذف type بالنسبة النص فقط أو تمرير type=all لكل الكرامة. المدخلات المجدولة للتقاعد تحمل deprecation كائن.

بدلاً من معرف النموذج الخام يمكنك إرسال اسم السمة كـ model. GET /models/traits?type=text إرجاع الخريطة الحالية مثلاً default → zai-org-glm-5-2 و default_reasoning → kimi-k3 و default_code → deepseek-v4-pro-0813. إرسال "model": "default" يقرر لأي نموذج حالياً يحمل أن السمة — نطاق انفجار أصغر من معرف مثبت عند Venice يستحق.

معاملات خاصة بـ Venice

نقطة نهاية كمال الدردشة تقبل جسم OpenAI القياسي بالإضافة إلى كائن إضافي واحد venice_parameters للسلوك خارج مواصفات OpenAI. مع SDKs الرسمي يسافر عبر معامل extra_body الخاص بـ extra_body:

response = client.chat.completions.create(
    model="zai-org-glm-5",
    messages=[{"role": "user", "content": "Latest developments in AI?"}],
    extra_body={
        "venice_parameters": {
            "enable_web_search": "auto",
            "enable_web_citations": True,
        }
    },
)

مفاتيح موثقة جديرة بالمعرفة:

مفاتيح غير معروفة داخل venice_parameters يتم تجاهلها وليس الاعتراضية — خطأ إملائي يعود طبيعي 200 مع الميزة ببساطة لم تنطبق. كتابة النظام المطالبة يسير جنباً إلى جنب مع موجهات Venice الخاصة بها يستخدم نفس التقنية العامة كـ ChatGPT prompting cheat sheet.

بشكل افتراضي الرسالة النظام الخاصة بك مُلحقة بمطالبات Venice الافتراضية موثقة كمضبوطة غير رقابية الاستجابات. ضع "venice_parameters": {"include_venice_system_prompt": false} في نفس جسم الطلب لاستخدام نظام الخاص بك فقط المطالبة بلا شيء من Venice.

Model feature suffix. عندما عميل فقط يدع تختار سلسلة نموذج append معاملات إلى معرف النموذج بدلاً من: "model": "default:enable_web_search=auto&include_venice_system_prompt=false". نفس ميزة سلسلة نموذج مع &.

البث

ضع stream: true لأحداث من الخادم ينتهي في data: [DONE]. stream_options.include_usage يضيف آخر مجموعة الاستخدام:

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5",
    "messages": [{"role": "user", "content": "One sentence about Venice."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

إذا كنت أيضاً تضع venice_parameters.include_search_results_in_stream موثقة كتجريبية نتائج البحث تصل كأول مجموعة مُطلقة بدلاً من الترابط مع محتوى عادي.

توليد الصور

توليد الصور متزامن: طلب واحد رد واحد مع الصورة الحد الأقصى. POST /image/generate API أصلي مع معاملات كاملة؛ POST /images/generations OpenAI-compatible بديل للهجرة OpenAI الصورة الموجودة كود. اسرد نماذج الصور أولاً مع GET /models?type=image ابحث عن صالح model معرف.

curl -X POST https://api.venice.ai/api/v1/image/generate \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "venice-sd35",
    "prompt": "A cinematic photo of a gondola on a canal at blue hour",
    "negative_prompt": "blurry, low quality, watermark",
    "width": 1024,
    "height": 1024,
    "format": "webp"
  }'

حقول موثقة تشمل prompt (مطلوب) و width/height نماذج pixel-based و aspect_ratio/resolution لنماذج نسبة-based (qwen-image-2 و gpt-image-2 و nano-banana-2) و format (jpeg/png/webp) و variants (1–4) و return_binary و safe_mode و seed و style_preset. عائلات النموذج لا تتفق على التحجيم: عائلة Qwen Image ترفض width/height مع 400 قول لاستخدام aspect_ratio بدلاً من ذلك. تحقق model_spec.constraints من قائمة النماذج أولاً.

حدود الرفع

الأرقام الافتراضية لكل-tier موثقة كمرجع لكن Venice تقول اعامل نقطة نهاية المفتاح الخاص بك كموثوق:

curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"

نماذج نصية وتضمين يجلس في أربعة نطاقات حجم منشورة مع طلب مختلف/رموز-في-الدقيقة حدود؛ صورة upscale inpaint كلام وتحويل نماذج لديها الحد الأقصى المنفصل. عند 429 x-ratelimit-reset-requests يعطي Unix طابع زمني (بالملي ثانية) عند النافذة يوضح. اثنا إضافي الميزانيات ينطبقان بغض النظر عن التحقق: أكثر من 50 طلب فاشل أو أكثر من 200 طلب لميزة نموذج غير مدعومة في أي 30 ثانية نافذة.

معالجة البيانات والإيقاف ما وثقت

يصف صفحة الخصوصية الخاصة بـ Venice الوكيل إعادة الطلبات عبر TLS دون تخزين المحتوى للاستدلال العادي. كل نموذج ثم يضيف واحد من أربع أوضاع الخصوصية: Anonymous (الهوية محتفظ بها من المزود محتوى لا يزال يراه) و Private (عقد يتم إنفاذ الاحتفاظ الصفري) و TEE (معزول بالأجهزة مع الشهادة البعيدة) أو E2EE (مشفرة إلى enclave معين قبل مغادرة عميل). توثق Venice أيضاً أنها قد تعالج البيانات الوصفية التشغيلية بشكل منفصل — الطوابع الزمنية وعدد الرموز والفواتير و IP العنوان — لـ auth والفواتير ومنع الإساءة. “لا نحتفظ نص المطالبة” و “لا نسجل لا شيء في الإطلاق” ادعاءات مختلفة؛ تحقق من وضع الخصوصية من النموذج تستدعي.

عند الإيقاف Venice الوثائق 7–15 يومات إشعار وإيقاف تحذير في ردود API خلال ذلك النافذة و auto-routing إلى مماثل استبدال بعد الغروب أو 410 Gone عندما التوجيه لا يمكن. نموذج وصل من خلال سمة مثل default_code يحصل على إعادة تعيين السمة تلقائياً.

صولها في n8n

بيانات اعتماد OpenAI المدمج في n8n لديها Base URL حقل (افتراضي https://api.openai.com/v1) إلى جانب API Key. هذا نوع بيانات اعتماد واحد يدعم عقدة OpenAI و OpenAI Chat Model sub-node الذي يستخدمه AI Agent و Embeddings OpenAI و LM OpenAI.

1. Credentials → Add Credential → OpenAI.
2. API Key: مفتاح Venice الخاص بك. Organization ID: اترك فارغة.
3. Base URL: https://api.venice.ai/api/v1.
4. احفظ — n8n اختبار بيانات الاعتماد ضد /models على هذا القاعدة URL.

أضف عقدة OpenAI Chat Model وإرفاق بيانات اعتماد هذه. منتقى نموذجه يدعو GET /models ضد قاعدة URL مكونة لذا معرفات نموذج Venice تحمل مرة يشير بيانات الاعتماد عند Venice. لكل عقدة Options → Base URL يتجاوز موجود أيضاً فتأخذ أولوية على بيانات الاعتماد إذا سير عمل واحد يحتاج نقطة نهاية مختلفة. زوج Chat Model عقدة مع عقدة AI Agent وأداة مغطى في أول مختبرة n8n سير العمل؛ استدعاء أداة المفاهيم في عام موجود في ما هو ذكاء اصطناعي agentive وصولها خادم MCP كأداة موجود في MCP يُفسَّر الخوادم.

لأي شيء عقدة chat-model لا تغطي — توليد الصور استدعاء البث الخام — استخدم HTTP Request عقدة. ضع Authentication → Generic Credential Type ثم Generic Auth Type → Bearer Auth والصق فقط الرمز (لا Bearer بادئة)؛ n8n يبني Authorization: Bearer <token> رأس. ويشير URL عند https://api.venice.ai/api/v1/image/generate الطريقة POST:

{
  "model": "venice-sd35",
  "prompt": "A dark server room with a single glowing rack",
  "width": 1024,
  "height": 1024,
  "format": "webp"
}

لـ curl استيراد وإعادات المحاولة و HTTP عام Request عقدة سلوك انظر أول مختبرة n8n سير العمل؛ بالنسبة تختار n8n عبر أداة الأتمتة SaaS في أول مكان انظر n8n مقابل Make مقابل Zapier.

الأخطاء

Keys في تصدير سير العمل JSON. n8n متاجر بيانات اعتماد أسماء والمعرفات في JSON المصدرة وليس القيمة السرية. لكن HTTP Request عقدة مبني من المعجون curl الأمر يمكن أن دمج Authorization: Bearer sk-... رأس مباشرة في عقدة المعاملات. اقرأ JSON المصدرة قبل مشاركته والتفضيل نوع بيانات اعتماد عام / Bearer Auth حتى السري يعيش في بيانات اعتماد ليس في معاملات.

Hardcoding معرف نموذج يحصل على استحقاق. قد يعود معرف محدد مشفرة 410 Gone بعد نافذة إشعار إذا Venice يمكن لا auto-route هذا. يراقب deprecation حقل عند GET /models أو استدعاء سمة مثل default لذا Venice الاسم المستعار الحل يمتص التغيير.

venice.ai بدلاً من api.venice.ai. إرجاع المجال الحقل تطبيق الويب HTML أو 404 ل استدعاءات API وليس رد JSON خطأ — سهل الخطأ لمفتاح السيء عند فعلاً المضيف خاطئ.

افتراض “خاص” يعني سجل لا شيء على الإطلاق. يفصل Venice محتوى المطالبة/الاستجابة (لا احتفظ بها للاستدلال العادي) من البيانات الوصفية التشغيلية يقول قد يعالج لا يزال. وضع الخصوصية هو الرافعة مقابل محتوى؛ لا ادعاء صفر البيانات الوصفية.

الأخطاء الإملائية الصامتة في venice_parameters. مفاتيح غير معروفة يتم تجاهلها وليس مرفوضة. الكود المكتوب بشكل خاطئ enabled_web_search يعود 200 مع البحث ببساطة لم تطبق — التحقق من السلوك تغيير وليس مجرد رمز الحالة.

الأسئلة الشائعة

ما هو عنوان URL الأساسي الذي أستخدمه لـ Venice AI API؟

https://api.venice.ai/api/v1 وليس venice.ai. المجال venice.ai يقدم تطبيق الويب لذا طلبات هناك إرجاع صفحة HTML أو 404. أشر OpenAI SDK الخاص بك base_url/baseURL عند api نطاق فرعي احتفظ /api/v1 لاحقة وأرسل مفتاحك كـ رمز Bearer.

هل يمكنني استخدام OpenAI SDK مع Venice AI أم أحتاج إلى عميل منفصل؟

تستخدم نفس OpenAI SDK. أنشئ العميل باستخدام مفتاح Venice API وعنوان URL الأساسي لـ Venice بدلاً من OpenAI. كمال الدردشة والبث واستدعاءات الأدوات تعمل بنفس الطريقة؛ خيارات Venice فقط تسافر عبر معامل extra_body الخاص بـ SDK كـ كائن venice_parameters.

ماذا تتحكم venice_parameters فعلاً؟

سلوك Venice فقط خارج مواصفات OpenAI: البحث المدمج على الويب (enable_web_search) واقتباسات المصادر وكشط عنوان URL وشخصيات Venice (character_slug) والتفكير في نموذج الاستدلال وما إذا كانت مطالبة النظام الافتراضية الخاصة بـ Venice مُلحقة بالخاص بك (include_venice_system_prompt). المفاتيح المجهولة داخل الكائن تُتجاهل بصمت لذا الخطأ الإملائي يفشل بهدوء بدلاً من خطأ.

هل Venice AI يحتفظ بمطالباتي؟

وفقاً لتوثيق Venice تعيد الوكيل الطلبات عبر TLS دون تخزين محتوى المطالبة أو الرد للاستدلال العادي وكل نموذج يضيف واحد من أربع أوضاع الخصوصية: Anonymous و Private (يتم إنفاذ الاحتفاظ الصفري العقد) و TEE (معزول بالأجهزة) أو E2EE (مشفرة لـ Enclave معين). يقول Venice قد يحتفظ بـ البيانات الوصفية التشغيلية مثل الطوابع الزمنية وعدد الرموز وبيانات الفواتير منفصلة عن المحتوى نفسه.

هل يمكنني توصيل Venice AI بـ n8n كنموذج دردشة؟

نعم. أنشئ بيانات اعتماد OpenAI في n8n والصق مفتاح Venice في API Key وعين Base URL إلى https://api.venice.ai/api/v1. تلك بيانات الاعتماد مشتركة بواسطة عقدة OpenAI و OpenAI Chat Model sub-node و Embeddings OpenAI و LM OpenAI. لأي استدعاء خام أو توليد الصور استخدم عقدة HTTP Request مع نوع بيانات اعتماد عام → Bearer Auth بدلاً من ذلك.