Seedance 2.0

יכולות

תמחור וקרדיטים

החיוב על יצירת סרטונים מתבצע בנקודות זכות (credits) בהתאם למשך הזמן לחיוב בשניות. ללא סרטון קלט, המשך לחיוב הוא אורך סרטון הפלט; עם סרטון קלט, החיוב כולל גם את אורך סרטון הייחוס.

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

• ללא קלט וידאו: שניות פלט × תעריף ללא וידאו.
• עם קלט וידאו: (שניות פלט + שניות מדודות של סרטון ההתייחסות) × תעריף עם וידאו. השרת מודד את אורך סרטון ההתייחסות הכולל ומעגל אותו כלפי מעלה לשניות שלמות לפני החיוב.
• התייחסויות המבוססות על תמונה או אודיו בלבד מחושבות לפי תעריף 'ללא וידאו'. תעריף החיוב עבור סרטון התייחסות חל רק במצב reference-to-video כאשר מסופקים סרטוני התייחסות.

הקרדיטים נשמרים בעת שליחת הבקשה ומחויבים רק עם הצלחת המשימה. משימות שנכשלו או שהזמן שלהן קצב (timeout) נכנסות לתהליך זיכוי. סטטוס חיוב של refund_failed פירושו שהזיכוי לא הושלם בהצלחה; יש לבדוק את יומני הרישום (logs) של ה-API או לפנות לתמיכה.

אימות

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

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

הגדירו את משתנה הסביבה SEEVIO_API_KEY לפני הרצת דוגמאות אלו. דוגמאות ה-JavaScript רצות על השרת שלכם באמצעות Node.js; דוגמאות ה-Python משתמשות בחבילת requests.

מדריך מהיר

שלחו בקשה בסיסית זו, שמרו את ה-taskId שמוחזר, והשתמשו בדוגמה לשאילתת משימה המופיעה להלן. ערך הקרדיטים (credits) בתגובת היצירה מייצג את כמות הקרדיטים השמורה עבור המשימה.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

דוגמה לתגובת יצירת משימה

לאחר קבלת הבקשה שלעיל, ה-API מחזיר תגובת JSON זו. הפרמטר taskId הוא מזהה המשימה המשמש לשאילתות סטטוס הבאות; הפרמטר credits מייצג את מספר הקרדיטים השמורים עבור משימה זו. תגובה זו מאשרת את יצירת המשימה, ולא שהסרטון מוכן. עליך לבצע פנייה יזומה (polling) לבדיקת סטטוס המשימה או להשתמש ב-Webhook כדי לקבל את תוצאות הסרטון.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 60
}

יצירת משימה

שלחו אובייקט JSON המכיל את הדגם והקלט, יחד עם callback_url אופציונלי. הקפידו תמיד לציין את מזהה הדגם המוצג בעמוד זה; השמטת השדה תבחר כברירת מחדל ב-seedance-2-0.

גוף הבקשה

פרמטרי קלט

יש לספק את image_urls‏, video_urls ו-audio_urls כמערכים של מחרוזות URL‏ (string[]). כל כתובת URL שתוזן חייבת להיות נגישה לציבור באמצעות פרוטוקול HTTPS, כולל קובצי מדיה שאין בהם שימוש במצב שנבחר.

שדות בוליאניים חייבים לקבל ערך JSON של true או false, ולא כמחרוזות או מספרים.

תגובת יצירה

קוד HTTP 200 מחזיר taskId (מחרוזת) ו-credits (מספר). תגובה זו מאשרת את יצירת המשימה, אך לא את השלמתה. הסכום המוצג להלן תואם למדריך המהיר של 5 שניות ב-720p.

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 60
}

מצבי יצירה ודוגמאות

טקסט לווידאו

יצירה מתוך הנחיית טקסט. כתובות URL של מדיה אינן מועברות במצב זה.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}'

פריים ראשון

ספקו תמונה אחת כפריים הראשון, ותארו את התנועה הרצויה בהנחיית הטקסט.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "aspect_ratio": "adaptive"
  }
}'

פריים ראשון ואחרון

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

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "aspect_ratio": "adaptive",
    "return_last_frame": true
  }
}'

התייחסות רב-מודאלית

שילוב של תמונות, סרטונים וקובצי אודיו להתייחסות. הנחיית הטקסט נשארת שדה חובה. שימוש בסרטון התייחסות משנה את נוסחת החיוב.

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "Follow the reference camera movement and keep the character consistent. Use the audio for ambience.",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "reference-to-video",
    "image_urls": [
      "https://example.com/character.jpg"
    ],
    "video_urls": [
      "https://example.com/camera.mp4"
    ],
    "audio_urls": [
      "https://example.com/ambience.mp3"
    ],
    "aspect_ratio": "adaptive"
  }
}'

שאילתת משימה

החליפו את מזהה הדוגמה ב-taskId שהתקבל בעת היצירה. שאילתות יחזירו רק משימות השייכות למשתמש של מפתח ה-API; מזהים שאינם נגישים או שאינם קיימים יחזירו שגיאת HTTP 404.

כנקודת מוצא, בצעו שאילתה (polling) כל 10–20 שניות, הפחיתו את התדירות במקרה של שגיאת HTTP 429, ועצרו כאשר הסטטוס הופך ל-completed או failed. בסביבת פרודקשן מומלץ להשתמש ב-Webhooks. כל דוגמת קוד להלן מבצעת שאילתה אחת בלבד.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

משימה הושלמה: תגובת שאילתה עם תוצאות הווידאו

כאשר השאילתה מחזירה status=completed, יצירת הווידאו הסתיימה. ניתן לקרוא את כתובות ה-URL של הסרטונים מתוך data.results ולהוריד אותם לפני המועד המצוין ב-data.video_expires_at. הסטטוס billing_status=charged מציין כי הקרדיטים השמורים חויבו.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-0",
  "status": "completed",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

משימה נכשלה: תגובת שאילתה עם פרטי השגיאה והחיוב

כאשר השאילתה מחזירה status=failed, תהליך היצירה הסתיים ללא הצלחה. ניתן לראות את סיבת הכישלון ב-failed_reason ואת סטטוס ההחזר ב-billing_status. בדוגמה זו, refunded מציין שהקרדיטים הוחזרו. השדה credits שומר על הערך המקורי שהוזמן, והתגובה אינה כוללת את השדה data.

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

Webhooks

הגדירו callback_url בבקשת היצירה כדי לקבל בקשת POST מסוג JSON כאשר המשימה מסתיימת או נכשלת. החזירו תגובת 2xx בתוך 15 שניות. שליחות שנכשלו ינוסו שוב; טפלו בקבלת שידורים חוזרים בצורה אידמפוטנטית (idempotent) לפי מזהה המשימה.

קצה הקישור החוזר (callback endpoint) שלך חייב לקבל בקשות POST עם גוף בקשה מסוג JSON (Content-Type: application/json).

יצירת משימה עם קריאה חוזרת (Callback)

curl --fail-with-body https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedance-2-0",
  "input": {
    "prompt": "A cat surfing at sunset, cinematic lighting",
    "duration": 5,
    "resolution": "720p",
    "generation_type": "text-to-video",
    "aspect_ratio": "16:9",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

נתוני ה-Webhook שונים מהתגובות לשאילתות משימה: הם אינם כוללים את billing_status ואת credits; פרטי הכישלון נמצאים בתוך data.failed_reason ו-data.credits_refunded. השדה created_at ב-Webhook מייצג את זמן יצירת האירוע בפורמט Unix timestamp (שניות).

המשימה הושלמה: נתוני ה-payload של ה-callback שהצליח

כאשר היצירה מצליחה, ה-callback יכיל את הסטטוס status=completed. השתמש ב-id כדי לזהות את המשימה וב-data.results כדי לקבל את כתובות ה-URL של הווידאו. יש להוריד ולשמור את התוצאות לפני הזמן המצוין ב-data.video_expires_at.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1788652800,
  "model": "seedance-2-0",
  "status": "completed",
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/videos/example.mp4"
    ],
    "video_expires_at": "2026-09-07T00:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

המשימה נכשלה: נתוני ה-payload של ה-callback שנכשל

כאשר היצירה נכשלת, ה-callback יכיל את הסטטוס status=failed. השתמש ב-id כדי לזהות את המשימה, ב-data.failed_reason כדי לראות את סיבת הכתב וב-data.credits_refunded כדי לראות את כמות הקרדיטים שזוכתה.

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

דוגמה לקוד קליטה (Receiver)

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

  if (callbackData.status === "completed") {
    const videoUrls = callbackData.data.results;
    // Save the video URLs and mark this task as completed in your application.
    console.log(callbackData.id, videoUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData.data;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

דוגמה זו ב-Next.js קוראת את גוף ה-JSON של ה-callback ומטפלת ישירות במשימות שהושלמו או נכשלו. מומלץ להוסיף שמירה בבסיס נתונים ומניעת כפילויות של מזהי משימות (task-ID deduplication) באפליקציה שלך; מומלץ להעביר עבודות איטיות לתור (queue) לפני החזרת אישור על קבלת ה-callback.

מגבלות ודרישות מדיה

• כל כתובות ה-URL של המדיה והקריאות החוזרות חייבות להיות כתובות HTTPS ציבוריות. הימנעו משימוש ב-localhost, כתובות IP פרטיות או קבצים הדורשים עוגיות (cookies) או התחברות. כתובות URL של סרטוני/קובצי אודיו להתייחסות חייבות להוביל ישירות לקובץ המדיה לקריאה.
• במצב reference-to-video, ספקו לפחות קלט התייחסות אחד, ולא יותר מ-9 תמונות, 3 סרטונים, 3 קובצי אודיו ו-12 חומרי מקור סך הכל. אורך הווידאו הכולל ואורך האודיו הכולל של קלטי ההתייחסות חייבים להיות לכל היותר 15 שניות כל אחד.
• מצב text-to-video מתעלם מכל קלטי המדיה. מצב image-to-video מעביר רק את תמונות הפריים הראשון/האחרון ומתעלם מהתייחסויות לווידאו ואודיו. השתמשו ב-reference-to-video כדי לשלב סוגי מדיה שונים.
• עבור דגמי Seedance 2.0, השתמשו באודיו יחד עם תמונה אחת או סרטון אחד לפחות לצורך תאימות עם הדגם. דוגמאות לשימוש באודיו בלבד זמינות בעמוד של Seedance 2.5.

שגיאות

שגיאות HTTP מחזירות אובייקט error המכיל code (קוד) ו-message (הודעה). משימה שהתקבלה בהצלחה עדיין עלולה להיכשל בשלב מאוחר יותר; בצעו שאילתה על המשימה או טפלו בקריאה החוזרת של הכישלון שלה.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

מגבלות קצב בקשות

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

שאילתות משימות: כברירת מחדל, כל מפתח API מאפשר עד 120 בקשות בדקה. בקשות שאילתה ובקשות ליצירת משימות נספרות בנפרד.