التوثيق

مرجع API

إنشاء مهمة صور دائمة

POST/v1/image-tasks

يجب أن يتطابق quote_id صالح وIdempotency-Key. تنفذ المعالجة الخلفية مرة واحدة وتُسوي/تؤرشف. لا تُعِد إرسال unknown أو billing_review دون تحقق. تقتصر الطلبات على 128 KiB؛ وتُرفض الحقول غير المعروفة.

من عرض السعر إلى النتيجة

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

ينبغي أن يحفظ التطبيق مفتاح الطلب التجاري ومعرّف المهمة معًا. بعد انقطاع العميل استعد بالمفتاح الأصلي، ولا تولّد مجددًا بسبب حالة مجهولة. حتى عند النجاح الجزئي افحص كل نتيجة وحالة حفظها قبل تقرير التنزيل. راجع المهام غير المتزامنة وضمان عدم تكرار التنفيذ.

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

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

Authorization: Bearer $GLOOP_API_KEY

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

الطلب

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

  • Idempotency-Keystringمطلوب

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

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

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

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

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

  • modelstringمطلوب

    معرّف نموذج عام من دليل المفتاح الحالي.

    الحد الأقصى للطول
    191
  • promptstringمطلوب

    غير فارغ، بحد أقصى 32000 بايت UTF-8. يحسب OpenAPI maxLength المحارف، لذلك لا يُحدد حد مصطنع لعدد المحارف.

  • sizestringمطلوب

    قيمة الحجم التي يعيدها عنصر image-models المختار؛ تُتحقق الإمكانات والأحجام لكل نموذج.

  • nintegerاختياري

    تُطبَّع القيم المحذوفة أو 0 إلى 1. الحد الأقصى الفعلي هو max_n من image-models؛ ولا تعتبر الحد الأقصى العام إمكانية للنموذج.

    القيمة الافتراضية
    1
    الحد الأدنى
    1
    الحد الأقصى
    6
  • referencesarrayاختياري

    اختر واحدًا فقط من file_id أو asset_id أو url لكل عنصر؛ ويحدد max_references العدد الفعلي.

    الحد الأقصى للعناصر
    14
    الحقول الفرعية لـ references (1)
    • []objectاختياري
      الحقول الفرعية لـ [] (3)
      • file_idstringاختياري

        المعرّف العام لملف مُدار للحساب والمفتاح نفسيهما.

      • asset_idstringاختياري

        معرّف أصل مرفوع للحساب والمفتاح نفسيهما.

      • urlstringاختياري

        رابط HTTPS عام دون userinfo أو fragment؛ يخضع لفحص SSRF.

        التنسيق
        "uri"
      فرع oneOf رقم 1

      المطلوب في هذا الفرع: file_id

      فرع oneOf رقم 2

      المطلوب في هذا الفرع: asset_id

      فرع oneOf رقم 3

      المطلوب في هذا الفرع: url

  • source_task_idstringاختياري

    مهمة مصدر اختيارية تابعة للمفتاح نفسه، لإثبات المصدر فقط؛ ولا تحل محل المراجع.

    الحد الأقصى للطول
    64
  • quote_idstringاختياري

    عند الإنشاء يجب أن يكون عرضًا صالحًا مطابقًا للطلب؛ يُتجاهل في طلب عرض السعر.

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

HTTP 202

تم إنشاء مهمة الصور الدائمة بنجاح

application/json

النوع
object
الحقول المطلوبة
modelpromptsizenreferencesidstatuscreated_atupdated_atreserved_quotafinal_quotabilling_statusresults
  • modelstringمطلوب

    معرّف نموذج عام من دليل المفتاح الحالي.

  • promptstringمطلوب

    توجيه التوليد.

  • sizestringمطلوب

    قيمة الحجم التي يعيدها عنصر image-models المختار؛ تُتحقق الإمكانات والأحجام لكل نموذج.

  • nintegerمطلوب

    عدد صور المخرجات المطلوبة، مع استمرار تطبيق الحد الأقصى للنموذج المختار.

  • referencesarrayمطلوب

    قائمة الصور المرجعية للتوليد.

    الحقول الفرعية لـ references (1)
    • []objectاختياري
      الحقول الفرعية لـ [] (3)
      • file_idstringاختياري

        المعرّف العام لملف مُدار للحساب والمفتاح نفسيهما.

      • asset_idstringاختياري

        معرّف أصل مرفوع للحساب والمفتاح نفسيهما.

      • urlstringاختياري

        رابط HTTPS عام دون userinfo أو fragment؛ يخضع لفحص SSRF.

        التنسيق
        "uri"
      فرع oneOf رقم 1

      المطلوب في هذا الفرع: file_id

      فرع oneOf رقم 2

      المطلوب في هذا الفرع: asset_id

      فرع oneOf رقم 3

      المطلوب في هذا الفرع: url

  • source_task_idstringاختياري

    المعرّف العام لمهمة المصدر، لإثبات المصدر فقط.

  • quote_idstringاختياري

    المعرّف العام لعرض السعر؛ يجب أن يستوفي ارتباط السعر والطلب عند الإنشاء.

  • idstringمطلوب

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

  • statusstringمطلوب

    لا يُعاد unknown تلقائيًا، وقد تبقى الحسابات المحجوزة pending.

    القيم المعدودة
    ["queued","dispatching","running","succeeded","partial_succeeded","failed","unknown","deleted"]
  • created_atintegerمطلوب

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

  • updated_atintegerمطلوب

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

  • reserved_quotaintegerمطلوب

    الحصة المحجوزة بوحدات quota للمنصة، وليست مبلغًا بالدولار.

  • final_quotaintegerمطلوب

    التكلفة النهائية بوحدات quota للمنصة؛ تعني null أنها غير محددة.

  • billing_statusstringمطلوب

    حالة الحجز/التسوية/الاسترداد؛ تحقق منها بصورة منفصلة عن حالة المهمة والأرشفة.

  • error_codestringاختياري

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

  • error_messagestringاختياري

    وصف موجّه للمستخدم بعد معالجته بتصنيف الأخطاء العام.

  • resultsarrayمطلوب

    عناصر المخرجات المولّدة؛ حالة أرشفة كل عنصر مستقلة.

    الحقول الفرعية لـ results (1)
    • []objectاختياري
      الحقول الفرعية لـ [] (7)
      • file_idstringاختياري

        المعرّف العام لملف مُدار للحساب والمفتاح نفسيهما.

      • storage_statusstringاختياري

        حالة أرشفة الملف؛ لا تُضمن التنزيلات المُدارة إلا بعد ready.

      • storage_errorstringاختياري

        الفئة العامة لفشل أرشفة الملف.

      • expires_atintegerاختياري

        وقت انتهاء بثواني Unix؛ تعني 0 عدم وجود انتهاء ثابت.

      • urlstringاختياري

        رابط الوصول إلى نتيجة أو مرجع؛ الروابط الموقّعة صالحة لفترة قصيرة فقط.

      • b64_jsonstringاختياري

        سلسلة Base64 للصورة؛ لا تطلبها باعتبارها URL.

      • revised_promptstringاختياري

        التوجيه المعدّل الذي يعيده الخدمة إن وُجد.

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)