الانتقال إلى المحتوى الرئيسي
ستتناول هذه المقالة شرح توصيل SeeDream Images Generation API، والتي يمكن من خلالها توليد صور SeeDream الرسمية عن طريق إدخال معلمات مخصصة.

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

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

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

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

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء API، بعد التقديم يمكنك اختيارها مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • prompt: كلمة التلميح.
  • model: نموذج التوليد، الافتراضي هو doubao-seedream-4.0.
  • image: معلومات الصورة المدخلة، تدعم URL أو ترميز Base64. حيث أن doubao-seedream-4.5، doubao-seedream-4.0 تدعم إدخال صورة واحدة أو عدة صور، بينما doubao-seededit-3.0-i2i تدعم إدخال صورة واحدة فقط، و doubao-seededit-3.0-t2i لا تدعم هذا المعامل.
  • size: تحديد معلومات حجم الصورة المولدة، تدعم الطريقتين التاليتين، ولا يمكن مزجهما. الطريقة 1 | تحديد دقة الصورة المولدة، ووصف نسبة العرض إلى الارتفاع، وشكل الصورة أو استخدامها بلغة طبيعية في prompt، ليقوم النموذج بتحديد حجم الصورة المولدة. الطريقة 2 | تحديد قيم بكسل العرض والارتفاع للصورة المولدة: القيمة الافتراضية: 2048x2048، تختلف القيم الافتراضية حسب النموذج.
  • seed: بذور الأرقام العشوائية، تستخدم للتحكم في عشوائية المحتوى الذي ينتجه النموذج. نطاق القيم هو [-1، 2147483647]. فقط doubao-seedream-3.0-t2i، doubao-seededit-3.0-i2i تدعم هذا المعامل.
  • sequential_image_generation: مجموعة الصور: بناءً على المحتوى الذي أدخلته، يتم توليد مجموعة من الصور المرتبطة. فقط doubao-seedream-4.5، doubao-seedream-4.0 تدعم هذا المعامل، القيمة الافتراضية هي disabled.
  • stream: التحكم في ما إذا كان يجب تشغيل وضع الإخراج المتدفق. فقط doubao-seedream-4.5، doubao-seedream-4.0 تدعم هذا المعامل، القيمة الافتراضية هي false.
  • guidance_scale: درجة توافق نتائج النموذج مع prompt، حرية توليد الصورة، والمعروفة أيضًا بوزن النص؛ كلما زادت القيمة، كانت حرية النموذج أقل، وزادت العلاقة مع كلمة التلميح المدخلة. نطاق القيم: [1، 10]. القيمة الافتراضية لـ doubao-seedream-3.0-t2i هي 2.5، والقيمة الافتراضية لـ doubao-seededit-3.0-i2i هي 5.5، ولا تدعم النماذج الأخرى.
  • response_format: تحديد تنسيق الاستجابة للصورة المولدة. القيمة الافتراضية هي url، كما تدعم b64_json.
  • watermark: ما إذا كان يجب إضافة علامة مائية إلى الصورة المولدة. القيمة الافتراضية هي true.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل تم توليده على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • trace_id: معرف تتبع توليد الفيديو في ذلك الوقت.
  • data: قائمة نتائج مهمة توليد الصورة في ذلك الوقت.
    • image_url: رابط مهمة توليد الصورة في ذلك الوقت.
    • prompt: كلمة التلميح.
    • size: بكسل الصورة المولدة.
يمكننا أن نرى أننا حصلنا على معلومات الصورة المرضية، كل ما علينا هو الحصول على صورة SeeDream المولدة من خلال رابط الصورة في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد كود التوصيل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-4-0-250828",
  "prompt": "a white siamese cat"
}'

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

إذا كنت ترغب في تحرير صورة معينة، يجب أولاً تمرير رابط الصورة التي تحتاج إلى تحريرها في المعامل image.
  • model: النموذج المستخدم في مهمة تحرير الصورة، تدعم هذه المهمة حاليًا doubao-seedream-4.5، doubao-seedream-4.0 إدخال صورة واحدة أو عدة صور، بينما doubao-seededit-3.0-i2i تدعم إدخال صورة واحدة فقط.
  • image: تحميل الصورة التي تحتاج إلى تحريرها، صورة واحدة أو عدة صور.
مثال على كيفية التعبئة كما يلي:

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

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

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

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند النقر على التشغيل، يمكنك أن ترى أنه سيتم الحصول على نتيجة على الفور، كما يلي: 
{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "احتفظ بوضعية النموذج وشكل الملابس السائلة المتدفقة دون تغيير. غير مادة الملابس من المعدن الفضي إلى الماء الشفاف تمامًا (أو الزجاج). من خلال تدفق السائل، يمكن رؤية تفاصيل جلد النموذج. يتغير تأثير الضوء والظل من الانعكاس إلى الانكسار.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}
يمكنك أن ترى أن التأثير الناتج هو تأثير تحرير الصورة الأصلية، والنتيجة مشابهة لما سبق.

​
ردود غير متزامنة

نظرًا لأن وقت توليد صور SeeDream Images Generation API طويل نسبيًا، حوالي 1-2 دقيقة، إذا لم يستجب API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك إضافي لموارد النظام، لذا فإن هذا API يوفر أيضًا دعمًا للردود غير المتزامنة. تتكون العملية العامة من: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب API، سيقوم API على الفور بإرجاع نتيجة تحتوي على معلومات حقل task_id، تمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة الصورة المولدة إلى callback_url المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. عند النقر على التشغيل، يمكنك أن تلاحظ أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
المحتوى كما يلي: 
{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "احتفظ بوضعية النموذج وشكل الملابس السائلة المتدفقة دون تغيير. غير مادة الملابس من المعدن الفضي إلى الماء الشفاف تمامًا (أو الزجاج). من خلال تدفق السائل، يمكن رؤية تفاصيل جلد النموذج. يتغير تأثير الضوء والظل من الانعكاس إلى الانكسار.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}
يمكنك أن ترى أن النتيجة تحتوي على حقل 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": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

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