واجهة برمجة تطبيقات Seedance 2.0: كيفية إنشاء مقاطع فيديو بالذكاء الاصطناعي برمجياً

أنشئ فيديو سينمائي بالذكاء الاصطناعي بطلب HTTP واحد. واجهة برمجة تطبيقات Seedance 2.0 هي نفس خط أنابيب التوليد الذي تستخدمه منصة الويب، مكشوفة كواجهة REST نظيفة مع مصادقة Bearer ونقاط نهاية للدُفعات وخطافات الويب. إذا كنت تستطيع إرسال طلب POST، فبإمكانك بناء خط أنابيب لتوليد الفيديو.

يغطي هذا الدليل كل ما تحتاجه لدمج Seedance 2.0 في تطبيقاتك الخاصة: المصادقة، ونقاط النهاية، والمعاملات، ومعالجة الأخطاء، ونماذج أكواد جاهزة للإنتاج بلغتي Python وJavaScript.

ملخص سريع: نظرة عامة على الواجهة البرمجية

• عنوان URL الأساسي: https://api.arteza.ai/v1
• المصادقة: رمز Bearer في ترويسة Authorization
• التوليد: غير متزامن - أرسل مهمة، ثم استطلع أو استخدم خطاف الويب للاكتمال
• حدود المعدل: 60 طلبًا في الدقيقة، و5 عمليات توليد متزامنة
• النماذج: Seedance 2.0 و1.0 Pro و1.0 Lite وSeedream v3/v4.5/v5 كلها في واجهة برمجية واحدة
• تكلفة الرصيد: نفس التسعير الديناميكي بالثانية المستخدم في واجهة الويب (19-351 رصيد للإصدار 2.0)

ما تستطيع الواجهة البرمجية فعله فعلًا

كل ما تفعله واجهة الويب، تفعله الواجهة البرمجية أيضًا. تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، واختيار النموذج، والتحكم في المدة، ونسبة العرض إلى الارتفاع، وتبديل الصوت، والوصول إلى كل نموذج على المنصة. نقاط نهاية للدُفعات لتوليد مقاطع متعددة دفعة واحدة. إشعارات خطاف الويب حتى لا تضطر إلى الاستطلاع المستمر. بيانات وصفية مخصصة تُعاد في النتائج لتتبع اختبارات A/B أو متغيرات الحملات.

النماذج المدعومة

جميع النماذج تستخدم نفس واجهة الواجهة البرمجية، مع معرّفات مختلفة فقط.

المصادقة في 30 ثانية

أنشئ مفتاح API من لوحة التحكم تحت الإعدادات > مفاتيح API. أرسله كرمز Bearer:

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

الاستجابة:

{
  "credits": 2750,
  "tier": "popular"
}

قواعد الأمان المهمة:

• لا ترسل مفتاح API أبدًا في كود جانب العميل أو المستودعات العامة
• احفظه في متغيرات البيئة (SEEDANCE_API_KEY)
• جدّد المفاتيح دوريًا من لوحة التحكم
• كل مفتاح يرث رصيد الحساب الأصلي

نقطة نهاية تحويل النص إلى فيديو

هذه هي نقطة النهاية التي ستستخدمها أكثر من غيرها.

POST /v1/generate/text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Aerial shot of a coastal city at sunset, golden light reflecting off glass skyscrapers, cinematic drone footage",
  "duration": 10,
  "aspect_ratio": "16:9",
  "audio": true
}

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

الاستجابة عند النجاح

{
  "task_id": "task_abc123def456",
  "status": "queued",
  "model": "seedance-2.0",
  "credits_charged": 607,
  "estimated_time": 120,
  "created_at": "2026-04-10T14:30:00Z"
}

التوليد غير متزامن. ستحصل على task_id فورًا وتستطلع حالة الاكتمال (أو تستخدم خطافات الويب).

نقطة نهاية تحويل الصورة إلى فيديو

حرّك صورة مصدر باستخدام موجّه حركة.

POST /v1/generate/image-to-video
Content-Type: multipart/form-data

هل تفضّل عدم رفع ملف؟ مرّر image_url بدلًا من ذلك:

{
  "model": "seedance-2.0",
  "image_url": "https://example.com/photo.jpg",
  "prompt": "The woman turns her head slowly and smiles, wind gently blowing her hair",
  "duration": 8,
  "aspect_ratio": "16:9"
}

التحقق من حالة التوليد

استطلع نقطة نهاية المهمة للتحقق من التقدم.

GET /v1/tasks/{task_id}

الاستجابة أثناء المعالجة

{
  "task_id": "task_abc123def456",
  "status": "processing",
  "progress": 65,
  "model": "seedance-2.0",
  "created_at": "2026-04-10T14:30:00Z",
  "estimated_completion": "2026-04-10T14:31:30Z"
}

الاستجابة عند الاكتمال

{
  "task_id": "task_abc123def456",
  "status": "completed",
  "model": "seedance-2.0",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true,
    "file_size": 8542310
  },
  "credits_charged": 607,
  "created_at": "2026-04-10T14:30:00Z",
  "completed_at": "2026-04-10T14:31:28Z"
}

قيم الحالة

روابط الفيديو تنتهي صلاحيتها خلال 24 ساعة. نزّلها واحفظها على بنيتك التحتية الخاصة فورًا.

هل تريد توليد مخرجات كهذه برمجيًا؟ أنت على بُعد 30 ثانية من أول استدعاء API. احصل على مفتاح API مجانًا →

مثال Python جاهز للإنتاج

إليك سكريبت كامل يرسل طلب توليد، ويستطلع حالة الاكتمال، وينزّل النتيجة.

import os
import time
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def generate_video(prompt, duration=8, aspect_ratio="16:9"):
    """Submit a text-to-video task. Returns task_id."""
    response = requests.post(
        f"{BASE_URL}/generate/text-to-video",
        headers=HEADERS,
        json={
            "model": "seedance-2.0",
            "prompt": prompt,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
            "audio": True,
        },
    )
    response.raise_for_status()
    return response.json()["task_id"]


def wait_for_completion(task_id, poll_interval=5, timeout=300):
    """Poll until the task finishes. Returns result dict."""
    elapsed = 0
    while elapsed < timeout:
        response = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["result"]
        if data["status"] == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")

        time.sleep(poll_interval)
        elapsed += poll_interval

    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


def download_video(video_url, output_path):
    """Stream the video to disk."""
    response = requests.get(video_url, stream=True)
    response.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)


if __name__ == "__main__":
    task_id = generate_video(
        prompt="A cat sitting on a windowsill watching rain fall outside, cozy indoor lighting, shallow depth of field",
        duration=10,
    )
    print(f"Task submitted: {task_id}")

    result = wait_for_completion(task_id)
    print(f"Video ready: {result['video_url']}")

    download_video(result["video_url"], "output.mp4")
    print("Downloaded to output.mp4")

مثال JavaScript (Node.js)

نفس سير العمل في Node.js الحديث مع fetch الأصلي.

const API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = "https://api.arteza.ai/v1";

async function generateVideo(prompt, duration = 8, aspectRatio = "16:9") {
  const response = await fetch(`${BASE_URL}/generate/text-to-video`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "seedance-2.0",
      prompt,
      duration,
      aspect_ratio: aspectRatio,
      audio: true,
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  const data = await response.json();
  return data.task_id;
}

async function waitForCompletion(taskId, pollMs = 5000, timeoutMs = 300000) {
  const start = Date.now();

  while (Date.now() - start < timeoutMs) {
    const response = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const data = await response.json();

    if (data.status === "completed") return data.result;
    if (data.status === "failed") {
      throw new Error(`Generation failed: ${data.error}`);
    }

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

  throw new Error(`Task ${taskId} timed out`);
}

// الاستخدام
const taskId = await generateVideo(
  "Timelapse of a flower blooming, macro lens, soft natural lighting",
  12
);
console.log(`Task submitted: ${taskId}`);

const result = await waitForCompletion(taskId);
console.log(`Video ready: ${result.video_url}`);

تحويل الصورة إلى فيديو بلغة Python

عندما تحتاج إلى رفع صورة مصدر، استخدم multipart/form-data:

def generate_from_image(image_path, prompt, model="seedance-2.0", duration=8):
    """Generate video from a local image file."""
    with open(image_path, "rb") as img_file:
        response = requests.post(
            f"{BASE_URL}/generate/image-to-video",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": img_file},
            data={
                "model": model,
                "prompt": prompt,
                "duration": duration,
                "aspect_ratio": "16:9",
                "audio": "true",
            },
        )
    response.raise_for_status()
    return response.json()["task_id"]

معالجة الأخطاء بشكل موثوق

تستخدم الواجهة البرمجية رموز حالة HTTP القياسية مع هياكل أخطاء منظّمة.

شكل استجابة الخطأ

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 8 credits but this generation requires 24 credits.",
    "required_credits": 24,
    "available_credits": 8
  }
}

النمط الموصى به

try:
    task_id = generate_video(prompt)
except requests.exceptions.HTTPError as e:
    status = e.response.status_code
    if status == 402:
        error = e.response.json()["error"]
        print(f"Need {error['required_credits']} credits, have {error['available_credits']}")
        # Redirect the user to /pricing
    elif status == 429:
        retry_after = int(e.response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retry after {retry_after}s.")
    else:
        raise

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

الحدود

خمس ممارسات مهمة في بيئة الإنتاج

1. استخدم خطافات الويب بدلًا من الاستطلاع على نطاق واسع. الاستطلاع يهدر استدعاءات الواجهة البرمجية. خطافات الويب تُطلق مرة واحدة بالضبط.
2. طبّق التراجع الأسي عند استجابات 429. لا تعيد المحاولة فورًا.
3. نزّل روابط الفيديو فورًا. تنتهي صلاحيتها خلال 24 ساعة. احفظها على شبكة توصيل المحتوى الخاصة بك.
4. تحقق من صحة المدخلات من جانب العميل. اكتشف مشاكل طول الموجّه وحجم الملف قبل الوصول إلى الواجهة البرمجية.
5. تحقق من رصيد الاعتمادات قبل مهام الدُفعات. خطأ 402 في منتصف الدُفعة أمر مزعج. استعلم عن /account/credits أولًا.

دمج خطاف الويب

أضف webhook_url في طلب التوليد وستُرسل Arteza طلب POST إليه عند اكتمال المهمة.

{
  "model": "seedance-2.0",
  "prompt": "...",
  "webhook_url": "https://yourapp.com/api/seedance/webhook"
}

حمولة خطاف الويب

{
  "event": "task.completed",
  "task_id": "task_abc123def456",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/task_abc123def456.mp4",
    "duration": 10,
    "resolution": "1280x720",
    "has_audio": true
  },
  "metadata": {
    "campaign_id": "summer-2026",
    "variant": "A"
  },
  "timestamp": "2026-04-10T14:31:28Z"
}

تتضمن طلبات خطاف الويب ترويسة X-Seedance-Signature، وهي توقيع HMAC-SHA256 للجسم موقّع بسرّ خطاف الويب الخاص بك. تحقق دائمًا من التوقيع قبل معالجة الأحداث.

التوليد بالدُفعات

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

POST /v1/generate/batch

{
  "tasks": [
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 1 description...",
      "duration": 8
    },
    {
      "type": "text-to-video",
      "model": "seedance-2.0",
      "prompt": "Scene 2 description...",
      "duration": 10
    },
    {
      "type": "image-to-video",
      "model": "seedance-1.0-pro",
      "image_url": "https://example.com/product.jpg",
      "prompt": "Slow rotation revealing product details",
      "duration": 6
    }
  ],
  "webhook_url": "https://yourapp.com/api/seedance/batch-complete"
}

تُعالَج المهام في الدُفعة بشكل متزامن حتى حد التزامن المسموح به.

أربع حالات استخدام تستحق البناء

1. فيديوهات منتجات التجارة الإلكترونية على نطاق واسع

أتمت تحريك المنتجات لكامل كتالوجك. كرّر على قاعدة بيانات منتجاتك، وأطلق استدعاء تحويل صورة إلى فيديو لكل عنصر، واحفظ عناوين URL الناتجة بجانب سجل المنتج.

products = get_products_from_database()

for product in products:
    task_id = generate_from_image(
        image_path=product["hero_image"],
        prompt=f"Slow 360 rotation of {product['name']}, studio lighting, white background",
        model="seedance-1.0-pro",
        duration=6,
    )
    save_task_mapping(product["id"], task_id)

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

2. خطوط أنابيب وسائل التواصل الاجتماعي الآلية

أدخل الموضوعات الرائجة في مولّدات الموجّهات، وولّد فيديو رأسيًا يوميًا، وادفعه إلى قائمة مراجعة:

for topic in get_trending_topics():
    prompt = build_prompt(topic)
    task_id = generate_video(prompt, duration=6, aspect_ratio="9:16")
    queue_for_review(task_id, topic)

3. اختبار A/B للتسويق

ولّد متغيرات إبداعية متعددة مع تتبع البيانات الوصفية:

variants = [
    "Product hero shot with warm lighting, luxury feel",
    "Product hero shot with bright lighting, energetic feel",
    "Product hero shot with moody lighting, premium feel",
]

for i, variant in enumerate(variants):
    generate_video(
        prompt=variant,
        duration=6,
        metadata={"variant": chr(65 + i), "campaign": "spring-launch"},
    )

يُعاد حقل metadata في حمولة الاكتمال، مما يتيح لك توجيه النتائج تلقائيًا إلى دلو الحملة الصحيح.

4. التطبيقات التفاعلية

ادمج توليد الفيديو مباشرة في تطبيقك الخاص. يكتب المستخدم موجّهًا، تستدعي الواجهة الخلفية الواجهة البرمجية، ويُسلّم خطاف الويب المقطع المكتمل. تستغرق الحلقة بأكملها نحو 90 ثانية.

الخلاصة

واجهة Arteza البرمجية سهلة الدمج وجاهزة للإنتاج. مصادقة بسيطة، ودلالات REST نظيفة، وخطافات ويب للعمل غير المتزامن، ونقاط نهاية للدُفعات على نطاق واسع. إذا سبق لك استخدام Stripe أو أي واجهة REST حديثة، ستشعر بالألفة خلال عشر دقائق.

للاطلاع على التسعير وتحسين الاعتمادات، راجع دليل الأسعار. للحصول على نظرة عامة أشمل على المنتج، اقرأ الدليل الشامل لـ Seedance 2.0.

هل أنت مستعد للبدء في البناء؟ أنشئ حسابك المجاني →

تابع القراءة: الدليل الشامل لـ Seedance 2.0 • دليل الأسعار • Seedance 2.0 مقابل Seedance 1.0 • Seedance 2.0 مقابل Runway Gen-4