אימות
נקודות קצה בבטא פרטית צריכות להשתמש במפתחות Bearer API מעל HTTPS. שמרו מפתחות בצד השרת והחליפו אותם כשחברי צוות או מערכות אוטומציה משתנים.
תיעוד
בנו אוטומציית מדיה על גבי סוויפטול.
מושגי API של סוויפטול לבניית תהליכי מדיה אוטומטיים סביב העלאות, תורים, עיבוד AI, Webhooks ומסירת תוצאות מאובטחת.
יסודות API
מיועד למשימות מדיה ארוכות ואמינות.
מחזור חיי משימה
רוב עבודות המדיה הארוכות הן אסינכרוניות: יוצרים משימה, בודקים סטטוס או מקבלים Webhook, ואז מורידים את חבילת התוצרים המוכנה.
בטיחות מדיה
לתהליכים פרטיים השתמשו בכתובות העלאה והורדה חתומות. אין לחשוף נתיבי אחסון ענן פרטיים ישירות לדפדפנים ציבוריים.
אידמפוטנטיות
שלחו כותרת Idempotency-Key בניסיון חוזר ליצירת משימה, כדי שניסיונות רשת חוזרים לא ייצרו משימות עיבוד כפולות.
תהליך עבודה
מחזור משימה אחד מהעלאה ועד תוצר.
את רוב פעולות סוויפטול אפשר להכניס לתור, לנטר ולמסור באותו דפוס עבודה.
יצירה או העלאה של קובץ המדיה המקורי.
שליחת משימת תמלול, תרגום, הפרדה או המרה.
מעקב אחרי מצבי תור, עיבוד, השלמה וכשל.
הורדת חבילת התוצרים או קבלת Webhook בסיום.
נקודות קצה
נתיבים מרכזיים לאוטומציית מדיה.
POST
/v1/transcribe
יצירת משימת תמלול
יצירת כתוביות SRT, VTT, TXT או JSON מאודיו או וידאו.
בקשה
- file or source_url
- language=auto or ISO language code
- outputs[]=srt|vtt|txt|json
- speaker_hints optional
תגובה
- job_id
- status
- estimated_seconds
- output_formats
הערות
- השתמשו באודיו נקי כשאפשר.
- קבצים ארוכים צריכים לרוץ דרך עובדי ענן.
- בדקו כתוביות שנוצרו לפני פרסום.
POST
/v1/translate
תרגום קובץ כתוביות
תרגום קובצי SRT או VTT ליותר מ-100 שפות תוך שמירה על תזמון.
בקשה
- subtitle_file
- source_language optional
- target_language required
- tone=natural|formal|short
תגובה
- job_id
- status
- source_language
- target_language
הערות
- שפות RTL נתמכות.
- תזמון הכתוביות נשמר.
- מומלץ לבצע בדיקה אנושית לחומרים משפטיים, רפואיים או חינוכיים.
POST
/v1/separate
הפרדת ערוצי קול
פיצול קובץ אודיו לשירה, תופים, בס וערוצים אינסטרומנטליים.
בקשה
- file or source_url
- stems[]=vocals|drums|bass|other
- quality=standard|high
תגובה
- job_id
- status
- stems
- estimated_seconds
הערות
- מצבי איכות גבוהה נמשכים יותר זמן.
- השתמשו ב-WAV לתהליכי פוסט-פרודקשן.
- כבדו זכויות יוצרים ותנאי פלטפורמות.
POST
/v1/convert
המרת מדיה
המרת קובצי וידאו, אודיו וכתוביות לפורמטים מוכנים לפרסום.
בקשה
- file or source_url
- format=mp4|webm|mp3|wav|vtt|srt
- quality preset optional
תגובה
- job_id
- status
- target_format
- download_url when ready
הערות
- מגבלות השרת צריכות להתאים למגבלות ההעלאה של nginx ו-PHP.
- לעיבוד אצווה השתמשו ב-Webhook בסיום.
GET
/v1/jobs/{id}
בדיקת סטטוס משימה
מעקב אחרי משימות בתור, בעיבוד, שנכשלו או שהושלמו.
בקשה
- job id in path
תגובה
- job_id
- status
- progress
- error
- outputs
הערות
- בדקו סטטוס כל 5 עד 15 שניות למשימות פעילות.
- לאוטומציית אצווה העדיפו Webhooks.
POST
/v1/webhooks/test
בדיקת שליחת Webhook
שליחת אירוע דוגמה חתום כדי לוודא שמקבל האוטומציה פועל.
בקשה
- url
- event=job.completed|job.failed
- secret optional
תגובה
- delivered
- http_status
- latency_ms
הערות
- ודאו חתימות בשרת שלכם.
- החזירו 2xx כדי לאשר קבלה.
דוגמאות
קטעי דוגמה לאינטגרציות נפוצות.
יצירת משימת תמלול
bashcurl -X POST https://swifttool.org/api/v1/transcribe \
-H "Authorization: Bearer $SWIFTTOOL_API_KEY" \
-H "Idempotency-Key: job-2026-06-27-001" \
-F "file=@interview.mp4" \
-F "language=auto" \
-F "outputs[]=srt" \
-F "outputs[]=vtt"בדיקת משימה
bashcurl https://swifttool.org/api/v1/jobs/job_123 \
-H "Authorization: Bearer $SWIFTTOOL_API_KEY"מבנה Payload של Webhook
json{
"event": "job.completed",
"job_id": "job_123",
"status": "completed",
"outputs": ["captions.srt", "captions.vtt"],
"completed_at": "2026-06-27T10:00:00Z"
}תגובות
קודי סטטוס שכדאי לטפל בהם באינטגרציה שלכם.
תקין
הבקשה הצליחה והחזירה את המשאב המבוקש.
התקבל
המשימה התקבלה וממתינה בתור העיבוד.
בקשה שגויה
אימות הקלט נכשל, חסרים שדות חובה או שהפורמט אינו נתמך.
לא מורשה
פרטי גישת API חסרים, פגו או אינם תקינים.
Payload גדול מדי
הקובץ שהועלה חורג ממגבלת המסלול או השרת שהוגדרה.
מוגבל קצב
יותר מדי בקשות או יותר מדי משימות מקבילות למסלול הנוכחי.
שגיאת שרת
כשל לא צפוי. נסו שוב עם אותו מפתח אידמפוטנטיות או פנו לתמיכה.
צ׳קליסט השקה
לשימוש יציב ב-API, הגדירו HTTPS, מגבלות העלאה, כתובות חתומות, אימות חתימות Webhook, החלפת מפתחות API וניטור משימות שנכשלו.
צריכים נקודת קצה מסוימת?
השתמשו בטופס התמיכה לבקשות גישת API, תכנון תהליך מותאם, עובדי ענן פרטיים או אינטגרציות לתוכנות עריכה.
פנייה לתמיכה