واجهة بياني البرمجية

1. 1

   إنشاء رمز

   سجّل الدخول وافتح الحساب ← الواجهة البرمجية. سمِّ الرمز باسم تتعرّف عليه لاحقًا (مثل البرنامج الذي سيستخدمه)، واختر مدة صلاحيته، ثم انسخه. يبدأ الرمز بـ bay_ ولا يُعرض إلا مرة واحدة.

   احفظه في متغيّر بيئة، لا في شيفرتك:

   الطرفية content_copyنسخ

   export BAYANII_TOKEN="bay_..."

2. 2

   اعثر على نموذجك

   اعرض قائمة نماذجك. دوّن معرّف النموذج الذي تريده وأعمدة الإدخال التي يتوقعها.

   curl content_copyنسخ

   curl -H "Authorization: Bearer $BAYANII_TOKEN" \
     https://bayanii.com/api/v1/models

   الاستجابة content_copyنسخ

   {
     "data": [
       {
         "id": 88,
         "name": "Churn",
         "task_type": "classification",
         "targets": ["churned"],
         "input_columns": ["tenure", "plan", "monthly_charges"],
         "input": "rows",
         ...
       }
     ],
     "meta": {"total": 1, "limit": 50, "offset": 0, "has_more": false}
   }

3. 3

   احصل على تنبؤ

   أرسل كائنًا واحدًا لكل صف، يكون فيه كل عمود إدخال مفتاحًا.

   curl content_copyنسخ

   curl -X POST https://bayanii.com/api/v1/models/88/predictions \
     -H "Authorization: Bearer $BAYANII_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"rows": [{"tenure": 12, "plan": "monthly", "monthly_charges": 70.5}]}'

   الاستجابة content_copyنسخ

   {
     "data": {
       "model_id": 88,
       "task_type": "classification",
       "row_count": 1,
       "predictions": [
         {"prediction": "yes", "confidence": 0.82, "runner_up": "no", "runner_up_confidence": 0.18}
       ],
       "warnings": [],
       "prediction_run_id": 1234,
       "stored": false
     }
   }

المصادقة

يحمل كل طلب رمزك في ترويسة Authorization:

Authorization: Bearer bay_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• schedule

  مدة العمل

  30 أو 90 أو 365 يومًا، أو دون انتهاء. حتى 10 رموز نشطة لكل حساب.

• block

  الإلغاء

  ألغِ الرمز من الحساب ← الواجهة البرمجية. يُرفض الطلب التالي الذي يحمله.

• person_off

  تغييرات الحساب

  حذف حسابك يحذف رموزه. وتتوقف رموز الحساب المعطَّل عن العمل خلال 15 دقيقة.

• lock

  إدارة الرموز

  لا يستطيع الرمز إنشاء الرموز أو عرضها أو إلغاءها — فذلك يتطلب أن تكون أنت مسجّل الدخول.

الطلبات والاستجابات

لكل استجابة الشكل نفسه: النتيجة تحت "data"، أو المشكلة تحت "error" — ولا يجتمعان أبدًا. تحقّق من حالة HTTP أولًا، ثم اقرأ المفتاح المقابل.

{
  "data": { ... },
  "meta": { ... }
}

{
  "error": {
    "code": "missing_columns",
    "message": "Row 3 is missing: plan.",
    "details": {"row": 3, "columns": ["plan"]}
  }
}

• يظهر "meta" في القوائم ويحمل معلومات التنقّل بين الصفحات.
• اعتمد على "code" في منطق برنامجك — فهو لا يتغيّر أبدًا. أما "message" فجملة موجّهة للناس تتبع ترويسة Accept-Language (en أو ar؛ والإنجليزية افتراضيًا).
• الطوابع الزمنية مثل created_at وexpires_at بصيغة ISO 8601 بالتوقيت العالمي المنسّق (UTC)، وتنتهي بالحرف Z — مثل 2026-11-01T09:30:00Z. أما period في التنبؤ الزمني فهو التاريخ كما ورد في بيانات تدريبك، دون إضافة منطقة زمنية.
• أرسل أجسام الطلبات بصيغة JSON مع الترويسة Content-Type: application/json.
• لا تُخزَّن الاستجابات مؤقتًا أبدًا (Cache-Control: no-store): فقد تحمل بياناتك.

إجراء التنبؤات

ما ترسله

• يجب أن يحضر كل عمود إدخال في كل صف. قد تكون القيمة رقمًا أو نصًا أو true / false، أو null لخلية فارغة — ويملأ النموذج الخلية الفارغة بالطريقة التي اتبعها في التدريب.
• تُتجاهَل المفاتيح الزائدة، ويسمّيها تحذير، كي لا يمرّ خطأ إملائي في اسم عمود دون أن يُلاحَظ.
• استخدم input_schema الخاص بالنموذج لبناء الصفوف: أسماء الأعمدة بدقة، والقيم التي يعرفها للفئات.

ما تحصل عليه

التحذيرات

لكل تحذير رمز ودرجة خطورة وعنوان ورسالة. "caution" تعني أن التنبؤ قد يكون أقل موثوقية؛ و"notice" للعلم فقط.

{
  "code": "out_of_range",
  "severity": "caution",
  "title": "Values outside the training range",
  "message": "Values in \"tenure\" are outside the range seen during training (0–72; count: 1). They were not changed.",
  "details": {"column": "tenure", "min": 0, "max": 72, "count": 1}
}

نماذج التنبؤ الزمني

يأخذ نموذج التنبؤ الزمني الذي لا أعمدة إدخال له "steps" بدل الصفوف، ويعود كل عنصر بفترته الزمنية ومجال التنبؤ حوله:

{"steps": 3}

{
  "period": "2026-01-01T00:00:00",
  "prediction": 120.5,
  "lower": 98.1,
  "upper": 141.7
}

الأخطاء

تعني الحالة 4xx أن في الطلب ما يحتاج إلى إصلاح — وإعادة الطلب نفسه ستفشل بالطريقة نفسها، باستثناء 429. أما الحالة 5xx فمن جهتنا: أعد المحاولة لاحقًا، واذكر details.request_id إن تواصلت معنا.

الحدود

تُحتسب الحدود لكل حساب — لجميع رموزك معًا. اجمع الصفوف في طلب واحد بدل إرسال طلب لكل صف: فهذا أسرع لك ويُحتسب مرة واحدة.

طلب تنبؤ في الدقيقة

30

طلبًا آخر في الدقيقة

120

صف في كل طلب تنبؤ

10,000

رموز نشطة لكل حساب

10

أمثلة كاملة

تنبؤ مع معالجة الأخطاء، يقرأ الرمز من متغيرات البيئة.

import os
import requests

API = "https://bayanii.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BAYANII_TOKEN']}"

rows = [
    {"tenure": 12, "plan": "monthly", "monthly_charges": 70.5},
    {"tenure": 48, "plan": "yearly", "monthly_charges": 55.0},
]
resp = session.post(f"{API}/models/88/predictions", json={"rows": rows}, timeout=120)
body = resp.json()

if resp.ok:
    for row, p in zip(rows, body["data"]["predictions"]):
        print(row, "->", p["prediction"], p.get("confidence"))
    for w in body["data"]["warnings"]:
        if w["severity"] == "caution":
            print("caution:", w["message"])
elif resp.status_code == 429:
    print("Slow down; retry after", resp.headers.get("Retry-After"), "seconds")
else:
    print(resp.status_code, body["error"]["code"], body["error"]["message"])

const API = "https://bayanii.com/api/v1";

const resp = await fetch(`${API}/models/88/predictions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BAYANII_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    rows: [{ tenure: 12, plan: "monthly", monthly_charges: 70.5 }],
  }),
});
const body = await resp.json();

if (!resp.ok) {
  throw new Error(`${resp.status} ${body.error.code}: ${body.error.message}`);
}
for (const p of body.data.predictions) {
  console.log(p.prediction, p.confidence);
}

curl -sS -X POST https://bayanii.com/api/v1/models/88/predictions \
  -H "Authorization: Bearer $BAYANII_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
        "rows": [
          {"tenure": 12, "plan": "monthly", "monthly_charges": 70.5},
          {"tenure": 48, "plan": "yearly",  "monthly_charges": 55.0}
        ],
        "store": true
      }'

الإصدارات

الإصدار جزء من عنوان URL. وضمن v1 قد نضيف نقاط نهاية وحقول استجابة ورموز تحذيرات ورموز أخطاء، لذا تجاهل الحقول التي لا تعرفها. لن نعيد تسمية حقل أو نحذفه أو نغيّر معنى رمز — فتغيير كهذا يصبح /api/v2، ويستمر v1 في العمل إلى جانبه.