واجهة برمجة تطبيقات Seedream v4.5 Edit: تحرير الصور البرمجي

تشغيل Seedream v4.5 Edit من خلال واجهة Arteza يعمل بشكل جيد للتعديلات الفردية والدفعات الصغيرة. بالنسبة لسير العمل عالي الحجم - الكتالوجات التي تحتوي على آلاف المنتجات، توليد الصور الديناميكي لكل مستخدم، خطوط أنابيب الأصول المدفوعة بنظام إدارة المحتوى - ستحتاج إلى الوصول عبر واجهة برمجية. يرشدك هذا الدليل عبر هيكل نقطة النهاية، معاملات الطلب، معالجة الاستجابة، والأنماط الإنتاجية لبناء أنظمة تحرير الصور المؤتمتة على Seedream v4.5.

ملخص سريع

• Seedream v4.5 Edit متاح عبر نقطة النهاية fal-ai/bytedance/seedream/v4.5/edit
• نفس 1 رصيد ($0.10) لكل سعر صورة كما هو الحال في الواجهة
• يقبل ما يصل إلى 10 عناوين URL للصور المدخلة بالإضافة إلى موجه نصي
• إخراج 4MP (2048×2048) يتم إرجاعه كعنوان URL للصورة
• وقت توليد نموذجي 30-60 ثانية - استخدم الأنماط غير المتزامنة للإنتاج

لماذا تستخدم واجهة برمجية التطبيقات

تفتح واجهة برمجية التطبيقات أنماط الأتمتة التي لا يمكن للواجهة مطابقتها:

• معالجة دفعية عالية الحجم. معالجة 1000+ تعديل في تشغيل خط أنابيب واحد.
• التوليد الديناميكي. بناء الصور عند الطلب من بيانات المستخدم أو سجلات قاعدة البيانات.
• سير العمل المجدول. تحديثات الكتالوج الليلية، إعادة التوليد المُشغلة بالأحداث.
• التكامل مع المكدسات الموجودة. Node.js و Python و Go و Ruby - أي عميل HTTP.
• الإنتاج القابل للتكرار. البرامج النصية المتحكم فيها بالإصدار بدلاً من النقرات اليدوية.

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

هيكل نقطة النهاية

نموذج Seedream v4.5 Edit متاح على:

fal-ai/bytedance/seedream/v4.5/edit

هذه نقطة نهاية نموذج fal.ai قياسية يمكن استدعاؤها مباشرة أو عبر نظام رصيد Arteza.

المصادقة

تتحقق طلبات واجهة برمجية Arteza من خلال مفتاح واجهة برمجية يتم تمريره في رأس Authorization كرمز Bearer.

الحصول على مفتاح واجهة برمجية التطبيقات الخاص بك

1. سجل الدخول على arteza.ai
2. انتقل إلى إعدادات حسابك
3. ابحث عن قسم واجهة برمجية التطبيقات
4. إنشاء مفتاح واجهة برمجية جديد
5. قم بتخزينه بأمان - تعامل معه مثل كلمة المرور

لا تلتزم أبداً بمفتاح واجهة برمجية التطبيقات الخاص بك بالتحكم في المصدر. استخدم متغيرات البيئة:

export SEEDANCE_API_KEY="your_api_key_here"

رأس المصادقة

Authorization: Bearer your_api_key_here

هيكل الطلب

يبدو طلب Seedream v4.5 Edit الأساسي كما يلي:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

مرجع المعاملات

يمكن تمرير ما يصل إلى 10 عناوين URL للصور. يتعامل النموذج مع الصورة الأولى كصورة أساسية والصور اللاحقة كمراجع.

طلب عينة: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

طلب عينة: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

هيكل الاستجابة

تتضمن الاستجابة الناجحة عناوين URL للصور المُنشأة:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

قم بتنزيل الصورة من عنوان URL المُرجع - عناوين URL المخرجات صالحة لمدة 24 ساعة.

نمط التوليد غير المتزامن

يستغرق Seedream v4.5 Edit 30-60 ثانية لكل طلب. بالنسبة للإنتاج، ستريد على الأرجح توليداً غير متزامن مع webhooks أو استطلاع بدلاً من الطلبات المحجوبة.

غير المتزامن القائم على Webhook

مرر webhook_url في طلبك وسيقوم Arteza بنشر النتيجة عليه عند اكتمال التوليد:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

يتلقى معالج webhook الخاص بك:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

معالجة Webhook هي نمط الإنتاج الموصى به.

ابدأ البناء. جرّب الأداة أولاً.

غير المتزامن القائم على الاستطلاع

إذا لم تتمكن البنية الأساسية الخاصة بك من استقبال webhooks، فقم باستطلاع الحالة:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Poll for completion
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

قم باستطلاع كل 5-10 ثوان. الانتظار الإجمالي عادة ما يكون 30-60 ثانية.

أنماط الإنتاج

النمط 1: توليد دفعة الكتالوج

قم بتشغيل واجهة برمجية التطبيقات على كتالوج المنتجات الخاص بك لتوليد مبادلات خلفية متسقة لكل SKU:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

اجمع مع معالج webhook يحفظ المخرجات على شبكة CDN الخاصة بك ويحدث سجل المنتج.

النمط 2: تعديلات المستخدم عند الطلب

دع المستخدمين يرفعون الصور ويحصلون على نتائج معدلة بذكاء عند الطلب:

1. يرفع المستخدم الصورة إلى دلو الخاص بك
2. يستدعي الخادم الخاص بك Seedream v4.5 Edit بموجه يختاره المستخدم
3. الاستطلاع أو انتظار webhook
4. إرجاع عنوان URL النتيجة إلى عميل المستخدم

ميزانية حوالي 60 ثانية من وقت الانتظار لكل تعديل في تجربة المستخدم الخاصة بك.

النمط 3: خط أنابيب الأصول المدفوع بنظام إدارة المحتوى

عند نشر المحتوى في نظام إدارة المحتوى الخاص بك، قم بإنشاء الصور المرتبطة تلقائياً:

1. ينبعث نظام إدارة المحتوى حدث النشر
2. تُشغل دالة بدون خادم
3. استدعاء Seedream v4.5 Edit بموجه نموذجي
4. تخزين النتيجة على CDN
5. تحديث سجل نظام إدارة المحتوى برابط الصورة

يلغي هذا النمط إنشاء الصور اليدوية للنشر عالي الحجم.

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

استجابات الخطأ الشائعة:

قم دائماً بلف استدعاءات واجهة برمجية التطبيقات في try/except مع منطق إعادة المحاولة لاستجابات 429 و 500.

حدود المعدل

تطبق Arteza حدود معدل معقولة على واجهة برمجية التطبيقات. بالنسبة لمعظم سير العمل الإنتاجي، لن تصل إليها، لكن بالنسبة للدفعات الكبيرة من 1000+ طلب، قم بتنفيذ:

• التراجع الأسي عند استجابات 429
• حدود الطلب المتزامن (ابدأ بـ 5 متوازي، اضبط لأعلى)
• قائمة انتظار الطلب للإنتاجية المتوقعة

اتصل بالدعم للحصول على حدود معدل أعلى على أحمال العمل الإنتاجية الثقيلة.

التكلفة بحجم واجهة برمجية التطبيقات

تكلف استدعاءات واجهة برمجية التطبيقات نفس استدعاءات الواجهة: 1 أرصدة ($0.10) لكل صورة. لأغراض التخطيط:

• 100 استدعاء واجهة برمجية = 100 رصيد (جيد جداً ضمن خطة Starter بقيمة 5 دولارات)
• 1000 استدعاء واجهة برمجية = 1000 رصيد (خطة Studio بقيمة 120 دولار، 1800 شهرياً)
• 10000 استدعاء واجهة برمجية = 10000 رصيد (خطة Studio بقيمة 120 دولار بالإضافة إلى حوالي 8200 رصيد في عمليات الملء)

للأحجام فوق 10000/شهر، اتصل بالفريق للحصول على تسعير مخصص.

أفضل الممارسات

1. استخدم webhooks في الإنتاج. يعمل الاستطلاع لكنه يهدر الموارد.
2. قم بتخزين الموجهات في التحكم بالإصدار. تعامل مع الموجهات مثل الكود.
3. سجل كل شيء. معرفات الطلب والموجهات والمخرجات والأخطاء.
4. تحقق من المدخلات قبل الاستدعاء. عناوين URL الصور السيئة تهدر الأرصدة.
5. راقب رصيد الأرصدة. تنبيه عند الانخفاض أقل من حد معين.
6. اختبر تغييرات الموجه في التدريج. تحقق من 3-5 صور قبل تشغيل دفعة كاملة.
7. النتائج المخزنة مؤقتاً. إذا كانت المدخلات متطابقة، أعد استخدام المخرجات السابقة.

قراءة إضافية

• دليل تعديل Seedream v4.5 الكامل
• درس تحرير دفعي
• تفصيل الأسعار

ابدأ

قم بإنشاء مفتاح واجهة برمجية في لوحة معلومات Arteza، واحصل على 10 أرصدة مجانية، وقم بتشغيل مثال Node.js أعلاه بصورة منتج. تفتح واجهة برمجية التطبيقات الإمكانات الإنتاجية الكاملة لـ Seedream v4.5 Edit - بمجرد توصيلها، كل شيء آخر هو هندسة الموجه. للاختبار العملي أولاً، افتح أداة الويب والتحقق من الموجهات الخاصة بك قبل الأتمتة.