واجهة برمجة تطبيقات Seedance 2.0

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

أنشئ مفتاح API في لوحة التحكم وأرسله كرمز مميز من نوع Bearer في كل طلب. يظهر المفتاح بالكامل مرة واحدة فقط وقت الإنشاء.

Authorization: Bearer sk_live_xxxxxxxx

أرسل مهمة أولاً. بعد قبول المهمة، اختر طريقة واحدة لتوصيل النتيجة: استقصاء نقطة نهاية المهمة، أو استلام النتيجة النهائية عبر webhook.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

أنشئ مهمة فيديو باستخدام POST /v1/videos/generations. يحتوي نص الطلب على نموذج على مستوى أعلى، و callback_url اختياري، وكائن إدخال يحتوي على إعدادات الموجه والإنشاء.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

يتحكم generation_type في مدخلات الوسائط المقبولة وكيف يفسر النموذج هذه المدخلات.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "1080p"
    }
  }'

أسماء المعلمات، وقيم التعداد، ومسارات نقطة النهاية، والأمثلة هي جزء من عقد واجهة برمجة التطبيقات. تشرح الأوصاف أدناه كيفية تصرف كل حقل.

هذه هي استجابة النجاح من POST /v1/videos/generations. وهذا يعني أنه تم قبول المهمة وتم حجز الأرصدة. استخدم taskId الذي تم إرجاعه لاستقصاء GET /v1/tasks/:id أو لمطابقة رد اتصال إكمال أو فشل.

{
  "taskId": "3f2aK9mR...",
  "credits": 60
}

استخدم GET /v1/tasks/:id لاسترداد حالة المهمة الحالية. لا تستقصِ أكثر من مرة كل 10 ثوانٍ. بالنسبة لأنظمة الإنتاج، يفضل استخدام خطافات الويب (webhooks).

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "refunded",
  "credits": 60,
  "failed_reason": "provider_failed"
}

عندما يكون callback_url موجودًا، يقوم Seedance باستدعاء نقطة النهاية الخاصة بك عند اكتمال المهمة أو فشلها، ويرسل بيانات JSON تصف النتيجة النهائية. إذا أعادت نقطة النهاية الخاصة بك استجابة غير 2xx أو لم تستجب في غضون 15 ثانية، تتم إعادة محاولة التسليم حتى 5 مرات. تستخدم عمليات إعادة المحاولة نفس معرف المهمة، لذا قم بإزالة التكرارات حسب المعرف. قم بإرجاع استجابة 200 بمجرد تسجيل بيانات رد الاتصال بأمان.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 60
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

تُرجع POST /v1/videos/generations و GET /v1/tasks/:id هذا الشكل من الأخطاء عندما يفشل طلب API نفسه، مثل المعلمات غير الصالحة، أو مفتاح API غير الصالح، أو الأرصدة غير الكافية، أو تحديد المعدل، أو عدم العثور على المهمة. تتضمن بعض الأخطاء حقولًا إضافية مثل required، أو available، أو retry_after اعتمادًا على الموقف.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 60,
    "available": 12
  }
}

يتم تطبيق حدود المعدل لكل مفتاح API مع نافذة منزلقة. الإنشاء الافتراضي هو 60 طلبًا في الدقيقة؛ تكون استعلامات الحالة أكثر تساهلاً. تتضمن استجابات HTTP 429 Retry-After.

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