دليل تكامل SeeDream Images Generation API

​

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

📘 الوثائق الكاملة: SeeDream Images Generation API →

​

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

• accept: التنسيق الذي ترغب في تلقي النتيجة المستجيبة به، ويُملأ هنا بـ application/json، أي تنسيق JSON.
• authorization: مفتاح استدعاء API، ويمكنك الاختيار مباشرة من القائمة المنسدلة بعد التقديم.

• prompt: كلمة التلميح.
• model: نموذج التوليد، الافتراضي هو doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite، الأحدث). يدعم doubao-seedream-5-0-pro-260628، وdoubao-seedream-5-0-lite-260128، وdoubao-seedream-4-5-251128، وdoubao-seedream-4-0-250828. من بينها، doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) هو نموذج رائد للصورة المفردة، وينشئ صورة مفردة فقط، ولا يدعم مجموعة الصور (sequential_image_generation) أو البث (stream) أو البحث عبر الإنترنت (tools). يجب تمرير سلسلة النموذج الكاملة إلى model (مثل doubao-seedream-5-0-lite-260128)، وتمرير اختصار مثل doubao-seedream-5.0-lite سيؤدي إلى إرجاع 400.
• image: معلومات الصورة المُدخلة، وتدعم URL أو ترميز Base64. يدعم doubao-seedream-5-0-pro-260628 إدخال صورة واحدة أو صور متعددة (بحد أقصى 10 صور)، بينما يدعم doubao-seedream-5-0-lite-260128، وdoubao-seedream-4-5-251128، وdoubao-seedream-4-0-250828 إدخال صورة واحدة أو صور متعددة.
• size: تحدد معلومات حجم الصورة المُنشأة، وتدعم الطريقتين التاليتين ولا يمكن خلطهما. الطريقة 1 | تحديد دقة الصورة المُنشأة، ووصف نسبة العرض إلى الارتفاع للصورة بلغة طبيعية في prompt. تختلف الإعدادات المسبقة المدعومة بين النماذج: يدعم doubao-seedream-5-0-pro-260628 ‏1K/1.5K/2K؛ ويدعم doubao-seedream-5-0-lite-260128 ‏2K/3K/4K؛ ويدعم doubao-seedream-4-5-251128 ‏2K/4K فقط؛ ويدعم doubao-seedream-4-0-250828 ‏1K/2K/4K. الطريقة 2 | تحديد قيم بكسل العرض والارتفاع للصورة المُنشأة: الافتراضي هو 2048x2048، ويختلف نطاق إجمالي البكسلات ونسبة العرض إلى الارتفاع حسب النموذج (على سبيل المثال، نطاق إجمالي البكسلات لـ 5.0 Pro هو [921600, 4624220]، والحد الأدنى لإجمالي البكسلات لـ 5.0 Lite / 4.5 هو 3,686,400، ولـ 4.0 هو 921,600).
• sequential_image_generation: مجموعة صور: مجموعة من الصور المترابطة في المحتوى، يتم إنشاؤها بناءً على المحتوى الذي أدخلته. يدعم doubao-seedream-5-0-lite-260128، وdoubao-seedream-4-5-251128، وdoubao-seedream-4-0-250828 هذه المعلمة، والافتراضي هو disabled.
• stream: يتحكم فيما إذا كان سيتم تفعيل وضع الإخراج المتدفق. يدعم doubao-seedream-5-0-lite-260128، وdoubao-seedream-4-5-251128، وdoubao-seedream-4-0-250828 هذه المعلمة، والافتراضي هو false.
• response_format: يحدد تنسيق الإرجاع للصورة المُنشأة. الافتراضي هو url، ويدعم أيضًا b64_json.
• watermark: ما إذا كانت ستتم إضافة علامة مائية إلى الصورة المُنشأة. الافتراضي هو true.
• output_format: يحدد تنسيق ملف الصورة المُنشأة، ويدعم jpeg (الافتراضي) وpng. لا يدعمه إلا doubao-seedream-5-0-pro-260628 وdoubao-seedream-5-0-lite-260128.
• tools: يضبط الأدوات التي سيستدعيها النموذج، ويدعم حاليًا web_search (البحث عبر الإنترنت). يدعمه Seedream 5.0 Lite فقط.
• optimize_prompt_options: إعدادات تحسين كلمة التلميح. يدعم 5.0 Pro ‏standard/fast؛ ويدعم 5.0 Lite و4.5 ‏standard فقط؛ ويدعم 4.0 ‏standard/fast.
• background: مدعوم فقط لتحرير الصورة المفردة في 5.0 Pro. يتطلب transparent إدخال PNG واحد مع قناة شفافية، ويجب أن يكون output_format هو png؛ أما opaque فهو خلفية عادية غير شفافة.
• layer_decomposition: يدعمه 5.0 Pro فقط. عند تعيينه إلى true، يجب إدخال PNG/JPEG واحد، ويمكن عدم تمرير prompt للتقسيم التلقائي، أو تحديد العناصر بلغة طبيعية/<bbox>؛ يدعم size ‏auto/1K/1.5K/2K. لا يمكن استخدام هذا الوضع مع مجموعة الصور أو البث أو البحث عبر الإنترنت أو background.
• callback_url: عنوان URL الذي يحتاج إلى نتيجة رد نداء.
• async: ما إذا كانت المعالجة ستكون في وضع غير متزامن. عند تعيينه إلى true، تُرجع الواجهة task_id فورًا، ولا حاجة لتوفير callback_url، ثم يتم الحصول على النتيجة عبر الاستعلام الدوري من /seedream/tasks.

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

• success، حالة مهمة إنشاء الفيديو في هذا الوقت.
• task_id، معرّف مهمة إنشاء الفيديو في هذا الوقت.
• trace_id، معرّف تتبع إنشاء الفيديو في هذا الوقت.
• data، قائمة نتائج مهمة إنشاء الصور في هذا الوقت.
  • image_url، رابط مهمة إنشاء الصورة في هذا الوقت.
  • prompt، نص التلميح.
  • size: بكسلات الصورة المُنشأة

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-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

​

مهمة تعديل الصور

• model: النموذج المستخدم في مهمة تعديل الصور هذه، تدعم كل من doubao-seedream-5-0-pro-260628 وdoubao-seedream-5-0-lite-260128 وdoubao-seedream-4-5-251128 وdoubao-seedream-4-0-250828 إدخال الصور.
• image: رفع الصورة أو الصور التي تحتاج إلى تعديل

import requests

url = "https://api.acedata.cloud/seedream/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": "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.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

​

تفكيك الطبقات (Seedream 5.0 Pro)

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

​

الإخراج المتدفق

​

معاودة الاتصال غير المتزامنة

{
  "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"
        }
    ]
}

​

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

• 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"
}

​

الخلاصة