פיתוח עם ה-API של Seevio

בחירת דגם

כל מדריך דגם כולל את הפרמטרים המלאים שלו, תמחור ודוגמאות. תוכלו להשלים את האינטגרציה ישירות מתוך עמוד הדגם הרלוונטי.

אימות

צרו מפתח 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.

מדריך מהיר

דוגמה זו מייצרת סרטון באורך 5 שניות ברזולוציית 720p באמצעות Seedance 2.5. פתחו את מדריך הדגם כדי לראות את כל מצבי היצירה ומגבלות הפרמטרים.

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-5",
  "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": 100
}

שאילתת משימה

החליפו את מזהה הדוגמה ב-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-5",
  "status": "completed",
  "billing_status": "charged",
  "credits": 100,
  "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-5",
  "status": "failed",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Webhooks

עבור אינטגרציות בסביבת פרודקשן, ספקו callback_url בעת יצירת המשימה. כל מדריך דגם כולל את מבנה הנתונים (payload) שיתקבל ב-Webhook ודוגמה לקוד קליטה.

הגדירו 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-5",
  "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-5",
  "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-5",
  "status": "failed",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

דוגמה לקוד קליטה (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.

שגיאות

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

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