التوثيق
المطورون / كلام إلى نص
تنزيل مهمة مكتملة لتحويل الكلام إلى نص بصيغة TXT أو SRT أو JSON
https://api.echonova.ai/v1/speech-to-text/jobs/{jobId}/exportتعيد النص المفرّغ لمهمة API مكتملة في مساحة عمل هذا المفتاح في ملف: `txt` هو النص المفرّغ، و`srt` ترجمة لا يتجاوز كل مقطع منها 7 ثوانٍ وسطرين من 42 حرفًا، ويبدأ كل مقطع بتسمية متحدثه حين حُدّد المتحدثون، و`json` يحمل النص والمتحدثين والمقاطع الموقّتة. يحدد `lang` لغة تسميات المتحدثين. المهمة التي لم تكتمل تُرجع `400`، والمهمة التابعة لمساحة عمل أخرى تُرجع `404`. يحتاج المفتاح إلى وصول إلى تحويل الكلام إلى نص.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات المسار
`jobId` الذي أعادته API عند إنشاء المهمة.
معاملات الاستعلام
`txt`: النص المفرّغ. `srt`: ترجمة، بمقطع كل بضع ثوانٍ، يحمل كل منها متحدثه حين يكون معروفًا. `json`: النص والمتحدثون والمقاطع الموقّتة.
لغة تسميات المتحدثين: `en` تعطي "Speaker 1"، و`ar` تعطي "المتحدث 1".
الاستجابة
200 text/plain, application/x-subrip, application/json الجسم هو الملف نفسه، لا الغلاف، مع Content-Disposition: attachment واسم الملف. أما الأخطاء فتستخدم الغلاف.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. `jobId` ليس معرّفًا سداسيًا عشريًا من 24 خانة.
الحل. استخدم المعرّف كما أعاده طلب الإنشاء تمامًا.
متى يحدث. معامل الاستعلام `format` مفقود، أو ليس `txt` أو `srt` أو `json`.
الحل. أرسل `format=txt` أو `format=srt` أو `format=json`.
متى يحدث. معامل الاستعلام `lang` يحمل قيمة غير `en` أو `ar`.
الحل. أرسل `lang=en` أو `lang=ar`، أو احذفه لتكون `en`.
متى يحدث. المهمة في حالة `pending` أو `processing` أو `failed`؛ لا يوجد نص مفرّغ للتنزيل إلا في المهمة المكتملة.
الحل. انتظر Webhook `job.completed`، أو استعلم دوريًا عن `GET /v1/speech-to-text/jobs/{jobId}` حتى يصبح `status` هو `completed`.
متى يحدث. متن الطلب أو الاستعلام يحمل حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. مساحة العمل التي يتبعها المفتاح ليس لديها اشتراك.
الحل. تحقّق من خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة ولا تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح مقيّد، وتحويل الكلام إلى نص ليس من الخدمات المسموح بها له.
الحل. عدّل المفتاح وامنحه تحويل الكلام إلى نص، أو استخدم مفتاحًا آخر.
متى يحدث. معرّف المهمة غير معروف، أو أن المهمة تتبع مساحة عمل أخرى، أو أنها أُنشئت من البوابة.
الحل. استخدم `jobId` من مهام API في مساحة العمل هذه.
متى يحدث. المفتاح أرسل أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أن عنوان IP واحدًا أرسل أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يرد الخادم دون أي مفتاح)؛ و header `Retry-After` يحمل عدد الثواني المطلوب انتظارها.
الحل. انتظر عدد الثواني المذكور في `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه API.
الحل. تحقّق من الطلب، ثم أعد المحاولة بعد لحظة قصيرة؛ وتواصل مع الدعم إذا تكرر الخطأ.
متى يحدث. انقطاع مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
متى يحدث. انتهاء مهلة مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
curl "https://api.echonova.ai/v1/speech-to-text/jobs/{jobId}/export?format=srt" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o download.srtالسلام عليكم، كيف حالك؟ بخير، الحمد لله.