الأسئلة الشائعة
أكثر الأسئلة شيوعًا حول واجهة برمجة تطبيقات CloudZIR. إن لم يكن سؤالكم من بينها، راسلونا من Help & Feedback.
البداية#
هل يلزم اشتراك؟#
لا. واجهة API مدفوعة مسبقًا : تشحنون محفظة بالدينار وكل طلب يخصم منها. بلا التزام، بلا رسوم ثابتة، بلا تاريخ انتهاء صلاحية للرصيد.
هل يمكنني استخدام حساب الدردشة الخاص بي؟#
نعم، إنه نفس الحساب. سجّلوا الدخول على plateforme.cloudzir.com بمعرّفات ai.cloudzir.com. غير أن محفظة API منفصلة عن استخدام الدردشة.
هل توجد أرصدة مجانية؟#
ليس اليوم : يبدأ الحساب من الصفر ويلزم شحن أول لاستدعاء واجهة API. إن فُتح عرض ترحيبي لاحقًا، سيُضاف تلقائيًا وسيكون مرئيًا في Billing كأي حركة أخرى.
الفوترة#
كيف يُحسب سعر طلب ما؟#
رموز الإدخال × سعر الإدخال + رموز الإخراج × سعر الإخراج، بناءً على
أسعار المليون رمز في صفحة
النماذج والأسعار. عدّ الرموز المستخدم هو الذي
يُعيده النموذج في usage. رموز الإدخال المخدومة من الذاكرة المؤقتة
تُفوتَر بسعر أقل بكثير (التفاصيل).
هل يُفوتَر طلب في حالة خطأ؟#
لا بالنسبة لأخطاء 4xx و5xx التي لم تنتج أي نص (400، 401، 402، 404، 429، 503). التوليد المقطوع أثناء البث المباشر يُفوتَر عن الجزء المُنتَج.
هل يمكن أن يصبح رصيدي سالبًا؟#
بشكل هامشي : يتم الخصم بعد الاستجابة، لذا فإن عدة طلبات مُطلَقة في آنٍ
واحد برصيد شبه معدوم قد تجعله ينزل قليلًا تحت الصفر. تُرفض الاستدعاءات
التالية عندئذٍ بالرمز 402 حتى الشحن.
هل يمكنني الدفع بالدينار؟#
نعم. الأسعار والمحفظة والشحن كلها بالدينار الجزائري (DA). تظهر وسائل الدفع المقترحة في صفحة Top up على المنصة.
هل لديّ فاتورة؟#
السجل الكامل للشحنات والحركات موجود في Billing، قابل للتصدير بصيغة CSV. لمستند اسمي برأسية (شركة، رقم تعريف جبائي)، اطلبوه من Help & Feedback.
تقني#
هل ستعمل شيفرتي المكتوبة لـOpenAI؟#
نعم، بالنسبة إلى نقاط النهاية والمعاملات الموثقة هنا : غيّروا base_url إلى
https://api.cloudzir.com/v1، والمفتاح، واسم النموذج. بعض الحقول تُقبل ثم تُتجاهل أو
تُرفض، وتوضح صفحة المرجع الخاصة بكل واجهة ذلك. والأمر نفسه لشيفرة مكتوبة لـAnthropic مع
https://api.cloudzir.com/anthropic.
ما النماذج المختبئة خلف Mina؟#
Mina خدمة، وليست نموذجًا واحدًا : يُوجَّه كل طلب إلى محرك متاح، مع سلسلة احتياطية تلقائية عند حدوث عطل. تتطور هذه التركيبة لتحسين الجودة وزمن الاستجابة والتوافر، دون أي تغيير في API أو في السعر من جانبكم. تُعيد الاستجابات دائمًا اسم Mina المطلوب.
هل يمكنني استدعاء واجهة API من متصفح؟#
تقنيًا نعم، لكن لا تفعلوا ذلك : فذلك سيعرّض مفتاحكم لكل زوّاركم. مروا عبر خادمكم، الذي يحتفظ بالمفتاح وينقل الطلبات.
هل الاستجابات حتمية (deterministic)؟#
لا. حتى مع temperature: 0، قد يختلف استدعاءان متطابقان قليلًا.
يُقبَل المعامل seed ثم يُتجاهل : ليس له أي أثر.
ما أقصى مدة لطلب ما؟#
احسبوا حساب مهلة عميل لا تقل عن 120 ثانية. أثناء الانتظار، يبقى الاتصال
مفتوحًا (تعليقات SSE : keep-alive في البث المباشر).
كم طلبًا يمكنني إرساله في الدقيقة؟#
حسب مستواكم : 30 أو 300 أو 1 200 طلب في الدقيقة، مع 2 أو 10 أو 30 طلبًا متزامنًا. انظروا تحديد المعدل.
البيانات والأمان#
هل تُستخدم إدخالاتي (prompts) لتدريب النماذج؟#
لا. لا تستخدم CloudZIR محتوى طلباتكم لتدريب النماذج. في استدعاءات المحادثة
المتزامنة، لا تحفظ مسارات واجهة API الرسائل والصور؛ وتُسجّل بيانات الاستخدام
اللازمة للفوترة والدعم. أما الملفات المرفوعة عبر
API الملفات فتُخزّن بشكل منفصل وتُحذف عبر
DELETE /v1/files/{file_id}. لا تُطبّق مدة انتهاء تلقائية لهذه الملفات.
أين تُعالَج بياناتي؟#
تعمل بوابة واجهة API في الولايات المتحدة، وتُستضاف قاعدة البيانات والمصادقة وتخزين الملفات في الاتحاد الأوروبي. وبحسب المحرّك المستعمل، يُنفَّذ الاستدلال لدى مزوّدين يقع معظمهم في الولايات المتحدة وبعضهم في دول أخرى (لا سيما في آسيا). ويُعدّ إنشاء الحساب موافقة صريحة على هذا النقل إلى خارج الجزائر (المادتان 44 و45 من القانون رقم 18-07). التفاصيل في التخزين والخصوصية وفي سياسة الخصوصية. لأي سؤال عن مواقع المعالجة، راسلوا support@cloudzir.com (الموضوع « حماية المعطيات »).
فقدت مفتاحي، هل يمكن استرجاعه؟#
لا : لا يُخزَّن سوى بصمة منه. ألغوه وأنشئوا مفتاحًا جديدًا من API keys. يسري الإلغاء في أقل من دقيقة.
تسرّب مفتاحي، ماذا أفعل؟#
ألغوه فورًا من المنصة، أنشئوا مفتاحًا آخر، ثم تحققوا من Usage لرصد استهلاك غير طبيعي. أبلغونا بأي استخدام احتيالي : يمكننا التحقيق باستخدام معرّفات الطلبات.
هل يمكنني تقييد مفتاح باستخدام محدد؟#
نعم، من المنصة : في صفحة API keys، افتحوا السطر « ضبط الحدود » الذي يحمل اسم المفتاح المعني. يمكن لكل مفتاح أن يحمل :
- النماذج ونقاط الوصول التي يستطيع استدعاءها (مثل
/v1/chat/completions)؛ - معدّل طلبات خاص به (طلبات في الدقيقة) وعدد طلبات متزامنة خاص به : لا يمكنهما إلا خفض حدود مستواكم، ولا رفعها أبدًا؛
- ميزانية شهرية (الشهر التقويمي بالتوقيت العالمي UTC) وأقصى تكلفة لكل طلب، بالدينار.
التقييد بعناوين IP غير متاح حاليًا. خلف بنيتنا التحتية لا يمكن التحقق من عنوان
مصدر طلباتكم بشكل موثوق : وأي قيد يستند إليه يمنح إحساسًا زائفًا بالأمان. لذلك لم تعد
المنصة تعرض هذا الحقل. وترفض واجهة API تسجيل قائمة عناوين (400، المعامل
cidr_allowlist) وترفض طلبات المفتاح الذي يحمل قائمة مسجَّلة من قبل
(403 account_disabled) : أعيدوا حفظ حدود المفتاح فتُزال القائمة.
الحقل الفارغ لا يفرض أي قيد. وإلغاء تحديد « السماح بالطلبات بهذا المفتاح » يعلّق
المفتاح : فيرفض حينئذٍ كل طلب، بما في ذلك قراءة الملفات والدفعات وقائمة النماذج
والرصيد. تجري هذه الفحوص قبل استدعاء النموذج. الطلب
الخارج عن النماذج أو نقاط الوصول المسموح بها يتلقى
403 account_disabled. أما أقصى تكلفة والميزانية فيخصّان أقصى تكلفة
ممكنة للطلب (رموز الإدخال المقدَّرة زائد max_tokens) لا تكلفته
النهائية : الطلب الذي يتجاوزهما يتلقى 402 insufficient_balance حتى لو
كان رصيدكم كافيًا، وقد يمرّ إذا خفضتم max_tokens.
ما لا وجود له : تاريخ انتهاء صلاحية للمفتاح، وميزانية تراكمية على عمر المفتاح
كله (تعود الميزانية إلى الصفر كل شهر). يسري التعليق وقائمة نقاط الوصول
المسموح بها على كل مسار يقبل مفتاحًا، بما في ذلك الملفات والدفعات وقائمة النماذج
والرصيد : فالمفتاح المقيَّد بنقاط وصول محددة لا يبلغ هذه المسارات إلا إذا ورد
مسارها في القائمة (/v1/files، /v1/files/{file_id}،
/v1/files/{file_id}/content، /v1/batches،
/v1/batches/{batch_id}، /v1/batches/{batch_id}/cancel،
/v1/models، /anthropic/v1/models و/v1/user/balance).
أما قيود النماذج والتكلفة (بما فيها الميزانية) فلا تخصّ إلا طلبات التوليد ومسارات
الحساب (التضمينات والإشراف وOCR وإعادة الترتيب وعدّ الرموز) وإنشاء الدفعات.
ولفصل بيئاتكم أنشئوا أيضًا عدة مفاتيح :
يُتابَع استهلاكها بشكل منفصل في Usage.
الميزات#
هل يمكنني إرسال صور؟#
نعم، على النماذج الثلاثة وعلى الواجهتين : PNG وJPEG وWebP وGIF، حتى 8 ميغابايت لكل صورة و8 صور لكل طلب. انظروا الرؤية.
هل يمكنني إرسال مستندات؟#
نعم : ارفعوها عبر API الملفات، وتستخرج CloudZIR النص منها، فتُدرجونه في إدخالاتكم. المستندات الممسوحة ضوئيًا (بلا طبقة نصية) يجب أن تمر عبر الرؤية.
هل يمكنني التحكم في استدلال النموذج؟#
نعم : thinking لتفعيله أو إيقافه، وreasoning_effort
لضبط شدته. إيقاف الاستدلال في مهمة بسيطة قد يقلّل زمن الاستجابة بشكل ملحوظ (نحو النصف في مثال الدليل، بحسب السؤال). انظروا
وضع التفكير.
هل تولّد واجهة API صورًا أو صوتًا؟#
لا. تغطي واجهة API العمومية توليد النصوص فقط. توليد الصور والصوت متاحان في منتج CloudZIR AI، وليس بعد كنقاط نهاية مفوترة.
هل يوجد اتفاق مستوى خدمة (SLA)؟#
نعم. تلتزم الشروط العامة (المادة 10.6) لصالح CloudZIR بتوافر بنسبة 99,9 % لواجهة API، تُقاس شهريًا، باستثناء الصيانة المُعلَنة مسبقًا والقوة القاهرة. عند ثبوت إخلال خلال شهر ما، يمكنكم طلب تعويض بالرموز من support@cloudzir.com. تتولى سلاسل احتياطية المهمة تلقائيًا عند عطل أحد المحركات. تُنشر الأعطال على آخر المستجدات.