واجهة برمجة تطبيقات توليد صور Flux - تعليمات الدمج

ستتناول هذه الوثيقة تعليمات دمج واجهة برمجة تطبيقات توليد صور Flux، والتي يمكن استخدامها لتوليد صور رسمية من Flux من خلال إدخال معلمات مخصصة.

عملية التقديم

لاستخدام واجهة برمجة تطبيقات توليد صور Flux، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز 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، كما هو موضح أدناه:

النموذج	النطاق
flux-dev	يدعم نسبة العرض إلى الارتفاع 1024x1024، 1024x1792، 1792x1024، أو نسبة الصورة
flux-pro	يدعم نسبة العرض إلى الارتفاع 1024x1024، 1024x1792، 1792x1024، أو نسبة الصورة
flux-2-flex	يدعم فقط نسبة الصورة
flux-2-pro	يدعم فقط نسبة الصورة
flux-2-max	يدعم فقط نسبة الصورة
flux-kontext-pro	يدعم فقط نسبة الصورة
flux-kontext-max	يدعم فقط نسبة الصورة

نسب الصورة المرجعية: “21:9”، “16:9”، “4:3”، “3:2”، “1:1”، “2:3”، “3:4”، “9:16”، “9:21”. بعد اختيار المعلمات، سيتم توليد الكود المقابل تلقائيًا على الجانب الأيمن. يرجى التأكد من استخدام رأس التفويض الخاص بك قبل النسخ، ولا ينبغي أن تظهر بيانات الاعتماد الحقيقية في الوثائق أو لقطات الشاشة. انقر على زر “Try” لإجراء الاختبار، وهنا حصلنا على النتيجة التالية:

{
  "success": true,
  "task_id": "5456c749-3bbb-4f10-9eb8-cfbcac297500",
  "trace_id": "ae4eecb8-1dd6-45b4-bfb3-a1c48872536e",
  "data": [
    {
      "image_url": "https://platform2.cdn.acedata.cloud/flux/5456c749-3bbb-4f10-9eb8-cfbcac297500.jpg"
    }
  ]
}

تتضمن نتيجة الإرجاع عدة حقول، كما هو موضح أدناه:

success: حالة مهمة توليد الفيديو في ذلك الوقت.
task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
trace_id: معرف تتبع توليد الفيديو في ذلك الوقت.
data: قائمة نتائج مهمة توليد الصورة في ذلك الوقت.
- image_url: رابط مهمة توليد الصورة في ذلك الوقت.
- prompt: كلمة التلميح.

يمكننا أن نرى أننا حصلنا على معلومات الصورة المرضية، كل ما علينا هو الحصول على صورة Flux المولدة من خلال رابط الصورة في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود الدمج المقابل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي:

curl -X POST 'https://api.acedata.cloud/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
  "model": "flux-2-pro",
  "size": "1:1"
}'

تحرير مهمة الصورة

إذا كنت ترغب في تحرير صورة معينة، يجب أولاً تمرير معلمة 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: رابط الصورة التي تحتاج إلى تحريرها.

مثال على كيفية التعبئة كما يلي:

بعد الانتهاء من التعبئة، تم توليد الكود تلقائيًا كما يلي:

الكود المقابل:

import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

عند النقر على التشغيل، يمكنك أن تجد أنك ستحصل على نتيجة على الفور، كما يلي:

{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "timings": 1752744073
    }
  ]
}

可以看到，生成的效果是对原图片进行编辑的效果，结果与上文类似。

استدعاء غير متزامن

نظرًا لأن واجهة برمجة تطبيقات توليد الصور من Flux تستغرق وقتًا طويلاً نسبيًا، حوالي 1-2 دقيقة، إذا كانت واجهة برمجة التطبيقات لا تستجيب لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك إضافي لموارد النظام، لذا توفر هذه الواجهة أيضًا دعمًا لاستدعاء غير متزامن. العملية العامة هي: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب واجهة برمجة التطبيقات، ستقوم الواجهة على الفور بإرجاع نتيجة تحتوي على معلومات حقل task_id، تمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة الصورة المولدة إلى callback_url المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، استدعاء Webhook هو خدمة يمكنها استقبال طلبات HTTP، يجب على المطور استبدالها بعنوان URL الخاص بالخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عينة عام https://webhook.site/، عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة:

قم بنسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. بعد ذلك، يمكننا تعيين الحقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

عند النقر على تشغيل، يمكنك أن تلاحظ أنك ستحصل على نتيجة على الفور، كما يلي:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

بعد لحظة، يمكننا ملاحظة نتيجة الصورة المولدة على https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab، كما هو موضح في الصورة:

المحتوى كما يلي:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}

يمكنك أن ترى أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق ارتباط المهمة.

معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم الواجهة بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

400 token_mismatched：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
400 api_not_implemented：طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
401 invalid_token：غير مصرح به، رمز تفويض غير صالح أو مفقود.
429 too_many_requests：طلبات كثيرة جدًا، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
500 api_error：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الاستنتاج

من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات توليد الصور من Flux من خلال إدخال كلمات التوجيه لتوليد الصور. نأمل أن تساعدك هذه الوثيقة في التوصيل واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

Coding

واجهة برمجة تطبيقات توليد صور Flux - تعليمات الدمج

عملية التقديم

الاستخدام الأساسي

تحرير مهمة الصورة

استدعاء غير متزامن

معالجة الأخطاء

مثال على استجابة الخطأ

الاستنتاج

​عملية التقديم

​الاستخدام الأساسي

​تحرير مهمة الصورة

​استدعاء غير متزامن

​معالجة الأخطاء

​مثال على استجابة الخطأ

​الاستنتاج

عملية التقديم

الاستخدام الأساسي

تحرير مهمة الصورة

استدعاء غير متزامن

معالجة الأخطاء

مثال على استجابة الخطأ

الاستنتاج