عملية التقديم
لاستخدام واجهة API لتوليد صور Flux، انتقل أولًا إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك واحتفظ به للاستخدام لاحقًا.
إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية.
يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: واجهة API لتوليد صور Flux →
الاستخدام الأساسي
افهم أولًا طريقة الاستخدام الأساسية، وهي إدخال كلمة التوجيهprompt، وإجراء التوليد action، وحجم الصورة size، ثم يمكنك الحصول على النتيجة المعالجة. تحتاج أولًا إلى تمرير حقل action ببساطة، وتكون قيمته generate، ثم نحتاج أيضًا إلى إدخال كلمة التوجيه، والمحتوى المحدد كما يلي:
accept: تنسيق نتيجة الاستجابة الذي تريد تلقيه، وهنا يُملأ بـapplication/json، أي تنسيق JSON.authorization: مفتاح استدعاء API، ويمكن اختياره مباشرة من القائمة المنسدلة بعد التقديم.
action: إجراء مهمة توليد الصور هذه.size: حجم نتيجة توليد الصورة. يجب أن تمرر سلسلةflux-2-flex/flux-2-pro/flux-2-maxنسبة الصورة (مثل1:1و16:9)، ولا تقبل أبعاد البكسل مثل1024x1024، وسيتم إرجاع 400 عند عدم تحديدها.count: عدد الصور التي يتم إنشاؤها، والقيمة الافتراضية هي 1. تكون هذه المعلمة فعالة فقط في مهمة توليد الصور، وغير فعالة في مهمة التحرير.prompt: كلمة التوجيه.model: نموذج التوليد، والقيمة الافتراضية هيflux-dev؛ وأحدث النماذج الرائدة هيflux-2-proوflux-2-max(جودة صورة أعلى، وتتطلب استخدام نسبة الصورةsize).callback_url: عنوان URL الذي يحتاج إلى استدعاء النتيجة.async: اختياري، عند تعيينه إلىtrue، تقوم الواجهة بإرجاعtask_idفورًا، ولا حاجة لتوفيرcallback_url، ثم يتم الحصول على النتيجة عبر الاستعلام الدوري من خلال واجهة استعلام المهمة المقابلة.
size، وتنقسم أساسًا إلى نوعين: نسبة العرض إلى الارتفاع width x height، ونسبة الصورة x:y، والتفاصيل كما يلي:
نِسَب الصور المرجعية: “21:9”، “16:9”، “4:3”، “3:2”، “1:1”، “2:3”، “3:4”، “9:16”، “9:21”.
بعد اختيار المعلمات، سيتم إنشاء الكود المقابل تلقائيًا على الجانب الأيمن. قبل النسخ، يرجى التأكد من أن رأس التفويض يستخدم API Key الخاص بك، ولا ينبغي أن تظهر بيانات اعتماد حقيقية في الوثائق ولقطات الشاشة.
انقر على زر «Try» لإجراء الاختبار، وهنا حصلنا على النتيجة التالية:
success، حالة مهمة توليد الفيديو في هذا الوقت.task_id، معرّف مهمة توليد الفيديو في هذا الوقت.trace_id، معرّف تتبع توليد الفيديو في هذا الوقت.data، قائمة نتائج مهمة توليد الصور في هذا الوقت.image_url، رابط مهمة توليد الصور في هذا الوقت.prompt، كلمة التوجيه.
data ضمن النتيجة.
بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك نسخه مباشرةً، على سبيل المثال، كود CURL كما يلي:
مهمة تحرير الصور
إذا كنت ترغب في تحرير صورة معينة، فيجب أولًا تمرير رابط الصورة التي تحتاج إلى تحريرها في المعلمةimage_url، وفي هذا الوقت يدعم action فقط edit، ويمكنك تحديد المحتوى التالي:
- model: النموذج المستخدم في مهمة تحرير الصور هذه، ويدعم
flux-devوflux-proوflux-kontext-proوflux-kontext-maxوflux-2-flexوflux-2-proوflux-2-max. - image_url: ارفع الصورة التي تحتاج إلى تحريرها.
الاستدعاء غير المتزامن
نظرًا لأن وقت إنشاء Flux Images Generation API طويل نسبيًا، ويستغرق حوالي 1-2 دقيقة، فإذا لم تستجب API لفترة طويلة، فسيظل طلب HTTP متصلًا باستمرار، مما يؤدي إلى استهلاك إضافي لموارد النظام، لذلك توفر هذه API أيضًا دعمًا للاستدعاء غير المتزامن. التدفق العام هو: عند قيام العميل بإرسال طلب، يحدد بالإضافة إلى ذلك حقلcallback_url، وبعد أن يرسل العميل طلب API، ستعيد API نتيجة فورًا، تتضمن معلومات حقل task_id، والذي يمثل معرّف المهمة الحالية. عند اكتمال المهمة، سيتم إرسال نتيجة إنشاء الصورة إلى callback_url الذي حدده العميل بصيغة POST JSON، وتتضمن أيضًا حقل task_id، وبهذه الطريقة يمكن ربط نتائج المهام عبر المعرّف.
فيما يلي سنتعرف من خلال مثال على كيفية التنفيذ بالتحديد.
أولًا، استدعاء Webhook هو خدمة يمكنها استقبال طلبات HTTP، ويجب على المطور استبداله بعنوان URL لخادم HTTP الذي أنشأه بنفسه. ولتسهيل العرض التوضيحي هنا، يتم استخدام موقع نموذج Webhook عام https://webhook.site/، ويمكن الحصول على عنوان Webhook URL عند فتح هذا الموقع، كما هو موضح في الشكل:
انسخ عنوان URL هذا، ويمكن استخدامه كـ Webhook، والنموذج هنا هو https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
بعد ذلك، يمكننا تعيين الحقل callback_url إلى عنوان Webhook URL المذكور أعلاه، مع إدخال المعلمات المقابلة في الوقت نفسه، والمحتوى المحدد كما هو موضح في الشكل:
https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab، كما هو موضح في الشكل:
المحتوى كما يلي:
task_id في النتيجة، أما الحقول الأخرى فهي مشابهة لما ورد أعلاه، ويمكن تحقيق ربط المهام من خلال هذا الحقل.
معالجة الأخطاء
عند استدعاء API، إذا حدث خطأ، فستعيد API رمز الخطأ والمعلومات المقابلة. على سبيل المثال:400 token_mismatched：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.400 api_not_implemented：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.401 invalid_token：غير مصرح به، رمز تفويض غير صالح أو مفقود.429 too_many_requests：طلبات كثيرة جدًا، لقد تجاوزت حد المعدل.500 api_error：خطأ داخلي في الخادم، حدث خطأ ما على الخادم.