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

# تعليمات تكامل واجهة برمجة تطبيقات توليد الصور SeeDream

> ByteDance Seedream Image Generation 集成指南 - XHuoAPI

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

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

لاستخدام API، يجب أولاً التقدم للحصول على الخدمة المناسبة من خلال صفحة [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images). بعد الدخول إلى الصفحة، اضغط على زر "Acquire" كما هو موضح في الصورة:

![](https://cdn.xhuoapi.ai/q6ytrc.png)

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

عند التقديم لأول مرة، ستحصل على حصة مجانية لاستخدام API مجانًا.

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

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

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

يمكننا رؤية إعدادات رؤوس الطلب (Request Headers) التي تشمل:

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

كما تم إعداد جسم الطلب (Request Body) ليشمل:

* `prompt`: كلمة التوجيه.
* `model`: نموذج التوليد، الافتراضي هو `doubao-seedream-5.0-lite`. يدعم النماذج `doubao-seedream-5.0-lite` (الأحدث)، `doubao-seedream-4.5`، `doubao-seedream-4.0`، `doubao-seedream-3.0-t2i`، و`doubao-seededit-3.0-i2i`.
* `image`: معلومات الصورة المدخلة، تدعم URL أو ترميز Base64. حيث يدعم `doubao-seedream-5.0-lite`، `doubao-seedream-4.5`، و`doubao-seedream-4.0` إدخال صورة واحدة أو متعددة، بينما يدعم `doubao-seededit-3.0-i2i` صورة واحدة فقط، و`doubao-seedream-3.0-t2i` لا يدعم هذا المعامل.
* `size`: تحديد أبعاد الصورة الناتجة، ويدعم طريقتين لا يمكن دمجهما:
  * الطريقة 1 | تحديد دقة الصورة الناتجة مع وصف نسبة العرض إلى الارتفاع باستخدام لغة طبيعية في `prompt`. **تختلف الإعدادات المسبقة المدعومة حسب النموذج**: يدعم `doubao-seedream-5.0-lite` دقات `2K`/`3K`/`4K`؛ و`doubao-seedream-4.5` يدعم فقط `2K`/`4K`؛ و`doubao-seedream-4.0` يدعم `1K`/`2K`/`4K`؛ بينما `doubao-seedream-3.0-t2i` و`doubao-seededit-3.0-i2i` **لا يدعمان الإعدادات المسبقة** ويقبلان فقط الطريقة 2.
  * الطريقة 2 | تحديد أبعاد الصورة بوحدات البكسل: الافتراضي `2048x2048`، مع نطاقات مختلفة لإجمالي البكسلات ونسبة العرض إلى الارتفاع حسب النموذج (مثلاً الحد الأدنى لإجمالي البكسلات في 5.0 / 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`**.
* `sequential_image_generation`: توليد مجموعة صور مرتبطة بناءً على المحتوى المدخل. يدعم هذا المعامل `doubao-seedream-5.0-lite`، `doubao-seedream-4.5`، و`doubao-seedream-4.0`، والافتراضي هو `disabled`.
* `stream`: التحكم في تفعيل وضع الإخراج المتدفق. يدعمه `doubao-seedream-5.0-lite`، `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`.
* `output_format`: تحديد صيغة ملف الصورة الناتجة، يدعم `jpeg` (الافتراضي) و`png`. يدعمه فقط `doubao-seedream-5.0-lite`.
* `tools`: إعداد الأدوات التي يستدعيها النموذج، حاليًا يدعم `web_search` (بحث عبر الإنترنت). يدعمه فقط `doubao-seedream-5.0-lite`.
* `callback_url`: عنوان URL لاستقبال نتائج الاستدعاء العكسي.

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

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

اضغط على زر "Try" للاختبار، وستحصل على النتيجة التالية:

```json theme={null}
{
  "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.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}
```

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

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

يمكننا رؤية أننا حصلنا على معلومات صورة مرضية، ونحتاج فقط إلى استخدام رابط الصورة في `data` للحصول على صورة SeeDream الناتجة.

إذا أردت توليد كود التكامل مباشرة، يمكنك نسخه مثلًا كود CURL التالي:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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-5.0-lite`، `doubao-seedream-4.5`، و`doubao-seedream-4.0` إدخال صورة واحدة أو متعددة، و`doubao-seededit-3.0-i2i` يدعم صورة واحدة فقط.
* `image`: تحميل الصورة أو الصور المراد تحريرها.

مثال تعبئة النموذج:

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

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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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)
```

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

```json theme={null}
{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}
```

يمكن ملاحظة أن النتيجة تمثل تأثير تحرير الصورة الأصلية، والنتيجة مشابهة لما سبق.

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

نظرًا لأن توليد الصور عبر SeeDream Images Generation API يستغرق وقتًا نسبيًا طويلًا (حوالي 1-2 دقيقة)، وإذا لم يستجب API لفترة طويلة، سيظل اتصال HTTP مفتوحًا مما يستهلك موارد النظام. لذلك، توفر هذه الواجهة دعم الاستدعاء العكسي غير المتزامن.

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

فيما يلي مثال عملي:

بعد التشغيل، ستحصل فورًا على النتيجة التالية:

```
{
  "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": "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}
```

يمكن ملاحظة وجود حقل `task_id` في النتيجة، وبقية الحقول مماثلة لما سبق، مما يتيح ربط نتائج المهام باستخدام هذا المعرف.

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

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

* `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 Images Generation API لتوليد الصور عبر إدخال كلمات التوجيه. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأفضل للواجهة. لأي استفسارات، لا تتردد في التواصل مع فريق الدعم الفني لدينا.