סקירה של API
קראו את Speechdash מתוך יישום משלכם, ויצרו מפתחות API המאשרים זאת.
הספרייה של API של Speechdash מאפשרת ליישום שלכם ליצור מסמכים וליצור דיבור באמצעות אותן קולות כמו באפליקציה. כל מה שאתם מייצרים דרך API גם מופיע בספרייתכם. תסריטים של אודיו וסרטונים מוגמרים שנוצרו באפליקציה מופיעים גם הם כמסמכים בספרייה (source הוא transcription, עם transcript_id). אין משאב REST /transcripts: השתמשו בנקודות הסיום של המסמכים. לא ניתן לפתוח משימות תרגום באמצעות API.
URL הבסיס:
https://api.speechdash.com/v1בדיקת בריאות (לא דורש מפתח API): GET https://api.speechdash.com/health
הסכם קריא למכונה פורסם ב-https://api.speechdash.com/v1/openapi.json, כך שתוכלו ליצור לקוח לשפתכם.
נקודות סיום
| שיטה | דרך | מטרה |
|---|---|---|
GET | /health | בריאות השירות (לא תחת /v1) |
GET | /v1/openapi.json | מסמך OpenAPI 3.1 |
GET | /v1/me | חשבון, תוכנית, ומזוודה |
GET | /v1/documents | רשימת מסמכים בספרייה, כולל תסריטים מוגמרים |
POST | /v1/documents | יצירת מסמך טקסט (source=api) |
GET | /v1/documents/{document_id} | קריאה למסמך וטקסטו |
PUT | /v1/documents/{document_id} | עדכון כותרת, טקסט, שפה, is_archived, או visibility |
DELETE | /v1/documents/{document_id} | מחיקת מסמך |
POST | /v1/documents/{document_id}/translate | גרסה מתורגמת חדשה (העלות היא זהה ליצוא MP3) |
GET | /v1/documents/{document_id}/export | הורדת pdf, docx, txt, csv, srt, או vtt |
POST | /v1/audio/speech | סינתזת עד 5,000 תווים (JSON + אודיו) |
POST | /v1/audio/stream | הזרמת WAV, עד 20,000 תווים |
POST | /v1/audio/stream/with-timestamps | SSE עם אודיו לסעיף ולסימנים |
GET | /v1/voices | קטלוג קולות |
GET | /v1/voices/{voice_id} | הגדרות קול יחיד |
דפים אינטראקטיביים של OpenAPI: חשבון, מסמכים, אודיו, קולות.
שרת MCP (לעוזרים AI)
אם אתם משתמשים ב-Cursor, Claude Desktop, או לקוח אחר של MCP, אתם יכולים להוסיף את שרת MCP הרשמי של Speechdash במקום לקרוא ל-HTTP ישירות. הוא חשוף את אותה הספרייה (כולל תסריטים מוגמרים), תרגום, יצוא, קולות, צילום רגע חשבון, וסינתזת דיבור שאינה הזרמתית ככלים מאחורי אותם מפתחות API והטבות כמו מדריך זה. הזרמת דיבור נשארת ב-REST.
ראו את שרת MCP לקבלת רשימת הכלים המלאה וההתקנה (stdio או Streamable HTTP). אתם יכולים גם לקרוא את הספרייה של Agents באתר המרקטינג למסמכים קריאים למכונה המיועדים למערכות AI. משתמשי סוף יכולים להתחיל מ-מפתחות API ומCP באזור העזרה הזה.
יצירת מפתח API
פתחו תקנות → API.
לחצו על מפתח חדש ונתנו לו שם שיאמר איפה הוא יושם, כמו שרת ייצור.
העתקו את המפתח מיד. רק הקדמה שלו נשמרת, כך שהוא מוצג פעם אחת ולא יותר.
מפתח פועל על חשבונכם. שמורו אותו על השרת שלכם, לעולם לא בגלשן, באפליקציה ניידת, או במרפד ציבורי. אם מפתח נלכד, ביטלו אותו מתוך תקנות → API ויצרו אחד חדש.
אתם יכולים לשמור עד 10 מפתחות פעילים, לשנות את שמם בכל עת, ולראות מתי כל מפתח שימש לאחרונה. ביטול מפתח מפסיק את בקשותיו מיד.
אימות בקשה
שלחו את המפתח כטוקן בעל סמכות:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_מפתחכם"בקשות ללא מפתח תקין מענות 401 עם הקוד unauthorized.
GET /me משיב את ID החשבון, דואר האלקטרוני, התוכנית, והסaldo של המזוודה (wallet_cents ו-display_credits), בנוסף למידע מטא על המפתח API שנשמע. השתמשו בו כדי לאמת מפתח לאחר ההתקנה (לדוגמה, ב-Zapier).
POST /documents ו-POST /audio/speech מקבלים כותרת אופציונלית Idempotency-Key. חידוש המפתח עם אותו גוף מחדש משחק את התשובה הראשונה הצלחה במשך 24 שעות, כך שאי-יציבות ברשת לא תיצור מסמך שני או תטען דיבור פעמיים. אם התשובה של דיבור גדולה מדי כדי לשמור, חידוש עם אותו מפתח מענה 409 במקום להחזיר את האודיו מחדש (הבקשה המקורית כבר נטענה). חיבור לקוח ל-/audio/speech מענה 204, מסדיר כל אודיו שנוצר כבר, ומסיר את המפתח כך שחידוש יכול להחזיר את האודיו. נקודות סיום הזרמת אודיו דוחות את הכותרת.
נקודות
סינתזת דיבור משתמשת בנקודות מהמזוודה אותה משתמשים בה באפליקציה: 0.5 נקודות (1 סנט מזוודה) לכל 30 שניות של אודיו שנוצר. כל בקשה מחזיקה באומדן (כולל מרגע קטן) לפני תחילת הסינתזה, ואז מסדירה לאודיו שנוצר בפועל. הולדה לא משומשת מוחזרת; כל בקשה מסודרת מופיעה בתוך תקנות → שימוש בנקודות כ-סינתזת דיבור של API. השדה billed_credits בתגובות API הוא סנטי מזוודה (2 סנטים = נקודה אחת נראית). אם הזרימה נותקת באמצע, הסעיפים שנמסרו כבר נטענו.
אם הסaldo שלכם לא מספיק כדי לכסות את ההולדה, API מענה 402 עם הקוד payment_required לפני יצירת כל דבר.
יצירת מסמכים לא משתמשת בנקודות, אך היא מונה כלפי קפאת המסמכים היומית של התוכנית שלכם (חינם: 3 ביום; Unlimited: ללא קפא יומית) ומשך הזמן של העלאה. יצוא מסמך לא משתמש בנקודות.
חשבון vs השמעה של ענן בתוך האפליקציה
השמעה של ענן בתוך האפליקציה מחזירה את התחזית לסעיף של המסמך: השמעת סעיף שנוצר כבר על השרת עשויה לעלות 0 נקודות נראות. נקודות סיום REST ו-MCP של דיבור תמיד מסינתזות אודיו חדש וטוענות לפי 30 שניות שנוצרו בשיעור זהה כאשר הסינתזה מתרחשת. אין תחזית השמעה על סינתזת API או MCP.
מגבלות
| מגבלה | ערך |
|---|---|
בקשות ל-/documents | 120 לדקה, לחשבון אחד |
בקשות ל-/audio/* | 60 לדקה, לחשבון אחד |
| בקשות דיבור מקבילות | 3 לחשבון אחד |
POST /audio/speech input | 5,000 תווים |
POST /audio/stream input | 20,000 תווים |
| טקסט מסמך | 500,000 תווים |
| מפתחות API פעילים | 10 |
מגבלות הרצף מוחשבות לחשבון אחד ולא למפתח אחד, כך שמפתחות נוספים לא יגדילו את כמות הרצף שלכם. כל תגובה כוללת X-Request-ID, ו-/documents וכן /audio/* גם משיבים X-RateLimit-Limit, X-RateLimit-Remaining, ו-X-RateLimit-Reset. ציטוט X-Request-ID כאשר אתם מתקשרים עם תמיכה.
בקשות דיבור גם כוללות מגבלה של מקביליות: בקשה רביעית במקביל תענה 429 בזמן שלוש בקשות עדיין נמשכות, כך שאינטגרציה אחת לא תוכל לשלוט בסינתזה. חידוש 429 ו-503 לאחר כותרת Retry-After.
לתוכן ארוך יותר מהמגבלות של הדיבור, יצרו מסמך באמצעות POST /v1/documents ויצאו את האודיו מהאפליקציה.
מסמכים: חלק, תרגום, יצוא
מסמכים מסריאליים כוללים visibility ו-share_url (null כאשר פרטי). PUT /v1/documents/{id} מקבל visibility כדי לפרסם דף קריאה בלבד לא רשום ב-/share/document/{id}, ו-is_archived כדי לאחסן או להחזיר. דפים משותפים הם רק טקסט. הם לא משחקים אודיו שטוען.
POST /v1/documents/{id}/translate יוצר גרסה מתורגמת חדשה. הוא טוען את אותה מזוודה של נקודות כמו יצוא MP3 (0.5 נקודות לכל 30 שניות של דיבור מוערך) ומענה 402 כאשר המזוודה קצרה. הוא מענה 503 כאשר תרגום לא מוגדר או לא פעיל.
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt מוריד את הגרסה הנוכחית כקובץ משלוח. הוסף timestamps=1 כדי לכלול זמן סעיפים בפד"ף, DOCX, TXT, ו-CSV. SRT ו-VTT צריכים תרגום או זמן סעיפים מלא. טקסט נשמר text ב-GET /v1/documents/{id} שומר על כותרות זמן תרגום. הסתרתם היא תרגיל בלבד של קריאת האפליקציה.