رمز / المواصفات البرمجية.

المواصفات البرمجية.

تعرّف على مسارات العمل ومتطلباتها، وأدر حسابك ومفاتيح الواجهة البرمجية من منصة المطورين.

01

إنشاء مفتاح الواجهة البرمجية وحمايته

  1. سجّل الدخول إلى المنصة وتحقق من بريدك الإلكتروني.
  2. افتح صفحة مفاتيح الواجهة البرمجية وأنشئ مفتاحاً. انسخ المفتاح السري عند عرضه؛ يظهر مرة واحدة.
  3. احفظ المفتاح على خادمك في المتغير RAMZ_API_KEY. لا تضعه في شيفرة المتصفح أو لقطة شاشة مشتركة أو مستودع شيفرة.
  4. ألغِ المفتاح من صفحة المفاتيح إذا انكشف أو لم تعد بحاجة إليه.
إدارة مفاتيح الواجهة البرمجية
02

العنوان الأساسي والمصادقة

https://api.ramzai.org/v1

أرسل ترويسة Authorization مع كل طلب. يعيد الخادم الرمز HTTP 401 إذا كان المفتاح مفقوداً أو ملغى أو منتهياً أو غير صالح.

Authorization: Bearer YOUR_API_KEY
{"error":"A valid API key is required."}
03

معرّفات النماذج

ضع معرّف الطلب ramz0 في الحقل model، لا اسم المنتج أو المؤسسة. احصل على قائمة النماذج باستخدام GET /v1/models؛ استخدم قيم data[].id عند اختيار نموذج من القائمة.

curl https://api.ramzai.org/v1/models \
  -H "Authorization: Bearer $RAMZ_API_KEY"

تكون الاستجابة كائن JSON يحوي object بقيمة list ومصفوفة data. استجابة قائمة النماذج ليست نتيجة استدلال.

04

إرسال طلب محادثة

POST /v1/chat/completions

استخدم Content-Type: application/json. يحدد model النموذج المطلوب، وتحوي messages الرسائل بالترتيب. لكل رسالة حقلان: role وcontent. لا ترسل بيانات حساسة دون ضرورة.

curl https://api.ramzai.org/v1/chat/completions \
  -H "Authorization: Bearer $RAMZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ramz0",
    "messages": [
      {"role": "system", "content": "Answer clearly and concisely."},
      {"role": "user", "content": "Explain speech recognition."}
    ]
  }'

اقرأ الإجابة من choices[0].message.content. يعرض usage عدد رموز الإدخال والإخراج والمجموع. معرّف النموذج في الاستجابة هو ramz0. تحدّد الخدمة الحد الأقصى للإخراج بـ500 رمز؛ لا ترسل الحقل max_tokens. تعيد الطلبات التي تحاول تغيير هذا الحد الرمز HTTP 400. يمكن ضبط temperature بين 0 و1. لا تدعم هذه الواجهة البث أو استدعاء الأدوات. يجب إرسال رسالة نصية واحدة إلى 32 رسالة، بحجم إجمالي لا يتجاوز 32 كيلوبايت.

05

الرصيد والأخطاء وتتبع الطلبات

يحصل كل حساب على عشرة طلبات محادثة ناجحة مجاناً إجمالاً، بحد أقصى 500 رمز إخراج لكل طلب. تشترك الواجهة البرمجية ومساحة التجربة وجميع المفاتيح في هذا الحد؛ لا يعيد إنشاء مفتاح جديد ضبطه. يُستعاد الطلب المجاني عند فشل توليد الإجابة. يبدأ الرصيد من ‎$0.00؛ بعد استنفاد الطلبات العشرة، تعيد الطلبات ذات الرصيد غير الكافي الرمز HTTP 402. الدفع والفوترة التلقائية غير مفعّلين. راجع الطلبات المجانية المتبقية في صفحة الرصيد وسجل الطلبات في صفحة الاستخدام.

{
  "error": {
    "type": "insufficient_credit",
    "code": "insufficient_credit",
    "message": "Your account has insufficient credits."
  },
  "request_id": "REQUEST_ID"
}

يمكن تنفيذ طلبين متزامنين على الأكثر لكل حساب. الحد هو 120 طلباً في الساعة لكل عنوان عميل، ويشمل محاولات الواجهة البرمجية ومساحة التجربة. يشير HTTP 400 إلى معاملات غير صالحة، و429 إلى تجاوز حد الطلبات أو التزامن، و502 إلى فشل توليد الإجابة. لا تُعِد الطلب تلقائياً دون التحقق من نتيجته.

يُعاد معرّف request_id الفعلي أيضاً في ترويسة الاستجابة x-request-id. احتفظ به عند التواصل مع الدعم، ولا تشارك مفتاحك. عند 401 افحص المفتاح، وعند 402 افحص رصيد الحساب. لا تكرر الطلب دون معالجة سبب الخطأ.