Seedance API

ה-API מאפשר לכם להגיש משימות יצירת וידאו עבור Seedance 2.5 ו-Seedance 2.0 באופן פרוגרמטי. Seedance 2.5 הוא המודל המומלץ והוא תומך בטקסט לווידאו, תמונה לווידאו (על בסיס הפריים הראשון או הפריים הראשון והאחרון), ומולטימודל (יצירת וידאו על בסיס קבצי מקור). תהליך היצירה הוא אסינכרוני: יוצרים משימה, מקבלים מזהה משימה (task ID) באופן מיידי, ואז מקבלים את הסרטון המוכן על ידי פולינג (תשאול) של נקודת הקצה של המשימה או באמצעות קבלת וובחוק.

צרו מפתח API בלוח הבקרה ושלחו אותו כטוקן Bearer בכל בקשה. המפתח המלא יוצג פעם אחת בלבד בעת יצירתו.

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 המכיל את הנחיית הטקסט (prompt) ואת הגדרות היצירה.

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, נתיבי נקודות הקצה והדוגמאות הם חלק מחוזה ה-API. התיאורים להלן מסבירים את ההתנהגות של כל שדה.

זוהי תגובת ההצלחה המתקבלת מ-POST /v1/videos/generations. משמעותה היא שהמשימה התקבלה וקרדיטים נשמרו עבורה. השתמשו ב-taskId שהתקבל כדי לבצע פולינג ל-GET /v1/tasks/:id או כדי להתאים לקריאה החוזרת (callback) של סיום או כישלון המשימה.

{
  "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), לכן יש לבצע מניעת כפילויות (de-duplication) לפי מזהה זה. החזירו תגובת 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 יחזירו שגיאה במבנה זה כאשר בקשת ה-API עצמה נכשלת (למשל: פרמטרים שגויים, מפתח API לא תקף, חוסר בקרדיטים, חריגה ממגבלת הקצב או משימה שלא נמצאה). חלק מהשגיאות כוללות שדות נוספים כגון required, available או retry_after בהתאם לנסיבות.

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

מגבלות קצב הבקשות מוחלות לכל מפתח API באמצעות חלון זמן נע (sliding window). יצירת סרטונים מוגבלת כברירת מחדל ל-100 בקשות בדקה; שאילתות סטטוס משימה מאפשרות קצב גמיש יותר. תגובות HTTP 429 כוללות את הכותרת Retry-After.

ה-API עובד בשיטה של שמירת קרדיטים בעת הגשה, חיוב בעת הצלחה, והחזר בעת כישלון. דפי השימוש בלוח הבקרה מציגים את היסטוריית הקרדיטים של ה-API, יומני משימות ונתוני שימוש מבוססי זמן.