איך להשתמש ב-Seedance API: מפתח, בקשה, תשאול וייחוסים
מדריך Seedance API צעד אחר צעד: יוצרים מפתח, שולחים משימת וידאו, מתשאלים אותה עד לכתובת הווידאו, מוסיפים ייחוסים של תמונה, וידאו ואודיו ומעבירים לסוכן.
קריאה כ-Markdownכדי להשתמש ב-Seedance API, צור מפתח API, שלח לנקודת קצה אחת את גוף משימת הווידאו הרשמי של ModelArk, ותשאל את המשימה שמוחזרת עד שכתובת הווידאו מוכנה. אותם צעדים עובדים עבור Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini ו-Seedance 2.5; רק הערך של model וכמה מגבלות ייחודיות לכל מודל משתנים.
המדריך הזה עובר על כל שלב עם קוד עובד, ואז מראה איך להוסיף ייחוסים, לערוך קליפ עם Seedance 2.5 ולהעביר את העבודה לסוכן קוד.
מה צריך לפני הבקשה הראשונה?
- מפתח API. צור אחד בעמוד מפתחות API ושמור אותו בשרת שלך. לעולם אל תכניס אותו לקוד שרץ בדפדפן.
- קרדיטים. הוסף יתרה בעמוד החיוב. הקרדיטים לא פגים לעולם, ומשימות שנכשלו אינן מחויבות.
- מזהה מודל. בחר אחד מהטבלה שלמטה.
| מזהה מודל | מודל | רזולוציות | אורך קליפ |
|---|---|---|---|
dreamina-seedance-2-0 | Seedance 2.0 | 480p עד 4K | 4–15 שניות |
dreamina-seedance-2-0-fast | Seedance 2.0 Fast | 480p, 720p | 4–15 שניות |
dreamina-seedance-2-0-mini | Seedance 2.0 Mini | 480p, 720p | 4–15 שניות |
dreamina-seedance-2-5 | Seedance 2.5 | 480p עד 1080p | 4–30 שניות |
לא בטוח באיזה לבחור? המדריך Seedance 2.0 מול Fast מול Mini והמדריך Seedance 2.5 מול 2.0 משווים ביניהם.
export SEEDROUTER_API_KEY="your-key"איך שולחים בקשה ל-Seedance?
שלח את המשימה ב-POST ל-/v1/contents/generations/tasks. הגוף הוא הבקשה הרשמית של ModelArk ליצירת משימת וידאו ("create a video generation task"):
curl https://api.seedrouter.ai/v1/contents/generations/tasks \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}'התגובה היא מזהה משימה, לא וידאו:
{"id": "task_..."}אם אתה כבר קורא ל-ModelArk, שנה רק את כתובת הבסיס ל-https://api.seedrouter.ai/v1 ואת מפתח ה-API. שדות לא מוכרים נדחים לפני שמשהו מחויב, וכך גם הגדרה שמודל אינו תומך בה, כמו 1080p ב-Fast או ב-Mini.
איך מקבלים את הווידאו?
תשאל את המשימה כל 10 עד 20 שניות עד ש-status יהיה succeeded, failed או expired. קליפ של 5 שניות ב-720p לוקח בדרך כלל שתיים עד שלוש דקות. ב-Python:
import os
import time
import requests
API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
response = requests.post(
f"{API}/contents/generations/tasks",
headers=headers,
json={
"model": "dreamina-seedance-2-0",
"content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
},
timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
result.raise_for_status()
task = result.json()
if task["status"] == "succeeded":
print(task["content"]["video_url"])
break
if task["status"] in ("failed", "expired"):
raise RuntimeError(task["error"]["message"])
time.sleep(15)
else:
raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")במשימה שהצליחה, הווידאו נמצא ב-content.video_url, טוקני הווידאו שמחויבים נמצאים ב-usage.completion_tokens, ולצידם ההגדרות שרונדרו בפועל, כולל ה-seed שהמודל בחר. הווידאו מאוחסן באחסון שלנו; הורד אותו לאחסון שלך אם אתה צריך אותו לטווח ארוך.
פקיעת זמן בזמן התשאול אינה אומרת שהווידאו נכשל. שמור את מזהה המשימה ובדוק אותה שוב; שליחת משימה חדשה פירושה תשלום על וידאו שני. אין כתובת callback, כך שתשאול הוא הדרך לקבל את התוצאה, ואי אפשר לבטל משימה שכבר נשלחה.
איך מוסיפים תמונות, סרטונים ואודיו?
הוסף פריטים ל-content, כל אחד עם כתובת URL ציבורית ו-role:
curl https://api.seedrouter.ai/v1/contents/generations/tasks \
-H "Authorization: Bearer $SEEDROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "dreamina-seedance-2-0",
"content": [
{"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
],
"ratio": "adaptive",
"duration": 8
}'| מצב | מה נכנס ל-content |
|---|---|
| טקסט לווידאו | פריט טקסט אחד |
| פריים ראשון | טקסט ועוד תמונה אחת עם role first_frame |
| פריים ראשון ואחרון | טקסט ועוד תמונת first_frame אחת ותמונת last_frame אחת |
| ייחוסים | טקסט ועוד כל שילוב של reference_image, reference_video ו-reference_audio |
Seedance 2.0 וגרסאות ה-Fast וה-Mini שלו מקבלים עד 9 תמונות ייחוס, 3 סרטונים ו-3 רצועות אודיו; Seedance 2.5 מקבל עד 30, 10 ו-10. המדיה חייבת להיות כתובות URL: Base64 והעלאת קבצים אינם מתקבלים. המודל אינו תומך בתמונות ובסרטוני ייחוס עם פנים אנושיות אמיתיות. המדיה נבדקת כשהמשימה מתחילה, וקובץ שחורג ממגבלה מכשיל את המשימה לפני כל יצירה, בלי חיוב.
איך עורכים או מאריכים קליפ עם Seedance 2.5?
שלח את הקליפ כ-reference_video והגדר את omni_reference_task_type:
{
"model": "dreamina-seedance-2-5",
"content": [
{"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
{"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
],
"omni_reference_task_type": "edit"
}השתמש ב-edit כדי לשנות את מה שיש בצילום וב-extend כדי להמשיך אותו אחרי הפריים האחרון. ב-edit, השאר את duration בברירת המחדל -1; בשניהם, השאר את ratio כ-adaptive. שניות הקלט מחויבות בתעריף הייחוס, כפי שמדריך המחירים מסביר.
איך נותנים לסוכן קוד להשתמש ב-Seedance API?
סוכן קוד כמו Claude Code, Codex או Cursor יכול לקרוא ל-API בפקודת shell או בסקריפט קצר. SeedRouter לא מספקת שרת MCP, skill ארוז או node של ComfyUI; הפרומפט הזה הוא כל האינטגרציה. ייצא קודם את המפתח, ואז הדבק:
Use the SeedRouter API to generate a Seedance video for me.
Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.
Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k] Ratio: [16:9 | 9:16 | 1:1 | adaptive] Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]
Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
"content": [{"type": "text", "text": "..."}],
"resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.
Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.שלב האישור חשוב: הסוכן מוציא את היתרה שלך, ולכן הוא לעולם לא אמור לשלוח משימה על דעת עצמו.
שאלות נפוצות
איך משיגים מפתח ל-Seedance API?
התחבר, פתח את עמוד מפתחות API וצור מפתח. אותו מפתח עובד עם כל מודלי Seedance ועם שאר המודלים ב-SeedRouter.
איפה נמצא התיעוד של Seedance API?
מסמכי ה-API של Seedance 2.0 ושל Seedance 2.5 מפרטים כל שדה, מגבלה ושגיאה, עם דוגמאות ב-cURL, Python, Node.js ו-Go, וגם קובץ OpenAPI וגרסת Markdown להעתקה.
אפשר ליצור כמה סרטונים בבת אחת?
שלח משימה אחת לכל וידאו ותשאל את המשימות במקביל. כל משימה מחזירה וידאו אחד ומחויבת בנפרד. כדי לקבל רשימה של משימות אחרונות, קרא ל-GET /v1/contents/generations/tasks עם page_num, page_size ומסננים כמו filter.status.
אילו שגיאות צריך לטפל בהן?
400 פירושו שהגוף הפר כלל, למשל שדה לא מוכר או רזולוציה שאינה נתמכת, ושום דבר לא מחויב. משימה שמסתיימת ב-failed או ב-expired מכילה קוד שגיאה והודעה, וגם היא אינה מחויבת. המדריך לשגיאות מפרט כל קוד ומתי לנסות שוב.
שלח את הבקשה הראשונה שלך
צור מפתח, הוסף יתרה קטנה והרץ את דוגמת ה-Python שלמעלה, או נסה את אותה בקשה בלי קוד ב-Playground של Seedance 2.0. לקליפים ארוכים יותר ולעריכה, שנה את המודל ל-dreamina-seedance-2-5 וראה את העמוד של Seedance 2.5.



