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

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

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد صور Flux للتقدم للحصول على الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول والتسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، وسلوك التوليد action، وحجم الصورة size، للحصول على النتيجة المعالجة، أولاً نحتاج إلى تمرير حقل action، وقيمته هي generate، ثم نحتاج أيضًا إلى إدخال كلمة التلميح، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • action: سلوك مهمة توليد الصورة هذه.
  • size: حجم نتيجة توليد الصورة.
  • count: عدد الصور المولدة، القيمة الافتراضية هي 1، هذه المعلمة تكون فعالة فقط في مهمة توليد الصور، ولا تكون فعالة في مهمة التحرير.
  • prompt: كلمة التلميح.
  • model: نموذج التوليد، الافتراضي هو flux-dev.
  • callback_url: URL الذي يحتاج إلى استدعاء النتيجة.
توجد بعض القيود الخاصة على المعلمة size، والتي تنقسم بشكل رئيسي إلى نوعين: نسبة العرض إلى الارتفاع width x height، ونسبة الصورة x:y، كما هو موضح أدناه:
النموذجالنطاق
flux-2-flexيدعم نسبة العرض إلى الارتفاع x >= 64 يجب أن تكون مضاعفًا لـ 32
flux-2-proيدعم نسبة العرض إلى الارتفاع x >= 64 يجب أن تكون مضاعفًا لـ 32
flux-2-maxيدعم نسبة العرض إلى الارتفاع x >= 64 يجب أن تكون مضاعفًا لـ 32
flux-pro-1.1يدعم نسبة العرض إلى الارتفاع 256 <= x <= 1440 يجب أن تكون مضاعفًا لـ 32
flux-devيدعم نسبة العرض إلى الارتفاع 256 <= x <= 1440 يجب أن تكون مضاعفًا لـ 32
flux-pro-1.1-ultraلا يدعم نسبة العرض إلى الارتفاع يدعم نسبة الصورة
flux-kontext-proلا يدعم نسبة العرض إلى الارتفاع يدعم نسبة الصورة
flux-kontext-maxلا يدعم نسبة العرض إلى الارتفاع يدعم نسبة الصورة
نسب الصور المرجعية: “1:1” ، “16:9”، “21:9” ، “3:2”، “2:3”، “4:5”، “5:4”، “3:4”، “4:3”، “9:16”، “9:21”، بعد الاختيار، يمكنك أن تلاحظ أن الكود المقابل تم توليده على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "226eb763-9eab-4d06-ad57-d59753a03307",
  "trace_id": "089f8b46-0167-4f25-88ee-3c3f88d80e84",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/lion/NVhtlwwGYQD6HrGaEfrzu_341484fad6d84b21b73f4f8824a3f98a.png",
      "timings": 1752743801
    },
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/8UEQpFbQCYVOK1wKP3aV0_9bbc26fad64049b18d0244b99ef66ad1.png",
      "timings": 1752743801
    }
  ]
}
تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:
  • 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 white siamese cat",
  "model": "flux-kontext-pro",
  "count": 2
}'

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

إذا كنت ترغب في تحرير صورة معينة، يجب أولاً تمرير معلمة image_url التي تحتوي على رابط الصورة التي تحتاج إلى تحريرها، في هذه الحالة، يدعم action فقط edit، يمكنك تحديد المحتويات التالية:
  • model: النموذج المستخدم في مهمة تحرير الصورة، حاليًا تدعم هذه المهمة flux-kontext-max، flux-kontext-pro.
  • 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://fal.media/files/monkey/aEUXJZ6Faj9YXUCQVs01Q_af0cea56c558441c9ba8df67b200812d.png",
      "timings": 1752744073
    }
  ]
}
يمكننا أن نرى أن التأثير الناتج هو تأثير تحرير الصورة الأصلية، والنتيجة مشابهة لما سبق.

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

由于 Flux Images Generation API生成的时间相对较长，大约需要1-2分钟，如果API长时间无响应，HTTP请求会一直保持连接，导致额外的系统资源消耗，所以本API也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个callback_url字段，客户端发起API请求之后，API会立马返回一个结果，包含一个task_id的字段信息，代表当前的任务ID。当任务完成之后，生成图片的结果会通过POST JSON的形式发送到客户端指定的callback_url，其中也包括了task_id字段，这样任务结果就可以通过ID关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook回调是一个可以接收HTTP请求的服务，开发者应该替换为自己搭建的HTTP服务器的URL。此处为了方便演示，使用一个公开的Webhook样例网站https://webhook.site/，打开该网站即可得到一个Webhook URL，如图所示： 将此URL复制下来，就可以作为Webhook来使用，此处的样例为https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。 接下来，我们可以设置字段callback_url为上述Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下： 
{
  "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://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/f4f8d407-377a-408a-82d0-427a5a836f09_0.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}
可以看到结果中有一个task_id字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

​
错误处理

在调用API时，如果遇到错误，API会返回相应的错误代码和信息。例如：
  • 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 Images Generation API可通过输入提示词来生成图片。希望本文档能帮助您更好地对接和使用该API。如有任何问题，请随时联系我们的技术支持团队。