Seedance 1.0 Pro API: نقطة نهاية احترافية لتوليد الفيديو

إذا كنت تدمج الفيديو في منتج أو سير عمل أو خط إنتاج، فإن واجهة الويب ستصبح عائقاً في نهاية المطاف. واجهة برمجة التطبيقات (API) الخاصة بـ Seedance 1.0 Pro هي النموذج ذاته الذي يعمل خلف واجهة المستخدم، مكشوفاً كنقطة نهاية REST نظيفة مع مصادقة بالرمز المميز، وتسعير متوقع بالثانية، واستطلاع مهام مباشر. يغطي هذا الدليل كل ما تحتاجه لإطلاقه في بيئة الإنتاج.

ملخص سريع

• REST API لتوليد فيديو أصلي بدقة 1080p باستخدام Seedance 1.0 Pro
• المصادقة: رمز مميز من لوحة تحكم الحساب
• الفوترة: بالثانية بحوالي $0.12 في الثانية، مقرّبة للأعلى إلى أرصدة كاملة
• النمط: إرسال المهمة ← استطلاع الحالة ← تنزيل MP4
• الأنسب لـ: تكاملات SaaS، وخطوط الإنتاج الدُفعية، والأتمتة، والمنتجات ذات العلامة البيضاء

ما الذي توفره الواجهة البرمجية

كل ما تقدمه واجهة الويب الخاصة بـ Seedance 1.0 Pro، متاح برمجياً:

• توليد فيديو من صورة باستخدام رابط الصورة المصدر
• موجّه الحركة لتوجيه الرسوم المتحركة
• التحكم في المدة من 2 إلى 12 ثانية
• التحكم في الإطار الأخير للانتقالات الموجّهة
• تثبيت الكاميرا كخيار قابل للتفعيل
• استطلاع المهام للحالة ورابط النتيجة
• مخرجات MP4 بدقة أصلية 1080p

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

المصادقة

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

Authorization: Bearer YOUR_API_KEY

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

• لا تُدرج مفاتيح الواجهة البرمجية في نظام التحكم بالمصدر أبداً
• دوّر المفاتيح بانتظام
• استخدم متغيرات البيئة أو مدير الأسرار
• قيّد المفاتيح بمصادر محددة إن أمكن

نقاط النهاية الأساسية

إرسال مهمة توليد

POST /v1/seedance-1-pro/generate

جسم الطلب:

{
  "source_image_url": "https://your-cdn.com/source.jpg",
  "prompt": "Slow camera push-in on the subject, warm golden hour light, shallow depth of field",
  "duration_seconds": 6,
  "camera_lock": false,
  "end_frame_url": null
}

المعاملات:

الاستجابة:

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "created_at": "2026-04-10T12:00:00Z",
  "estimated_seconds": 90
}

التحقق من حالة المهمة

GET /v1/seedance-1-pro/status/{job_id}

الاستجابة (قيد التنفيذ):

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "progress": 0.45,
  "created_at": "2026-04-10T12:00:00Z"
}

الاستجابة (مكتملة):

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "video_url": "https://arteza.ai/videos/abc123xyz.mp4",
  "duration_seconds": 6,
  "resolution": "1920x1080",
  "credits_charged": 144
}

قيم الحالة المحتملة: queued، processing، completed، failed

تنزيل النتيجة

بمجرد أن تصبح الحالة completed، يشير video_url إلى ملف MP4 بدقة 1080p. نزّله فوراً واحفظه في بنيتك التحتية الخاصة، ولا تعتمد على صلاحية الرابط إلى أجل غير مسمى.

مثال كامل بلغة Python

import os
import time
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1/seedance-1-pro"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def generate_video(source_image_url, prompt, duration=6, camera_lock=False, end_frame=None):
    payload = {
        "source_image_url": source_image_url,
        "prompt": prompt,
        "duration_seconds": duration,
        "camera_lock": camera_lock,
    }
    if end_frame:
        payload["end_frame_url"] = end_frame
    
    response = requests.post(f"{BASE_URL}/generate", headers=HEADERS, json=payload)
    response.raise_for_status()
    return response.json()["job_id"]

def wait_for_completion(job_id, poll_interval=5, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        r = requests.get(f"{BASE_URL}/status/{job_id}", headers=HEADERS)
        r.raise_for_status()
        data = r.json()
        
        if data["status"] == "completed":
            return data["video_url"]
        if data["status"] == "failed":
            raise RuntimeError(f"Job failed: {data.get('error', 'unknown')}")
        
        time.sleep(poll_interval)
    
    raise TimeoutError(f"Job {job_id} did not complete within {timeout}s")

def download_video(url, output_path):
    response = requests.get(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)

# استخدامه
job_id = generate_video(
    source_image_url="https://example.com/product.jpg",
    prompt="Slow camera orbit around the product, studio lighting, 6 seconds",
    duration=6,
    camera_lock=True
)

video_url = wait_for_completion(job_id)
download_video(video_url, "output.mp4")
print(f"Video saved to output.mp4")

مثال كامل بلغة Node.js

import fs from 'fs';
import fetch from 'node-fetch';

const API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = 'https://api.arteza.ai/v1/seedance-1-pro';
const HEADERS = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function generateVideo(opts) {
  const response = await fetch(`${BASE_URL}/generate`, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify(opts)
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  return data.job_id;
}

async function waitForCompletion(jobId, { pollInterval = 5000, timeout = 300000 } = {}) {
  const start = Date.now();
  while (Date.now() - start < timeout) {
    const r = await fetch(`${BASE_URL}/status/${jobId}`, { headers: HEADERS });
    const data = await r.json();
    if (data.status === 'completed') return data.video_url;
    if (data.status === 'failed') throw new Error(`Job failed: ${data.error}`);
    await new Promise(res => setTimeout(res, pollInterval));
  }
  throw new Error('Timeout');
}

async function downloadVideo(url, path) {
  const response = await fetch(url);
  const buffer = await response.buffer();
  fs.writeFileSync(path, buffer);
}

// استخدامه
const jobId = await generateVideo({
  source_image_url: 'https://example.com/product.jpg',
  prompt: 'Slow camera orbit around the product, studio lighting, 6 seconds',
  duration_seconds: 6,
  camera_lock: true
});

const videoUrl = await waitForCompletion(jobId);
await downloadVideo(videoUrl, 'output.mp4');
console.log('Saved output.mp4');

هل تريد جودة بث كهذه؟ جرّب Seedance 1.0 Pro مجاناً →

التسعير والفوترة

السعر: حوالي $0.12 لكل ثانية من الفيديو الناتج، مقرّبة للأعلى إلى أقرب رصيد كامل

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

الخطط هي نفسها المتاحة في واجهة الويب: $5 للمبتدئين، و$25 للمبدعين، و$50 للمحترفين، و$120 للاستوديو. راجع صفحة الأسعار.

حدود المعدل والتزامن

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

إرشادات عامة:

• 5-10 مهام متزامنة موثوقة لمعظم الحسابات
• التراجع الأسي عند استجابات HTTP 429
• إعادة المحاولة على مستوى المهمة عند الأعطال العابرة (حتى 3 محاولات)
• استدعاءات Webhook متاحة لتجنب الاستطلاع المفرط

Webhooks (اختياري)

بدلاً من الاستطلاع، سجّل رابط webhook في إعدادات حسابك أو لكل طلب على حدة. عند اكتمال مهمة، ترسل Arteza طلب POST إلى رابطك:

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "video_url": "https://arteza.ai/videos/abc123xyz.mp4",
  "duration_seconds": 6,
  "credits_charged": 144,
  "timestamp": "2026-04-10T12:02:15Z"
}

يتم توقيع Webhooks بتوقيع HMAC في رأس X-Seedance-Signature. تحقق منه قبل الوثوق بالبيانات.

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

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

تتضمن أجسام استجابة الأخطاء حقل error برسالة قابلة للقراءة البشرية، وحقل code للمعالجة البرمجية.

{
  "error": "Source image URL could not be fetched",
  "code": "source_image_unreachable"
}

متطلبات صورة الإدخال

• الصيغ: PNG، JPEG، WebP
• الحجم: حتى 10 ميغابايت لكل صورة
• الدقة: 512x512 كحد أدنى، والأعلى أفضل (يُوصى بـ 1080p فأكثر)
• إمكانية الوصول إلى الرابط: يجب أن يكون متاحاً للعموم من خوادم Arteza (لا localhost، ولا روابط محمية بمصادقة)

للصور الخاصة، ارفعها إلى رابط S3 موقّع أو CloudFront أو ما شابه، ومرّر الرابط الموقّع في الطلب.

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

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

الاختبار والبيئة التجريبية

ابدأ كل تكامل بخطة المبتدئين بـ $5 (60 رصيداً شهرياً). هذا يكفي لعشرين عملية توليد اختبارية مدتها ثانيتان. ابنِ تكاملك واختبره من البداية إلى النهاية قبل الالتزام بخطة ذات حجم أعلى.

حالات الاستخدام

• منصات SaaS: امنح مستخدميك إمكانية توليد فيديو من أصولهم الخاصة
• التجارة الإلكترونية: أنشئ فيديوهات حركية للمنتجات من صور الكتالوج
• العقارات: أتمت إنتاج فيديوهات قوائم العقارات من الصور
• أتمتة التسويق: فيديو مخصص على نطاق واسع
• منصات المحتوى: أثرِ المقالات والقوائم أو منشورات التواصل الاجتماعي بفيديو مولّد
• أدوات الفيديو ذات العلامة البيضاء: ابنِ منتج فيديو بالذكاء الاصطناعي الخاص بك على خلفية Arteza

قراءات ذات صلة

• سير عمل المعالجة الدفعية
• الدليل الشامل لـ Seedance 1.0 Pro
• Seedance 1.0 Pro للوكالات
• دليل واجهة برمجة التطبيقات لـ Seedance 2.0

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

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

ماذا يحدث إذا فشل التوليد؟ لا تُخصم أي أرصدة عند فشل عمليات التوليد.

كم تدوم استضافة الفيديوهات المولّدة؟ تتوفر الفيديوهات للتنزيل خلال نافذة زمنية بعد التوليد. نزّلها واحفظها فوراً.

هل تدعمون مكتبات SDK؟ تتوفر مكتبات SDK مجتمعية لـ Python وNode. راجع وثائق المطورين على arteza.ai.

هل يمكنني إلغاء مهمة قيد التنفيذ؟ نعم، أرسل DELETE /v1/seedance-1-pro/jobs/{job_id}. لا تُخصم أرصدة على المهام الملغاة.

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

---

واجهة Seedance 1.0 Pro البرمجية هي المسار الجاهز للإنتاج لدمج توليد فيديو بالذكاء الاصطناعي بدقة 1080p في منتجك أو خط إنتاجك.

احصل على مفتاح API وابدأ البناء → مع 10 أرصدة مجانية عند التسجيل.