משימות דיבור ותרגום

החליפו את SERVICE שלהלן ב־speech_to_text או ב־translate, ואת JOB_ID ב־UUID שהוחזר. כל הפעולות מחייבות פרטי גישה לחשבון שלכם, כמתואר בסעיף אימות, ומוגבלות לחשבון שהמשימה שייכת לו. אפשר לקרוא משימה מכל אחד משני שרתי ה־API, אך לכל שרת מעטפת תשובה משלו, לכן השתמשו באותו שרת באופן עקבי.

בשרת api.multitel.net, כשלי אימות (401) מוחזרים לפני החלת מעטפת זו ועשויים לכלול גוף תשובה שונה, לכן בדקו את סטטוס ה־HTTP לפני פענוח התשובה.

אימות

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

• HTTP Basic (Authorization: Basic או curl --user). מתקבלים פרטי גישה של חשבון API מסוג סיסמה, של חשבון משנה, או פרטי הכניסה לחשבון שלכם. מומלץ להשתמש בחשבון API ייעודי. שם המשתמש אינו יכול לכלול נקודתיים, ולא שם המשתמש ולא הסיסמה יכולים להיות ריקים.
• טוקן Bearer (Authorization: Bearer YOUR_TOKEN). מתקבל עבור חשבון API מסוג טוקן. חשבונות API מסוג טוקן חייבים לכלול הגבלת IP, והבקשות חייבות להגיע מכתובת מורשית. שני שרתי ה־API מקבלים את כתובות ה־IPv4 וטווחי ה־CIDR שהוגדרו לחשבון. אי אפשר לשלוח טוקן כסיסמת Basic. ודאו שהטוקן פועל בשרת שבו אתם משתמשים.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

אם חשבון API מוגבל לפי כתובת IP, שלחו בקשות מכתובת מורשית. פרטי גישה חסרים או לא תקינים מחזירים 401. בשרת api.multitel.net, פרטי גישה תקינים שאינם מאפשרים להשתמש בשירותים אלה, כגון פרטי חשבון טוקן שנשלחו כ־Basic, מחזירים 403 unsupported_transcription_principal או unsupported_translation_principal. ניסיונות אימות כושלים חוזרים מאותה כתובת בשרת api.multitel.net עלולים לגרום לחסימת הכתובת, לכן תקנו את פרטי הגישה לפני ניסיון חוזר.

תשאול עד להשלמה

שלחו בקשת GET /v3/SERVICE/JOB_ID. מומלץ לתשאל לכל היותר פעם בכל 3 שניות. המעטפת החיצונית מתארת את הבקשה; כדי לקבוע אם העיבוד הסתיים, בדקו את השדה status של המשימה שבתוכה.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

בשרת api.multitel.net, הגדירו את HOST כ־https://api.multitel.net וקראו את .response.id במקום את .data.id.

ניסיון חוזר בטוח לבקשות שתוצאתן אינה ודאית

אם שליחה חורגת מזמן ההמתנה או מחזירה 429 או סטטוס 5xx, שלחו שוב את אותם נתוני קלט עם אותו מפתח אידמפוטנטיות. תשובה מכל אחד מהשרתים עלולה ללכת לאיבוד או להיות מוחלפת בשגיאה לאחר שהמשימה התקבלה; שליחה חוזרת עם אותו מפתח מחזירה את המשימה אם היא קיימת. שימוש חוזר במפתח עם קלט שונה מחזיר 409 idempotency_conflict. שגיאות מסוימות חוזרות בכל ניסיון, כגון 503 כאשר שירות בתשלום מושבת או 500 עבור קובץ שמע שאי אפשר לקרוא, לכן הפסיקו לאחר כמה ניסיונות.

לשינוי המפתח יש השפעה שונה בכל שירות.

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

שחרור תוצאה לאחר הוספת כסף

עבור משימה בסטטוס awaiting_payment, הוסיפו כסף כך שהיתרה תהיה לפחות בגובה ערך ה־costUsd של המשימה, מעוגל כלפי מעלה למדרגת ה־$0.00001 הבאה, ואז שלחו POST /v3/SERVICE/JOB_ID/settle. החיובים מתבצעים במדרגות שלמות של $0.00001 וכוללים כל שארית שהועברה ממשימות קודמות באותו שירות, לכן הסכום שנגבה עשוי לעלות על costUsd בהפרש קטן מ־$0.00001. בשרת api.multi.tel, שלחו JSON {} או גוף ריק; כל מאפיין בגוף נדחה עם 400. השרת api.multitel.net מתעלם מהגוף. הסדרת התשלום משחררת את התוצאה השמורה בלי להריץ שוב תמלול או תרגום. התשובה כוללת את המשימה; ודאו שהסטטוס שלה הוא completed. אם היתרה עדיין אינה מספיקה, המשימה נשארת בסטטוס awaiting_payment והתשובה עדיין מחזירה HTTP 200.

בהמרת דיבור לטקסט, בקשת הסדרת תשלום למשימה שכבר הושלמה מחזירה אותה עם duplicate: true, ואילו בקשת הסדרת תשלום למשימה שנמצאת בתור, בעיבוד או נכשלה מחזירה 409 transcription_not_awaiting_payment. בתרגום, בקשת הסדרת תשלום למשימה בכל סטטוס אחר מחזירה את המשימה ללא שינוי. הסדרת תשלום זמינה רק כאשר העיבוד בתשלום מופעל (אחרת 503). משימות הממתינות לתשלום נחשבות לעלות שמורה, לכן בחשבונות בתשלום מראש הן עלולות לחסום שליחת משימות חדשות בתשלום עם 402 עד להסדרת התשלום עליהן.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

בדיקת שימוש

השתמשו ב־GET /v3/SERVICE/usage. הפרמטרים האופציונליים from ו־to הם תאריכים לפי UTC בפורמט YYYY-MM-DD, ושני תאריכי הקצה נכללים. אם הם אינם מצוינים, from הוא כברירת מחדל התאריך שחל 30 ימים לפני היום, ו־to הוא התאריך של היום (UTC). התאריך to אינו יכול להיות מוקדם מ־from, והמרחק בין התאריכים יכול להיות לכל היותר 366 ימים (עד 367 תאריכים). תאריכים לא תקינים בלוח השנה, טווח הפוך או טווח ארוך יותר מחזירים 400, וכך גם פרמטרי שאילתה אחרים בשרת api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

התשובה כוללת mode, currency (USD), from, to ו־days, רשימה המסודרת מהחדש לישן.

• רשומות המרת דיבור לטקסט מקובצות לפי תאריך ומקור. הן כוללות date, source (api או hpbx עבור הקלטות Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd ו־debitedUsd.
• רשומות תרגום מקובצות לפי תאריך, מקור ומנוע. הן כוללות date, source, engine, jobs, sourceCharacters, accruedUsd ו־debitedUsd.

accruedUsd מציין את העלות המדויקת בתשע ספרות אחרי הנקודה העשרונית, ו־debitedUsd הוא הסכום שנגבה בחמש ספרות אחרי הנקודה. השימוש נרשם בתאריך ה־UTC שבו הוסדר החיוב על כל משימה, לכן משימות בתור, בעיבוד, שנכשלו או שממתינות לתשלום אינן מופיעות.

מגבלות

בכל חשבון יכולות להיות לכל היותר 50 משימות המרת דיבור לטקסט ותרגום פתוחות יחד: בתור, בעיבוד או בהמתנה לתשלום, כולל משימות הקלטה של Hosted PBX. כאשר מגיעים למגבלה זו או לקיבולת הכוללת של השירות, בקשות להגשת משימות מחזירות 429 transcription_queue_full או translation_queue_full. api.multi.tel מגביל גם כל כתובת IP של לקוח ל־300 בקשות בדקה, בסך הכול לכל הבקשות לאותו שרת. מגבלה זו מחזירה 429 עם כותרות הגבלת קצב וגוף טקסט רגיל במקום מעטפת שגיאה ב־JSON.

טיפול בשגיאות בקשה

בשרת הראשי, כשלים מחזירים סטטוס שגיאת HTTP ו־JSON עם status: "error", code, message ו־requestId. כל תשובה כוללת גם כותרת X-Request-ID. אפשר לספק ערך משלכם; ערכים שאורכם מעל 128 תווים נחתכים. שרת התאימות מחזיר רק את קוד השגיאה בשדה response.code. רשמו ביומן את מזהה הבקשה, אם הוא זמין, ואת קוד השגיאה, ואל תרשמו שמע, טקסט או פרטי גישה ביומנים.

סטטוסים נפוצים:

פעלו לפי קוד השגיאה שהוחזר, ולא מתוך הנחה שלכל כשל בבדיקת תקינות יש אותו סטטוס.

עבור 429 או 503, המתינו ונסו שוב עם השהיה הולכת וגדלה ועם אותו מפתח שליחה; כבדו את Retry-After אם הכותרת קיימת. עבור קלט או פרטי גישה לא תקינים, תקנו תחילה את הסיבה. אל תשלחו שוב ושוב מפתחות חדשים כל עוד משימות קודמות עדיין נמצאות בתור.