واجهة برمجة تطبيقات Seedream v4.5: دمج صور الذكاء الاصطناعي في تطبيقك

كان دمج توليد الصور بالذكاء الاصطناعي في تطبيقك يعني اختيار واحد من ثلاثة خيارات سيئة: تشغيل Stable Diffusion بنفسك (بنية تحتية مكلفة)، أو الدفع لـ OpenAI بأسعار لكل رمز (تكاليف غير متوقعة)، أو الالتزام بـ API اشتراك (سعة مهدرة). تم بناء Seedream v4.5 API بشكل مختلف - ادفع لكل صورة بـ 0,10 دولار، REST قياسي، وأوقات استجابة تُقاس بالثواني. يأخذك هذا الدليل من الصفر إلى الجيل الأول في أقل من 10 دقائق.

ملخص سريع

• يكلف Seedream v4.5 API 1 رصيد ($0.10) لكل صورة يتم توليدها
• REST API قياسي مع طلبات واستجابات JSON
• المعاملات: prompt، resolution، aspect ratio، num_images (1-6)، guidance scale
• وقت الاستجابة النموذجي: 5-15 ثانية لكل جيل
• خطط من 5 دولار شهريًا - يتم إنفاق الأرصدة فقط عند التوليد

ما الذي يناسب API

يناسب Seedream v4.5 API التطبيقات التي تحتاج إلى توليد صور بالذكاء الاصطناعي عند الطلب مع تكاليف متوقعة لكل صورة. حالات الاستخدام الشائعة:

منتجات SaaS التي تسمح للمستخدمين بتوليد الصور كجزء من سير عملهم - أدوات التصميم، منصات التسويق، تطبيقات إنشاء المحتوى.

منصات التجارة الإلكترونية التي تولد صور نمط الحياة للمنتجات أو رؤوس الفئات برمجيًا.

أدوات أتمتة التسويق التي تنتج مرئيات الحملة بناءً على مدخلات منظمة.

أنظمة إدارة المحتوى التي تقدم توليد الصور بالذكاء الاصطناعي كميزة أصلية.

مشاريع المطورين وسكريبتات الأتمتة لأي سير عمل يحتاج إلى توليد صور على نطاق واسع.

تطبيقات الهاتف المحمول التي تستدعي API من خدمة خلفية للحفاظ على توليد الصور خارج الجهاز.

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

المصادقة والبدء

الخطوة 1: احصل على مفتاح API

إنشاء حساب لحساب Arteza إذا لم يكن لديك واحد. انتقل إلى إعدادات حسابك وأنشئ مفتاح API. تعامل مع هذا المفتاح مثل كلمة المرور - لا تلتزمه بالمستودعات العامة.

الخطوة 2: أضف أرصدة إلى حسابك

يسحب استخدام API من رصيد الأرصدة نفسه كما هو الحال مع الاستخدام على الويب. تعمل أرصدة التسجيل المجانية 10 على استدعاءات API. للاستخدام الإنتاجي، اشترك من صفحة التسعير بدءًا من 5 دولار.

الخطوة 3: قم بطلبك الأول

نقطة نهاية API لـ Seedream v4.5 هي:

POST https://api.arteza.ai/v1/images/generate

الحد الأدنى من نص الطلب:

{
  "model": "seedream-v4-5",
  "prompt": "A cozy bookstore at dusk, warm window light",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

أدرج مفتاح API الخاص بك في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

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

الدقة المدعومة

يدعم Seedream v4.5 خيارات دقة متعددة تصل إلى 4 ميجابكسل:

أمثلة الكود

Node.js (Fetch)

const generateImage = async (prompt) => {
  const response = await fetch(
    'https://api.arteza.ai/v1/images/generate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SEEDANCE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'seedream-v4-5',
        prompt: prompt,
        width: 2048,
        height: 2048,
        num_images: 1,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data.images[0].url;
};

// Usage
const imageUrl = await generateImage(
  'A cozy bookstore at dusk, warm window light, editorial photography'
);
console.log(imageUrl);

Python (Requests)

import os
import requests

def generate_image(prompt, width=2048, height=2048, num_images=1):
    response = requests.post(
        'https://api.arteza.ai/v1/images/generate',
        headers={
            'Authorization': f'Bearer {os.environ["SEEDANCE_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'seedream-v4-5',
            'prompt': prompt,
            'width': width,
            'height': height,
            'num_images': num_images,
        },
    )
    response.raise_for_status()
    data = response.json()
    return [img['url'] for img in data['images']]

# Usage
urls = generate_image(
    'An editorial product photograph of a ceramic coffee mug, '
    'warm morning light, minimalist composition'
)
print(urls)

cURL

curl -X POST https://api.arteza.ai/v1/images/generate \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-5",
    "prompt": "A futuristic city skyline at sunset, cinematic photography",
    "width": 2048,
    "height": 1152,
    "num_images": 1
  }'

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type GenerateRequest struct {
    Model     string `json:"model"`
    Prompt    string `json:"prompt"`
    Width     int    `json:"width"`
    Height    int    `json:"height"`
    NumImages int    `json:"num_images"`
}

func generateImage(prompt string) (string, error) {
    reqBody := GenerateRequest{
        Model:     "seedream-v4-5",
        Prompt:    prompt,
        Width:     2048,
        Height:    2048,
        NumImages: 1,
    }

    jsonData, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest(
        "POST",
        "https://api.arteza.ai/v1/images/generate",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SEEDANCE_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    images := result["images"].([]interface{})
    firstImage := images[0].(map[string]interface{})
    return firstImage["url"].(string), nil
}

صيغة الاستجابة

تُرجع الاستجابات الناجحة JSON بهذا الهيكل:

{
  "id": "gen_abc123xyz",
  "model": "seedream-v4-5",
  "created": 1712764800,
  "images": [
    {
      "url": "https://cdn.arteza.ai/gen/abc123.png",
      "width": 2048,
      "height": 2048,
      "seed": 42871
    }
  ],
  "credits_used": 8,
  "credits_remaining": 1042
}

عناوين URL للصور صالحة لمدة 24 ساعة. قم بتنزيل وتخزين الصور على الفور إذا كنت بحاجة إلى وصول دائم.

تريد تفاصيل مثل هذه؟ جرّب Seedream v4.5 مجانًا →

هل أنت مستعد للبدء في التكامل؟ احصل على مفتاح واجهة برمجة التطبيقات →

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

يُرجع API رموز حالة HTTP القياسية:

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

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits for this request",
    "credits_required": 8,
    "credits_available": 3
  }
}

قم دائمًا بتطبيق معالجة الأخطاء وإعادة المحاولة لأخطاء 429 و 500. لا تعيد محاولة أخطاء 400 و 401 - تلك تتطلب إصلاح الطلب نفسه.

أفضل الممارسات للاستخدام الإنتاجي

تحديد المعدل

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

تطبيق التراجع الأسي على أخطاء 429:

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return generate_image(prompt)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Max retries exceeded")

إدارة الأرصدة

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

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Low credit warning: {remaining} credits')

المعالجة غير المتزامنة

بالنسبة للتطبيقات التي تواجه المستخدم، تعامل مع توليد الصور كعملية غير متزامنة. لا تحجب خيط واجهة المستخدم على استدعاء API لمدة 5-15 ثانية. الأنماط:

• إرجاع معرّف الوظيفة على الفور، والاستقصاء عن الإكمال
• استخدام webhooks (إن كانت مدعومة) لإخطارات الإكمال
• توليد الصور بشكل استباقي في الخلفية والنتائج المخزنة مؤقتًا

التخزين المؤقت

الصور المولدة حتمية بالنظر إلى نفس prompt والبذرة. قم بالتخزين المؤقت بقوة بواسطة hash prompt لتجنب إعادة توليد الصور المتطابقة.

import hashlib

def prompt_cache_key(prompt, width, height, seed):
    raw = f'{prompt}|{width}x{height}|{seed}'
    return hashlib.sha256(raw.encode()).hexdigest()

سلامة Prompt

إذا كان تطبيقك يعرض prompts للمستخدمين النهائيين، فقم بتطبيق تصفية المحتوى قبل الإرسال إلى API. لدى Arteza سياسات محتوى - prompts التي تنتهكها ستُرجع أخطاء، مما يهدر الأرصدة وينشئ فشل يواجه المستخدم.

التسعير لاستخدام API

يسحب استخدام API من رصيد حسابك بنفس السعر كما هو الحال مع الاستخدام على الويب.

تأتي الأرصدة من نفس مستويات التسعير بغض النظر عما إذا كنت تستخدمها عبر الويب أو API:

• Starter: 5 دولار = 60 رصيد شهريًا = 60 صورة
• Creator: 25 دولار = 300 رصيد شهريًا = 300 صورة
• Pro: 50 دولار = 700 رصيد شهريًا = 700 صورة
• Studio: 120 دولار = 1,800 رصيد شهريًا = 1,800 صورة

يمكن لعملاء الحجم الأعلى الاتصال بالدعم حول تسعير الحجم للاستخدام المستمر فوق 100,000 صورة/شهر.

الجمع مع نماذج Arteza الأخرى

يمكن لتطبيقك استخدام نماذج Seedance متعددة من خلال نفس API بتغيير معامل model:

• seedream-v4-5 - 1 رصيد - جودة رائدة
• seedream-v3 - 1 رصيد - أسرع، أبسط
• seedream-5-lite - 1 رصيد - وضع التفكير العميق
• seedream-5-edit - 1 رصيد - تحرير الصور
• seedance-2 - توليد الفيديو (نقطة نهاية مختلفة)

بالنسبة للتطبيقات التي تحتاج إلى قدرات التحرير بالإضافة إلى التوليد، يتعامل seedream-5-edit مع تحرير الصور القائم على النص. انظر إلى توثيق Seedream 5 Edit للحصول على التفاصيل.

اعتبارات الأمان

لا تعرّض مفاتيح API على جانب العميل. قم دائمًا بتوجيه استدعاءات API من خلال خادمك الخلفي. يمكن استخدام المفاتيح المكشوفة لاستنزاف رصيد الأرصدة الخاص بك.

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

سجل الطلبات للتصحيح. أدرج معرّفات الطلب في السجلات حتى تتمكن من ربط الأخطاء باستجابات API.

تطبيق حصص الاستخدام لكل مستخدم. إذا كان تطبيقك يقدم توليد الذكاء الاصطناعي كميزة، فحدد الاستهلاك لكل مستخدم لمنع الإساءة.

الأسئلة الشائعة

هل هناك طبقة مجانية لـ API؟ تعمل أرصدة التسجيل المجانية 10 على استدعاءات API. هذا هو 10 توليد Seedream v4.5 مجاني لاختبار التكامل قبل الدفع.

ما هو وقت الاستجابة النموذجي؟ 5-15 ثانية لـ Seedream v4.5 حسب الدقة والحمل الحالي.

هل يمكنني استخدام API للمنتجات التجارية؟ نعم. الاستخدام التجاري مشمول. الصور المولدة من قبل عملائك هي لهم لاستخدامها لأي غرض مشروع.

هل هناك Python SDK؟ تطوير SDKs الرسمية قيد التطوير. يعمل REST API الحالي بنظافة مع مكتبات HTTP القياسية في أي لغة.

كيف أتعامل مع أخطاء سياسة المحتوى؟ تطبيق رسائل تواجه المستخدم التي تشرح أن prompt تم رفضه. سجل الخطأ المحدد للتصحيح.

ماذا يحدث إذا انتهت أرصدتي في منتصف الطلب؟ يُرجع API خطأ 402 قبل بدء التوليد. لا تحدث رسوم جزئية أبدًا - إما أن تحصل على الصورة الكاملة أو تحصل على خطأ.

هل يمكنني دفع prompts متعددة في طلب واحد؟ ليس مباشرة. استخدم num_images: 6 للحصول على اختلافات من نفس prompt، أو قم بإجراء استدعاءات API متوازية لـ prompts مختلفة.

---

يوفر Seedream v4.5 API توليد صور بالذكاء الاصطناعي جاهز للإنتاج بتسعير متوقع لكل صورة مع اتفاقيات REST القياسية. بالنسبة لمعظم التكاملات، يمكنك الانتقال من مفتاح API إلى أول جيل عامل في أقل من 10 دقائق. للأسئلة أو تسعير الحجم، تواصل من خلال لوحة تحكم حسابك.

ابدأ التكامل اليوم. احصل على مفتاح واجهة برمجة التطبيقات → | عرض التسعير الكامل → | اقرأ دليل v4.5 →