توثيق الـ API

لكل سير عمل منشور نقطة وصول. المدخلات هي مفاتيح عُقد «الإدخال» والمخرجات مفاتيح عُقد «الإخراج».

العنوان الأساسي: https://api.mlgrid.com

المصادقة

أنشئ مفتاحاً من صفحة «مفاتيح API» وأرسله في ترويسة Authorization.

headerhttp
Authorization: Bearer mlg_xxxxxxxxxxxxxxxx

تشغيل سير العمل

الطلب متزامن ويعيد النتيجة بعد انتهاء التشغيل.

requesthttp
POST https://api.mlgrid.com/v1/workflows/{slug}/run
Content-Type: application/json

{ "input": { "text": "..." } }
200 OKjson
{
  "id": "cm...",
  "status": "succeeded",
  "output": { "summary": "..." },
  "usage": { "tokensIn": 812, "tokensOut": 164, "cost": "38.2", "currency": "IRT" }
}

ملفات المخرجات

تُعاد المخرجات مثل الصور والصوت والفيديو وPDF وWord وExcel كعناوين URL. تُحذف هذه الملفات بعد 24 ساعة من إنشائها؛ نزّلها واحفظها فورًا إن احتجتها.

الحصول على عقد المدخلات/المخرجات

requesthttp
GET https://api.mlgrid.com/v1/workflows/{slug}

حالة التشغيل

requesthttp
GET https://api.mlgrid.com/v1/runs/{id}

الذاكرة والجلسات

إذا احتوى سير العمل على عقدتي «قراءة الذاكرة» و«الحفظ في الذاكرة»، فإن كل استدعاء بنفس session يُعد استمراراً للمحادثة نفسها. الذاكرة منفصلة لكل مستخدم (مفتاح API)؛ لا يرى مستخدمو سير العمل العام ذاكرة بعضهم أبداً. الرسائل الأقدم من النافذة المحددة تُمرَّر إلى العقدة التي ربطتها للتلخيص ويحل الملخص محلها.

requesthttp
POST https://api.mlgrid.com/v1/workflows/{slug}/run
Authorization: Bearer mlg_xxxxxxxx
Content-Type: application/json

{ "input": { "message": "اسم من سارا است" }, "session": "user-42" }
مسح الذاكرةhttp
DELETE https://api.mlgrid.com/v1/workflows/{slug}/memory?session=user-42

حساب التكلفة

تكلفة كل عقدة = (توكنات الإدخال × سعر الإدخال + توكنات الإخراج × سعر الإخراج) ÷ 1,000,000 + الرسوم الثابتة لكل استدعاء. التكلفة الكلية للتشغيل هي مجموع العُقد مضافاً إليها عمولة المنشئ (إن وُجدت)، وتُخصم من محفظة المستدعي.

تُقرأ التوكنات مباشرة من تقرير مزوّد النموذج. إذا فشل التشغيل في منتصفه تُحتسب فقط تكلفة العُقد التي نُفّذت.

الأخطاء

400متن الطلب غير صالح (مثلاً لم يُرسل الحقل input).
401مفتاح API غير مرسل أو ملغى.
402رصيد المحفظة غير كافٍ.
404سير العمل غير موجود أو غير منشور أو خاص.
422فشلت إحدى العُقد؛ يحدد nodeId في الاستجابة أيها.
429عدد الطلبات تجاوز الحد (60 طلباً في الدقيقة لكل مستخدم).

إنشاء نموذج مخصص

يجب أن يعرّف ملف main.py الدالة execute. القيمة المعادة إما قاموس المخرجات مباشرة أو قاموس يحتوي outputs وusage للإبلاغ عن التوكنات.

main.pypython
def execute(inputs, params):
    text = inputs.get("text", "")
    return {
        "outputs": {"text": text[::-1]},
        "usage": {"tokensIn": len(text), "tokensOut": len(text)},
    }