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

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

أنشئ مفتاح واجهة برمجة التطبيقات من لوحة التحكم وأرسله كرمز حامل (Bearer token) في ترويسة كل طلب. يظهر المفتاح كاملاً مرة واحدة فقط عند إنشائه.

Authorization: Bearer sk_live_xxxxxxxx

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

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

curl https://api.seevio.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 اختياري، وكائن مدخلات (input) يحتوي على الوصف النصي وإعدادات الإنشاء.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

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

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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": "720p"
    }
  }'

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

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

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

استخدم الطلب GET /v1/tasks/:id لجلب الحالة الحالية للمهمة. يرجى ألا يتجاوز معدل الاستعلام الدوري مرة واحدة كل 10 ثوانٍ. بالنسبة لأنظمة التشغيل الفعلي، يفضل استخدام خطافات الويب.

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

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

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

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

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 هيكل الخطأ هذا عندما يفشل طلب واجهة برمجة التطبيقات نفسه، مثل معلمات غير صالحة، أو مفتاح واجهة غير صالح، أو رصيد غير كافٍ، أو تجاوز حدود معدل الطلبات، أو عدم العثور على المهمة. تتضمن بعض الأخطاء حقولاً إضافية مثل required أو available أو retry_after حسب الحالة.

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

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

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