التوثيق

مرجع API

إنشاء تشغيل أداة

POST/v1/tool-runs

دعم موحّد لتسعير flat الثابت لكل استدعاء، وتسعير input المحسوب مسبقًا من المدخلات، وتسعير usage المبني على الاستخدام النهائي. يحدد pricing.quote_required إلزامية عرض السعر؛ ويحدد requires_usage الحاجة إلى سقف تكلفة واستخدام نهائي موثوق. لا يُستنتج أي منهما من schema_version. عند تعطيل metered_pricing، تُقيّد الاستدعاءات الجديدة التي تتطلب الاستخدام النهائي فقط؛ وتظل القواعد الثابتة/المبنية على المدخلات متاحة إن لم تحتج إلى استخدام نهائي. يجب أن يملك المفتاح الحالي صلاحية الأداة؛ وترتبط هوية التشغيل ونتائجه بالمفتاح الأصلي. يكون الدليل فارغًا عند تعطيل المفتاح الرئيسي للأدوات؛ ولا يمنح الدليل المجهول صلاحية التنفيذ. تتطلب الاستدعاءات الجديدة version/input غير فارغين وIdempotency-Key. إذا فُقدت استجابة الإنشاء ولم يتوفر run_id، فأعِد هذه العملية بمفتاح API الأصلي وIdempotency-Key الأصلي وجسم الطلب الأصلي الكامل لاسترداد التشغيل الموجود، دون عرض سعر جديد أو تغيير سقف التكلفة. لا تعتمد إعادة تشغيل طلب مقبول على المفاتيح الحالية أو انتهاء عرض السعر. عند معرفة run_id، استعلم عن التشغيل الأصلي فقط؛ ولا تنشئ تشغيلًا جديدًا بمفتاح مختلف لإرسال غير معروف النتيجة.

التنفيذ بعد عرض السعر

احصل على version وinput_schema وpricing الدقيقة من تفاصيل الأداة. mode=flat سعر ثابت لكل استدعاء، وmode=input حساب مسبق حسب المدخلات، وmode=usage حساب حسب الاستخدام النهائي. يشير schema_version للقاعدة إلى تنسيق التخزين فقط.

الاستدعاء الجديد ذو quote_required=true يحتاج إلى عرض أولًا. تحقق من tool_id/version المعادين واحفظ quote_id والطلب الأصلي. عند requires_usage=true يجب أيضًا توفير max_cost_usd لا يقل عن maximum_usd. سقف التكلفة اختياري للتشغيلات الأخرى، لكنه يُراجع إذا قُدم. يمكن تنفيذ التشغيل الثابت الذي لا يحتاج إلى استخدام نهائي مباشرةً؛ قواعد المدخلات تتطلب عرض سعر، لكن قد لا تتطلب استخدامًا نهائيًا للتسوية.

يثبّت العرض المصدر الأصلي. إذا تغيّر المصدر الافتراضي لاحقًا، يظل العرض يستخدم المصدر الأصلي ما دام المصدر وإعداداته صالحين. للاستدعاءات الجديدة غير المرسلة، يمكن إعادة التسعير عند quote_expired أو quote_stale أو invalid_quote بعد مراجعة المدخلات. إذا نجح التنفيذ وبقي billing في reserved، فاستمر في الاستعلام عن الاستخدام النهائي؛ نجاح المخرجات لا يثبت اكتمال التسوية.

الاستعادة عند ضياع الرد

قبل الإرسال احفظ هوية API Key وIdempotency-Key ونص الطلب الكامل الأصلي. إذا ضاعت استجابة الإنشاء ولم يوجد run_id، فأعد POST /v1/tool-runs باستخدام Key ومفتاح الطلب والطلب الكامل نفسها. أبقِ quote_id وmax_cost_usd الأصليين، دون إعادة تسعير أو تغيير المفتاح. يعيد التشغيل الموجود سجله الأصلي بالأولوية دون استدعاء الخدمة مجددًا، حتى إذا انتهى العرض لاحقًا أو أُغلقت الاستدعاءات الجديدة. بعد الحصول على run_id استخدم GET للتشغيل الأصلي فقط.

يجب مراجعة الطلب الأصلي عند تعارض عدم التكرار؛ لا تغيّر المفتاح تلقائيًا لإنشاء عملية مدفوعة جديدة. راجع معالجة الأخطاء والفوترة والاستعادة غير المتزامنة.

المصادقة والصلاحيات

استخدم مفتاح GloopAPI الحالي. تعتمد النماذج والإمكانات والصلاحيات المتاحة على دليله ووثائق نقطة النهاية.

Authorization: Bearer $GLOOP_API_KEY

آليات المصادقة: BearerAuth

الطلب

ترويسات الطلب

  • Idempotency-Keystringمطلوب

    احتفظ بقصد الطلب الأصلي وبالمفتاح نفسه. بعد انقطاع الشبكة، استعلم عن الاسترداد أولًا؛ ولا تُعِد إرسال الحالات غير المعروفة دون تحقق.

    الحد الأدنى للطول
    1
    الحد الأقصى للطول
    191

جسم الطلب · application/json

النوع
object
الحقول المطلوبة
tool_idversioninput
خصائص إضافية
false

جسم الطلب مطلوب

  • quote_idstringاختياري

    عند pricing.quote_required=true يلزم عرض صالح للتشغيل الجديد؛ يمكن حذفه للسعر الثابت دون استخدام نهائي. يُتحقق دائمًا من ارتباطات العرض المقدم.

  • tool_idstringمطلوب

    معرّف الأداة من دليل الأدوات القابلة للتنفيذ للمفتاح الحالي.

  • versionstringمطلوب

    إصدار العقد/الإمكانات أو الأداة؛ تستخدم التشغيلات إصدار الأداة الذي يعيده الدليل.

    الحد الأدنى للطول
    1
    النمط
    ".*\\S.*"
  • inputunknownمطلوب

    يجب أن يجتاز input_schema لهذا الإصدار من الأداة. يُقبل JSON المعياري فقط؛ وتُحظر الحقول الإضافية مثل route_id الخاص بالمسؤول.

  • max_cost_usdstringاختيارييسمح بـ null

    عند pricing.requires_usage=true يلزم للتشغيل الجديد مبلغ ميزانية عشري صالح بالدولار وغير null، لا يقل عن maximum_usd للعرض؛ وإلا فهو اختياري ويُراجع عند تقديمه. تُراجع الميزانية عند الإنشاء فقط.

الاستجابات والأخطاء

HTTP 200

يُرجع 200 عندما تكون حالة التشغيل succeeded أو failed، في الاستجابة المتزامنة الأولى وفي الاسترداد المانع للتكرار للطلب الأصلي. قد تظل succeeded مع billing.status=reserved انتظارًا لتسوية الاستخدام النهائي؛ ولا يعني HTTP 200 أن الفوترة قد سُويت.

application/json

النوع
object
الحقول المطلوبة
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringمطلوب

    المعرّف العام لهذا الكائن، المستخدم لمسار تفاصيله المقابل.

  • tool_idstringمطلوب

    معرّف الأداة من دليل الأدوات القابلة للتنفيذ للمفتاح الحالي.

  • versionstringمطلوب

    إصدار العقد/الإمكانات أو الأداة؛ تستخدم التشغيلات إصدار الأداة الذي يعيده الدليل.

  • statusstringمطلوب

    submitting/running/submission_unknown/succeeded/failed؛ تعني submission_unknown جهل نتيجة الإرسال، ولا يجوز تغيير Idempotency-Key لإعادته.

  • outputunknownمطلوب

    JSON تحدده output_schema للأداة؛ لا تفترض بقاء النتائج بعد انتهاء الصلاحية.

  • error_codestringاختياري

    رمز خطأ عام يمكن استخدامه في منطق التفرّع.

  • billingobjectمطلوب

    حالة الفوترة المستقلة؛ لا تستبدلها بحالة التوليد.

    الحقول الفرعية لـ billing (7)
    • review_requiredbooleanاختياري

      تتطلب أدلة الفوترة مراجعة يدوية.

    • reasonstringاختياري

      السبب العام لتعذر الإجراء أو مراجعة الحسابات.

    • usageunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • breakdownunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • statusstringمطلوب

      حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

    • reserved_usdstringمطلوب

      الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

    • charged_usdstringمطلوب

      مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

    فرع allOf رقم 1

    النوع: object

    المطلوب في هذا الفرع: status, reserved_usd, charged_usd

    • review_requiredbooleanاختياري

      تتطلب أدلة الفوترة مراجعة يدوية.

    • reasonstringاختياري

      السبب العام لتعذر الإجراء أو مراجعة الحسابات.

    • usageunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • breakdownunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • statusstringمطلوب

      حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

    • reserved_usdstringمطلوب

      الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

    • charged_usdstringمطلوب

      مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

  • result_expiredbooleanمطلوب

    هل انتهت صلاحية النتيجة؛ تبقى سجلات الفوترة/منع التكرار.

  • created_atintegerمطلوب

    وقت الإنشاء بثواني Unix.

  • updated_atintegerمطلوب

    آخر تحديث بثواني Unix.

HTTP 202

حالة التشغيل submitting أو running أو submission_unknown. قُبل الطلب؛ ويجب تقييم الفوترة بصورة مستقلة باستخدام billing.

application/json

النوع
object
الحقول المطلوبة
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringمطلوب

    المعرّف العام لهذا الكائن، المستخدم لمسار تفاصيله المقابل.

  • tool_idstringمطلوب

    معرّف الأداة من دليل الأدوات القابلة للتنفيذ للمفتاح الحالي.

  • versionstringمطلوب

    إصدار العقد/الإمكانات أو الأداة؛ تستخدم التشغيلات إصدار الأداة الذي يعيده الدليل.

  • statusstringمطلوب

    submitting/running/submission_unknown/succeeded/failed؛ تعني submission_unknown جهل نتيجة الإرسال، ولا يجوز تغيير Idempotency-Key لإعادته.

  • outputunknownمطلوب

    JSON تحدده output_schema للأداة؛ لا تفترض بقاء النتائج بعد انتهاء الصلاحية.

  • error_codestringاختياري

    رمز خطأ عام يمكن استخدامه في منطق التفرّع.

  • billingobjectمطلوب

    حالة الفوترة المستقلة؛ لا تستبدلها بحالة التوليد.

    الحقول الفرعية لـ billing (7)
    • review_requiredbooleanاختياري

      تتطلب أدلة الفوترة مراجعة يدوية.

    • reasonstringاختياري

      السبب العام لتعذر الإجراء أو مراجعة الحسابات.

    • usageunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • breakdownunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • statusstringمطلوب

      حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

    • reserved_usdstringمطلوب

      الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

    • charged_usdstringمطلوب

      مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

    فرع allOf رقم 1

    النوع: object

    المطلوب في هذا الفرع: status, reserved_usd, charged_usd

    • review_requiredbooleanاختياري

      تتطلب أدلة الفوترة مراجعة يدوية.

    • reasonstringاختياري

      السبب العام لتعذر الإجراء أو مراجعة الحسابات.

    • usageunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • breakdownunknownاختياري

      قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

    • statusstringمطلوب

      حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

    • reserved_usdstringمطلوب

      الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

    • charged_usdstringمطلوب

      مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

  • result_expiredbooleanمطلوب

    هل انتهت صلاحية النتيجة؛ تبقى سجلات الفوترة/منع التكرار.

  • created_atintegerمطلوب

    وقت الإنشاء بثواني Unix.

  • updated_atintegerمطلوب

    آخر تحديث بثواني Unix.

HTTP 400

حقول الطلب أو معاملاته غير صالحة.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 401

Key مفقود أو غير صالح أو منتهي أو ملغى.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 403

صلاحيات IP أو الحساب أو النموذج أو الأداة غير كافية.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 404

الكائن/الإمكانية غير متاحين، أو مفتاح الميزة معطّل.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 409

تعارض في منع التكرار/عرض السعر، أو كائن غير جاهز، أو ما يزال مشارًا إليه.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 429

حد معدل الطلبات/قائمة الانتظار.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 500

فشل داخلي في المصادقة أو تخزين البيانات.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 503

الخدمة أو التسعير أو التخزين غير متاح.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

ملاحظات نقطة النهاية

هذا المثال للأدوات ذات requires_usage=true: استبدل quote_id وmax_cost_usd. يجب أن تكون الميزانية سلسلة USD عشرية صالحة لا تقل عن maximum_usd لعرض السعر هذا؛ والقيمة 0.01 توضيحية فقط. للقواعد المسعّرة بحسب المدخلات التي تتطلب عرض سعر دون استخدام نهائي، تكون الميزانية اختيارية. للتشغيلات ثابتة السعر التي لا تتطلب استخدامًا نهائيًا، يكون عرض السعر والميزانية اختياريين. قبل الإرسال، احتفظ بهوية المفتاح الأصلي ومفتاح الطلب وجسم الطلب الكامل؛ وأعِد استخدامها للاسترداد إذا فُقدت الاستجابة.