نظرة عامة على API
استدعاء Speechdash من تطبيقك الخاص، وإنشاء مفاتيح API التي تصرح باستخدامه.
يسمح API Speechdash لتطبيقك الخاص بإنشاء المستندات وتوليد الصوت باستخدام نفس الأصوات الموجودة في التطبيق. يظهر كل ما تخلقه عبر API أيضًا في مكتبةك. يظهر ملفات الصوت والنصوص المرئية المنتهية التي تم إنشاؤها في التطبيق أيضًا كمستندات في المكتبة (source هو transcription مع transcript_id). لا يوجد مورد REST /transcripts؛ استخدم نقاط النهاية للمستندات. لا يبدأ API مهام التحويل الصوتي.
العنوان الأساسي:
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 | توليد الصوت حتى 5000 حرف (JSON + صوت) |
POST | /v1/audio/stream | تدفق WAV، حتى 20,000 حرف |
POST | /v1/audio/stream/with-timestamps | SSE مع صوت لكل جملة ومarkers |
GET | /v1/voices | قتالوج الأصوات |
GET | /v1/voices/{voice_id} | إعداد صوت واحد |
صفحات OpenAPI التفاعلية: الحساب، المستندات، الصوت، الأصوات.
خادم MCP (لمساعدات الذكاء الاصطناعي)
إذا كنت تستخدم Cursor أو Claude Desktop أو أي عميل آخر MCP، يمكنك إضافة خادم Speechdash الرسمي MCP بدلاً من الاتصال بالHTTP مباشرة. إنه يعرض نفس المكتبة (بما في ذلك النصوص المرئية المنتهية)، الترجمة، التصدير، الأصوات، نسخة حساب المستخدم، وتوليد الصوت غير التدفقي كأدوات مدعومة من نفس مفاتيح API والتفويض مثل هذا الدليل. يتدفق الصوت عبر REST.
انظر إلى خادم MCP للحصول على قائمة الأدوات الكاملة والإعداد (stdio أو Streamable HTTP). يمكنك أيضًا قراءة مركز الوكالات على موقع التسويق للحصول على وثائق قابلة للقراءة من الآلة موجهة نحو أنظمة الذكاء الاصطناعي. يمكن للمستخدمين النهائيين البدء من مفاتيح API ومCP في هذا مركز المساعدة.
إنشاء مفتاح API
افتح الإعدادات → API.
انقر على مفتاح جديد وأعطه اسمًا يوضح مكان استخدامه، مثل خادم الإنتاج.
انسخ المفتاح فورًا. فقط الجزء الأول منه يتم تخزينه، لذا يتم عرضه مرة واحدة فقط ولا يظهر مرة أخرى.
يؤثر المفتاح على حسابك. احفظه على خادمك، لا في متصفح، أو تطبيق هاتف محمول، أو مستودع عام. إذا تسرب المفتاح، قم بإلغائه من الإعدادات → API وإنشاء مفتاح جديد.
يمكنك الاحتفاظ بـ 10 مفاتيح نشطة على الأقل، إعادة تسمية أي منها في أي وقت، ومشاهدة آخر مرة تم استخدام كل منها فيها. إلغاء صلاحية مفتاح يتوقف عن معالجة طلباته فورًا.
التحقق من طلب
أرسل المفتاح كطوق تحمل:
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_مفتاحك"يجيب الطلبات بدون مفتاح صالح بـ 401 مع الكود unauthorized.
GET /me يعيد معرف حسابك، بريدك الإلكتروني، الخطة، وميزانية المحفظة (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 سنت = 1 ائتمان عرضي). إذا تم قطع التدفق في منتصف الطريق، فإن الجمل التي تم تسليمها بالفعل لا تزال مدفوعة.
إذا لم يكن لديك رصيد كافٍ لتغطية الائتمان المحجوز، يجيب API بـ 402 مع الكود payment_required قبل توليد أي شيء.
إنشاء المستندات لا يستهلك الائتمان، ولكن يتم احتسابه ضمن الحد اليومي للمستندات الخاص بخططك (مجاني: 3 يوميًا; Unlimited: لا يوجد حد يومي) ومقاييس مدة التحميل. تصدير الملفات لا يستهلك الائتمان.
الدفع مقابل تشغيل الصوت في السحابة داخل التطبيق
تشغيل السحابة داخل التطبيق يستعيد ذاكرة التخزين المؤقت لكل جملة في المستند: إعادة تشغيل جملة تم توليدها بالفعل على الخادم قد لا تكلف 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 (صفر عندما يكون الخاص). 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 لإضافة وقت الأقسام في PDF، DOCX، TXT، وCSV. تحتاج SRT وVTT إلى نص تحويل أو توقيت جمل كاملة. يتم حفظ text المخزن في GET /v1/documents/{id} مع رؤوس وقت النص. إخفاؤها هو ضبط فقط في قراءات التطبيق.