> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# SeeDream Images Generation API توضيح الربط

> ByteDance Seedream Image Generation API guide - Ace Data Cloud

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

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

لاستخدام SeeDream Images Generation API، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [SeeDream Images Generation API →](https://platform.acedata.cloud/documents/seedream-images)

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

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

<p>
  <img src="https://cdn.acedata.cloud/seedream_request_body.png" width="500" className="m-auto" />
</p>

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

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

كما تم تعيين جسم الطلب، بما في ذلك:

* `prompt`: كلمة التلميح.
* `model`: نموذج التوليد، الافتراضي هو `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite، الأحدث). يدعم `doubao-seedream-5-0-pro-260628`، `doubao-seedream-5-0-260128`، `doubao-seedream-4-5-251128`، `doubao-seedream-4-0-250828`، `doubao-seedream-3-0-t2i-250415`، `doubao-seededit-3-0-i2i-250628`. حيث أن `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) هو نموذج الصورة الفردية الرائد، يقوم بتوليد صورة واحدة فقط، **لا يدعم توليد مجموعة من الصور (`sequential_image_generation`)، أو التدفق (`stream`) أو البحث عبر الإنترنت (`tools`)**. **يجب تمرير `model` كسلسلة نموذج كاملة (مثل `doubao-seedream-5-0-260128`)، تمرير اختصارات مثل `doubao-seedream-5.0-lite` سيؤدي إلى إرجاع 400.**
* `image`: معلومات الصورة المدخلة، تدعم URL أو ترميز Base64. حيث أن `doubao-seedream-5-0-pro-260628` يدعم إدخال صورة واحدة أو عدة صور (من 2 إلى 10 صور، بدءًا من الصورة الثانية يتم احتسابها)، بينما `doubao-seedream-5-0-260128`، `doubao-seedream-4-5-251128`، `doubao-seedream-4-0-250828` تدعم إدخال صورة واحدة أو عدة صور، و`doubao-seededit-3-0-i2i-250628` تدعم إدخال صورة واحدة فقط، و`doubao-seedream-3-0-t2i-250415` لا يدعم هذه المعلمة.
* `size`: تحديد معلومات حجم الصورة المولدة، تدعم طريقتين، لا يمكن استخدامهما معًا. الطريقة 1 | تحديد دقة الصورة المولدة، ووصف نسبة العرض إلى الارتفاع باللغة الطبيعية في `prompt`. **تختلف الإعدادات المدعومة لكل نموذج**: `doubao-seedream-5-0-pro-260628` يدعم `1K`/`2K`؛ `doubao-seedream-5-0-260128` يدعم `2K`/`3K`/`4K`؛ `doubao-seedream-4-5-251128` يدعم فقط `2K`/`4K`؛ `doubao-seedream-4-0-250828` يدعم `1K`/`2K`/`4K`؛ `doubao-seedream-3-0-t2i-250415` و `doubao-seededit-3-0-i2i-250628` **لا يدعمان الإعدادات**، يقبلان فقط الطريقة 2. الطريقة 2 | تحديد قيم بكسل العرض والارتفاع للصورة المولدة: الافتراضي هو `2048x2048`، نطاق القيم الكلية للبكسل ونسبة العرض إلى الارتفاع تختلف حسب النموذج (على سبيل المثال، نطاق البكسل الكلي لـ 5.0 Pro هو \[921600, 4194304]، الحد الأدنى للبكسل لـ 5.0 Lite / 4.5 هو 3,686,400، الحد الأدنى لـ 4.0 هو 921,600، نطاق 3.0-t2i / seededit-3.0-i2i هو \[512x512, 2048x2048]).
* `seed`: بذور الأرقام العشوائية، تستخدم للتحكم في عشوائية المحتوى الذي ينتجه النموذج. نطاق القيم هو \[-1, 2147483647]. **فقط `doubao-seedream-3-0-t2i-250415` يدعم هذه المعلمة**.
* `sequential_image_generation`: مجموعة الصور: بناءً على المحتوى الذي أدخلته، يتم توليد مجموعة من الصور المرتبطة. `doubao-seedream-5-0-260128`، `doubao-seedream-4-5-251128`، `doubao-seedream-4-0-250828` تدعم هذه المعلمة، الافتراضي هو `disabled`.
* `stream`: التحكم في ما إذا كان سيتم تفعيل وضع الإخراج المتدفق. `doubao-seedream-5-0-260128`، `doubao-seedream-4-5-251128`، `doubao-seedream-4-0-250828` تدعم هذه المعلمة، الافتراضي هو `false`.
* `guidance_scale`: درجة توافق نتائج النموذج مع `prompt`، كلما زادت القيمة، زادت العلاقة. نطاق القيم هو \[1, 10]. القيمة الافتراضية لـ `doubao-seedream-3-0-t2i-250415` هي 2.5، والقيمة الافتراضية لـ `doubao-seededit-3-0-i2i-250628` هي 5.5، النماذج الأخرى لا تدعم ذلك.
* `response_format`: تحديد تنسيق الإرجاع للصورة المولدة. الافتراضي هو `url`، ويدعم أيضًا `b64_json`.
* `watermark`: ما إذا كان يجب إضافة علامة مائية إلى الصورة المولدة. الافتراضي هو `true`.
* `output_format`: تحديد تنسيق ملف الصورة المولدة، يدعم `jpeg` (الافتراضي) و `png`. فقط `doubao-seedream-5-0-pro-260628` و `doubao-seedream-5-0-260128` يدعمان ذلك.
* `tools`: تكوين الأدوات التي يجب على النموذج استدعاؤها، حاليًا يدعم `web_search` (البحث عبر الإنترنت). فقط `doubao-seedream-5-0-260128` يدعم ذلك.
* `callback_url`: URL الذي يحتاج إلى استدعاء النتائج.
* `async`: ما إذا كان يجب معالجة الطلب بطريقة غير متزامنة. عند تعيينها إلى `true`، ستعيد الواجهة على الفور `task_id`، دون الحاجة لتقديم `callback_url`، ثم يمكنك الحصول على النتائج من خلال `/seedream/tasks`.

بعد الاختيار، يمكنك أن تلاحظ أنه تم توليد الكود المقابل على الجانب الأيمن، كما هو موضح في الصورة:

<p>
  <img src="https://cdn.acedata.cloud/seedream_image.png" width="500" className="m-auto" />
</p>

انقر على زر "Try" لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:

```json theme={null}
{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "لقطة منتج فوتوغرافية واقعية لزجاجة عطر من الزجاج المعالج على لوح أسود مبلل، ضوء رئيسي من صندوق ناعم واحد، قطرات ماء، خلفية داكنة ومزاجية، 85 مم ماكرو.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}
```

返回结果一共有多个字段，介绍如下：

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

يمكننا أن نرى أننا حصلنا على معلومات الصورة المرضية، كل ما علينا هو الحصول على صورة SeeDream المولدة من رابط الصورة في `data`.

إذا كنت ترغب في إنشاء كود تكامل مطابق، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي:

```shell theme={null}
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-260128",
  "prompt": "لقطة منتج فوتوغرافية واقعية لزجاجة عطر من الزجاج المعالج على لوح أسود مبلل، ضوء رئيسي من صندوق ناعم واحد، قطرات ماء، خلفية داكنة ومزاجية، 85 مم ماكرو."
}'
```

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

إذا كنت ترغب في تحرير صورة معينة، يجب أولاً تمرير رابط الصورة التي تحتاج إلى تحريرها في المعامل `image`.

* model: النموذج المستخدم في مهمة تحرير الصورة هذه، `doubao-seedream-5-0-260128`، `doubao-seedream-4-5-251128`، `doubao-seedream-4-0-250828` تدعم إدخال صورة واحدة أو عدة صور، `doubao-seededit-3-0-i2i-250628` تدعم إدخال صورة واحدة فقط.
* image: تحميل الصورة التي تحتاج إلى تحريرها، صورة واحدة أو عدة صور.

مثال على كيفية ملء النموذج:

<p>
  <img src="https://cdn.acedata.cloud/seedream_edit.png" width="500" className="m-auto" />
</p>

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

```python theme={null}
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": "احتفظ بوضعية النموذج وشكل الملابس السائلة المتدفقة دون تغيير. غير مادة الملابس من المعدن الفضي إلى ماء شفاف تمامًا (أو زجاج). من خلال تدفق السائل، يمكن رؤية تفاصيل بشرة النموذج. يتغير تأثير الضوء والظل من الانعكاس إلى الانكسار.",
  "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)
```

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

```json theme={null}
{
    "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 تستغرق وقتًا طويلاً نسبيًا، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة.

تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل `callback_url` إضافي، بعد أن يقوم العميل بإرسال طلب API، ستقوم الواجهة على الفور بإرجاع نتيجة تحتوي على حقل `task_id`، الذي يمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة الصورة المولدة إلى `callback_url` المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل `task_id`، بحيث يمكن ربط نتيجة المهمة من خلال المعرف.

إذا لم يكن لديك عنوان عام للرد، يمكنك عدم تحديد `callback_url`، ولكن في الطلب، قم بتعيين حقل `async` إلى `true`. في هذه الحالة، ستقوم الواجهة أيضًا بإرجاع `task_id` على الفور، ولكن لن يتم دفع النتيجة، ستحتاج إلى استخدام `task_id` لاستدعاء واجهة `/seedream/tasks` للاستعلام عن حالة المهمة للحصول على النتيجة النهائية.

دعونا نفهم كيفية القيام بذلك من خلال مثال.

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

```
{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```

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

```json theme={null}
{
    "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`، وجميع الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكن تحقيق ارتباط المهمة.

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

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

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

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

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

## الخاتمة

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