واجهة برمجة تطبيقات Seedream 5.0 Lite: أسرع نقطة نهاية لتوليد الصور

REST API، مصادقة Bearer، إنشاء غير متزامن، webhooks، معالجة دفعات أصلية تصل إلى 50 صورة لكل طلب. كل شيء متاح في واجهة Arteza الويب متاح أيضًا في API. إليك المرجع الكامل مع أمثلة Python و JavaScript عاملة يمكنك نسخها إلى الإنتاج اليوم.

ملخص سريع

• POST /v1/images/generate - نقطة نهاية صورة واحدة
• POST /v1/images/batch - حتى 50 صورة لكل طلب
• متوسط زمن انتظار 5-15 ثانية تقريبًا مع دعم async و webhook
• Python و JavaScript SDKs متاحة (seedance / @seedance/sdk)
• مصادقة Bearer token - إنشاء مفاتيح في Settings > API Keys

نظرة عامة على API

يوفر Seedream 5.0 Lite API وصولاً برمجيًا إلى خط أنابيب إنشاء الصور على منصة Arteza. كل شيء في واجهة الويب - text-to-image، deep thinking، style transfer، text rendering - موجود في REST API.

يتبع API اتفاقيات REST مع أجسام طلب واستجابة JSON. الإنشاء غير متزامن: قدم طلبًا، احصل على معرّف مهمة، ثم إما قم بالاستطلاع أو استقبل webhook عند الانتهاء.

نظرة عامة كاملة على الميزات في دليل شامل.

عنوان URL الأساسي

https://api.arteza.ai/v1

الخصائص الرئيسية

المصادقة

مصادقة Bearer token. أنشئ مفتاح API الخاص بك من لوحة تحكم Arteza ضمن Settings > API Keys.

الحصول على مفتاح API الخاص بك

1. إنشاء حساب أو قم بتسجيل الدخول إلى حسابك في Arteza
2. انتقل إلى Settings > API Keys
3. انقر على Generate New Key
4. انسخ وخزّن مفتاحك بأمان (يظهر مرة واحدة فقط)

رأس المصادقة

Authorization: Bearer YOUR_API_KEY

اختبار المصادقة

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.arteza.ai/v1/account/credits

الاستجابة:

{
  "credits_remaining": 1050,
  "tier": "starter"
}

نقطة نهاية صورة واحدة

POST /v1/images/generate

طلب بسيط

{
  "model": "seedream-5.0-lite",
  "prompt": "A serene mountain landscape at sunrise"
}

طلب كامل

{
  "model": "seedream-5.0-lite",
  "prompt": "Professional YouTube thumbnail with text 'TOP 10 TIPS' in bold red font, excited person on left, bright blue background",
  "aspect_ratio": "16:9",
  "deep_thinking": true,
  "style": "photorealistic",
  "webhook_url": "https://your-app.com/webhook/image-complete",
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  }
}

الاستجابة

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "credits_remaining": 1043,
  "estimated_time_seconds": 10
}

معاملات الطلب

نسب العرض إلى الارتفاع

إعدادات النمط

تنسيق الاستجابة

الاستطلاع عن النتائج

GET /v1/images/{task_id}

قيد المعالجة:

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "progress": 0.65,
  "estimated_time_remaining": 5
}

مكتمل:

{
  "task_id": "img_abc123def456",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "image_url_webp": "https://cdn.arteza.ai/generated/img_abc123def456.webp",
  "width": 1024,
  "height": 1024,
  "model": "seedream-5.0-lite",
  "deep_thinking_used": true,
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

انتهاء صلاحية عنوان URL للصورة

عناوين URL للصور المُنشأة صالحة لمدة 24 ساعة. قم بتنزيل وتخزين الصور في التخزين الخاص بك ضمن هذه النافذة الزمنية.

هل تريد نصًا بهذا الوضوح؟ جرّب Seedream 5.0 Lite مجاناً →

مثال Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.arteza.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Submit generation request
response = requests.post(
    f"{BASE_URL}/images/generate",
    headers=headers,
    json={
        "model": "seedream-5.0-lite",
        "prompt": "A futuristic city skyline at sunset with flying cars",
        "aspect_ratio": "16:9",
        "deep_thinking": True
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Task submitted: {task_id}")
print(f"Credits charged: {task['credits_charged']}")
print(f"Credits remaining: {task['credits_remaining']}")

# Poll for completion
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Image ready: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Generation failed: {result.get('error', 'Unknown error')}")
        break

    time.sleep(2)

مثال JavaScript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.arteza.ai/v1';

async function generateImage(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/images/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedream-5.0-lite',
      prompt,
      aspect_ratio: options.aspectRatio || '1:1',
      deep_thinking: options.deepThinking || false,
      ...options
    })
  });

  const task = await response.json();
  console.log(`Task submitted: ${task.task_id}`);

  while (true) {
    const result = await fetch(
      `${BASE_URL}/images/${task.task_id}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    ).then(r => r.json());

    if (result.status === 'completed') {
      return result;
    }
    if (result.status === 'failed') {
      throw new Error(result.error || 'Generation failed');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Usage
const result = await generateImage(
  'A cozy coffee shop interior with warm lighting',
  { aspectRatio: '16:9', deepThinking: true }
);
console.log(`Image URL: ${result.image_url}`);

تنزيل الصور المُنشأة

import requests

def download_image(image_url, filename):
    response = requests.get(image_url)
    with open(filename, 'wb') as f:
        f.write(response.content)
    print(f"Saved: {filename}")

download_image(result['image_url'], 'output/my_image.png')

نقطة نهاية إنشاء الدفعات

لعدة صور في طلب واحد:

POST /v1/images/batch

طلب الدفعة

{
  "generations": [
    {
      "prompt": "Minimalist logo design, blue circle with lightning bolt",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": true
    },
    {
      "prompt": "Professional headshot background, soft gradient",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": false
    },
    {
      "prompt": "YouTube thumbnail with text 'MUST WATCH' in red",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "16:9",
      "deep_thinking": true
    }
  ],
  "webhook_url": "https://your-app.com/webhook/batch-complete"
}

استجابة الدفعة

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_generations": 3,
  "total_credits_charged": 21,
  "credits_remaining": 1029
}

الاستطلاع عن حالة الدفعة

GET /v1/images/batch/{batch_id}

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "task_id": "img_001",
      "image_url": "https://cdn.arteza.ai/generated/img_001.png"
    },
    {
      "index": 1,
      "status": "completed",
      "task_id": "img_002",
      "image_url": "https://cdn.arteza.ai/generated/img_002.png"
    },
    {
      "index": 2,
      "status": "completed",
      "task_id": "img_003",
      "image_url": "https://cdn.arteza.ai/generated/img_003.png"
    }
  ]
}

حدود الدفعة

لسير عمل الدفعات، راجع دليل الإنشاء الجماعي.

تكامل Webhook

تلغي Webhooks الاستطلاع. عند اكتمال الإنشاء، يقوم API بـ POST إلى عنوان URL الخاص بك.

حمولة Webhook

{
  "event": "image.completed",
  "task_id": "img_abc123def456",
  "batch_id": "batch_xyz789",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

مثال معالج (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/image-complete', methods=['POST'])
def handle_image_webhook():
    data = request.json

    if data['event'] == 'image.completed':
        task_id = data['task_id']
        image_url = data['image_url']
        metadata = data.get('metadata', {})

        # Download image
        img_response = requests.get(image_url)
        filename = f"images/{metadata.get('project', 'default')}/{task_id}.png"
        with open(filename, 'wb') as f:
            f.write(img_response.content)

        # Update your database
        update_generation_record(task_id, filename)

        print(f"Image saved: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Generation failed: {data.get('error')}")

    return jsonify({'status': 'ok'}), 200

أمان Webhook

تحقق من صحة webhook عبر رأس X-Seedance-Signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

وضع Deep Thinking

يتم التحكم فيه بواسطة معامل deep_thinking المنطقي. عند التفعيل، يقوم النموذج بإجراء استدلال إضافي قبل الإنشاء.

متى يتم التفعيل

تأثير الأداء

يضيف Deep thinking 3-5 ثوانٍ تقريبًا لكن لا يكلف رصيدًا إضافيًا.

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

تنسيق استجابة الخطأ

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation. Required: 7, Available: 3",
    "status": 402
  }
}

رموز الأخطاء

استراتيجية إعادة المحاولة

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/images/generate",
                headers=headers,
                json={
                    "model": "seedream-5.0-lite",
                    "prompt": prompt
                }
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

حدود المعدل وأفضل الممارسات

حدود المعدل حسب المستوى

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

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

تثبيت SDK

Python:

pip install seedance

from seedance import SeedanceClient

client = SeedanceClient(api_key="your_key")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A beautiful sunset",
    deep_thinking=True
)

JavaScript:

npm install @seedance/sdk

import { SeedanceClient } from '@seedance/sdk';

const client = new SeedanceClient({ apiKey: 'your_key' });
const result = await client.images.generate({
    model: 'seedream-5.0-lite',
    prompt: 'A beautiful sunset',
    deepThinking: true
});

أنماط التكامل الشائعة

تكامل CMS

إنشاء صور مميزة تلقائيًا عند إنشاء منشور:

@app.route('/cms/webhook/new-post', methods=['POST'])
def handle_new_post():
    post = request.json

    result = generate_image(
        prompt=f"Blog header image for article about {post['title']}, "
               f"professional editorial style, 16:9",
        aspect_ratio="16:9",
        deep_thinking=True,
        metadata={"post_id": post["id"]}
    )

    update_post_featured_image(post["id"], result["image_url"])

صور منتجات التجارة الإلكترونية

def generate_product_images(product):
    prompts = [
        f"Product photo of {product.name}, white background, studio lighting, 1:1",
        f"Lifestyle photo of {product.name} in use, natural setting, 16:9",
        f"Product detail close-up of {product.name}, macro photography, 1:1"
    ]

    batch = client.images.batch_generate(
        generations=[
            {"model": "seedream-5.0-lite", "prompt": p}
            for p in prompts
        ]
    )

    return batch

أتمتة وسائل التواصل الاجتماعي

def generate_weekly_social_content(brand, topics):
    generations = []
    for topic in topics:
        generations.append({
            "model": "seedream-5.0-lite",
            "prompt": f"{brand.style_prefix} {topic}, social media post, 1:1",
            "aspect_ratio": "1:1",
            "deep_thinking": True,
            "metadata": {"topic": topic, "platform": "instagram"}
        })

    return client.images.batch_generate(generations=generations)

---

Seedream 5.0 Lite API هو أسرع طريق من طلب نصي إلى صورة مُنشأة مع دعم كامل لـ deep thinking وإنشاء الدفعات وتكامل webhook.

احصل على مفتاح API الخاص بك → - 10 رصيد مجاني، أنشئ مفتاحك من Settings > API Keys، ابدأ البناء في دقائق.