الرابط الأساسي https://api.echonova.ai

سجل التغييرات

سجل التغييرات

إصدار API، وما يُعدّ تغييرًا كاسرًا، وقائمة مؤرخة بكل تغيير على نقاط نهاية v1 منذ إطلاقها.

هذه الصفحة سجل لما تغيّر في API المطورين ومتى. اقرأها قبل أن ترقّي عميلًا، وراجعها عندما يبدأ طلب كان يعمل في الفشل.

الإصدار

يوجد إصدار واحد للواجهة، هو v1، وهو جزء من كل مسار: /v1/text-to-speech و/v1/speech-to-text ونقاط النهاية التي تحتهما. لا يوجد header للإصدار. التغيير الذي لا يمكن إجراؤه داخل v1 وفق السياسة أدناه يُطلق تحت بادئة جديدة، ويبقى v1 يعمل لفترة منشورة.

سياسة التغييرات الكاسرة

التغيير الكاسر هو التغيير الذي يجعل طلبًا كان يعمل بالأمس يفشل اليوم، أو يغيّر معنى استجابة كان العميل يقرؤها من قبل.

كاسر غير كاسر
حذف نقطة نهاية أو إعادة تسميتها، أو حذف حقل طلب أو حقل استجابة أو حدث Webhook أو إعادة تسميته. إضافة نقطة نهاية.
جعل حقل طلب اختياري حقلًا مطلوبًا. إضافة حقل طلب اختياري.
خفض حد: أحرف أقل، أو صوت أقصر، أو ملف أصغر، أو طلبات أقل في الدقيقة. رفع حد.
تغيير نوع حقل أو حالة HTTP لاستجابة. إضافة حقل إلى استجابة أو إلى جسم Webhook.
تغيير مخطط المصادقة أو صيغة المفتاح. إضافة نوع حدث Webhook جديد. يُرسل فقط إلى Webhooks المشتركة فيه.
تغيير نص errorMessage موجود. إضافة errorMessage جديد لحالة فشل جديدة.

تنتج خاصيتان للواجهة من هذا الجدول. أولًا، تُرفض الحقول غير المعروفة في جسم JSON أو في سلسلة الاستعلام بالرمز 400 مع property <name> should not exist، لذلك لا ينبغي للعميل أن يرسل حقلًا قبل المدخل أدناه الذي يقدّمه. ونقطتا رفع الملفات في تحويل الكلام إلى نص تقرآن حقول النموذج المسماة وتتجاهلان أي حقل نموذج آخر. ثانيًا، ينبغي للعميل أن يقرأ الحقول التي يحتاجها من الاستجابة ويتجاهل الباقي، لأن حقولًا جديدة ستظهر دون إشعار.

تُدرج التغييرات الكاسرة أدناه مع تاريخها.

التغييرات

2026-10-23

أُضيف:

  • تقبل نقطتا رفع تحويل الكلام إلى نص، POST /v1/speech-to-text وPOST /v1/speech-to-text/sync، حقل نموذج اختياريًا باسم identify_speakers بقيمة true أو false. القيمة الافتراضية هي false، فالطلب الذي لا يرسله يحصل على النص المفرّغ نفسه كما كان من قبل. والقيمة غير true أو false أو 1 أو 0 تحصل على 400 مع identify_speakers must be true or false.
  • صارت identifySpeakers وsegments وspeakers تُعاد في الاستجابة المتزامنة وفي المهمة التي تعيدها الجلب والقائمة. تحمل segments القيم start وend وtext وspeaker (spk0 أو spk1 أو … أو null)؛ وتحمل speakers القيمتين id وtalkTime. المهام التي أُنشئت قبل هذا التاريخ تُظهر false و[] و[]. ولم يتغير جسم Webhook ‏job.completed.
  • تنزّل GET /v1/speech-to-text/jobs/{jobId}/export مهمة مكتملة بقيمة format=txt أو srt أو json، مع تسميات المتحدثين بقيمة lang=en أو ar. الجسم هو الملف، لا الغلاف. وتضيف الرسائل format must be one of the following values: txt, srt, json وlang must be one of the following values: en, ar وJob is not completed، وكلها 400. انظر صيغ تحويل الكلام إلى نص ومخرجاته.

2026-10-21

كاسر:

  • صار jobId الذي ليس من 24 حرفًا سداسيًا عشريًا يحصل على 400 مع Invalid identifier في مسارات GET وDELETE الخاصة بالمهام. كان DELETE يجيب عنه بـ 404 من قبل، وكان المعرّف من 12 حرفًا يجيب بـ 404.
  • صارت طريقة HTTP الخاطئة على مسار /v1 موجود تحصل على 405 مع Method not allowed وheader باسم Allow. كانت 404.

تغيّر:

  • صار مسار /v1 غير المعروف يحصل على 404 مع Route not found. كان Cannot GET ….

أُضيف:

  • يحمل كل خطأ على مسار /v1 الحقل docs، بما في ذلك 413 و400 للجسم الذي ليس JSON صالحًا.
  • يقبل سجل الطلبات فلتر requestId، ويضم تبويب السجلات في النشاط ابحث بمعرّف الطلب. ويعرض الصوت المعالَج الثواني عندما يقل عن دقيقة.

2026-10-20

أُضيف:

  • يسجّل النشاط وسجل الطلبات الآن كل طلب إلى /v1 يُرسل بمفتاح معروف، بأي أسلوب وبأي حالة. تحصل طلبات GET وDELETE على صفوف أيضًا. لا تخصم طلبات GET أي رصيد.
  • جسم JSON أكبر من 100 كيلوبايت يعيد 413 مع Request body is larger than 100 KB. والجسم الذي ليس JSON صالحًا يعيد 400 مع Request body is not valid JSON. لا صف لأي منهما في النشاط، لأن المفتاح لم يُفحص بعد.
  • الجسم المُرسل إلى POST /v1/text-to-speech أو POST /v1/text-to-speech/sync أو تذكرة ودجت بـ Content-Type غير application/json يعيد 415 مع Content-Type must be application/json.
  • تعرض نافذة إضافة نقطة النهاية سر توقيع Webhook الجديد مرة واحدة، مع زر نسخ.

تغيّر:

  • صار حد IP يحتسب فقط الطلبات التي يرفضها فحص المفتاح. لا يحجب هذا الحد مفتاحًا صالحًا أبدًا، وتُقيَّد المفاتيح الصالحة لكل مفتاح فقط.
  • صار apiKeyName في spending.warning وspending.exhausted اسم المفتاح، لا معرّفه.

2026-10-15

أُضيف:

  • يقبل نقطتا رفع تحويل الكلام إلى نص، POST /v1/speech-to-text وPOST /v1/speech-to-text/sync، حقل نموذج اختياريًا باسم numbers_as_digits بقيمة true أو false. القيمة الافتراضية هي true: تعود الأعداد المنطوقة أرقامًا، كما كان من قبل. أرسل false لتبقى كما قيلت كلمات. لا تُحوَّل النصوص الإنجليزية في أي من الحالتين.
  • صار numbersAsDigits يُعاد في الاستجابة المتزامنة وفي المهمة التي تعيدها الجلب والقائمة. المهام التي أُنشئت قبل هذا التاريخ تُظهر true.

2026-10-11

أُضيف:

  • تنقية الصوت: POST /v1/sound-cleaning وGET /v1/sound-cleaning/jobs وGET /v1/sound-cleaning/jobs/{jobId}. الرفع متزامن، حتى 10 دقائق و150 ميجابايت، بصيغة MP3 أو WAV أو FLAC أو OGG/Opus، ويكلّف 1,000 credits في الدقيقة. راجع دليل البدء لتنقية الصوت.
  • clean قيمة جديدة في الخدمات المسموح بها للمفتاح. المفتاح الذي لا يقيّد الخدمات يستطيع استخدام تنقية الصوت فورًا. أما المفتاح الذي يسرد خدماته فلا يستطيع ذلك، حتى تضغط تعديل في البوابة وتفعّل تنقية الصوت؛ وإلى أن تفعل ذلك تحصل استدعاءات تنقية الصوت منه على 403.

تغيّر:

  • حدود كل طلب: يُقيَّد text في نقطتي تحويل النص إلى كلام بـ 500 حرف، ويُقيَّد الصوت في نقطتي تحويل الكلام إلى نص وفي تنقية الصوت بـ 10 دقائق. صارت رسالة المدة في نقطتي تحويل الكلام إلى نص هي Audio exceeds the 10-minute limit.
  • تغيّرت وحدة الرصيد. يكلّف تحويل النص إلى كلام رصيدًا واحدًا لكل حرف من text، بما في ذلك المسافات وفواصل الأسطر؛ ويكلّف تحويل الكلام إلى نص 100 credits في الدقيقة من الصوت، يُحتسب بالثانية. راجع الرصيد.
  • تحتفظ creditsConsumed وcreditsUsed وcreditLimit بأسمائها وأنواعها؛ أما قيمها فبالوحدة الجديدة، أي أرصدة صحيحة بلا كسور. ضُرب حد الرصيد لكل مفتاح في 3,000 لينتقل إلى الوحدة الجديدة، فصار الحد 100 يُقرأ الآن 300,000.
  • صارت الأرصدة أعدادًا صحيحة. يُقرَّب كل خصم إلى رصيد صحيح (تقريب نصفي للأعلى، وبحد أدنى 1)، لذلك لا تكون creditsConsumed عددًا عشريًا أبدًا؛ استدعاء تحويل كلام إلى نص مدته ثانية واحدة يكلّف 2 credits، لا 1.666667. وcreditsUsed عدد صحيح أيضًا.

2026-10-06

أُضيف:

  • يقبل نقطتا رفع تحويل الكلام إلى نص، POST /v1/speech-to-text وPOST /v1/speech-to-text/sync، حقل نموذج اختياريًا باسم language: auto أو ar أو en. القيمة الافتراضية هي auto.
  • صار language يُعاد في الاستجابة المتزامنة وفي المهمة التي تعيدها الجلب والقائمة. المهام التي أُنشئت قبل هذا التاريخ تُظهر auto.

كاسر:

  • قيمة language كانت تُتجاهل من قبل، مثل en-US أو arabic، صارت تحصل على 400 مع language must be one of: auto, ar, en. حقول النموذج الزائدة الأخرى ما زالت تُتجاهل.

2026-10-01

  • صارت مبالغ الرصيد في استجابات /v1 وفي webhooks spending.warning وspending.exhausted أعدادًا عشرية بحد أقصى 6 منازل عشرية. أسماء الحقول كما هي: creditsConsumed وcreditsUsed وcreditLimit. اقرأها كأعداد بفاصلة عائمة. ما زالت percentageUsed عددًا صحيحًا.
  • يُحتسب الرصيد بدقة. لم يعد الخصم يُقرَّب إلى رصيد صحيح كاملًا، ولا حد أدنى له.
  • صار الرصيد الواحد يساوي $0.095 من الاستخدام، وتُسعَّر كل خدمة بتكلفة المزوّد زائد 20%. راجع الرصيد.

2026-09-06

كاسر:

  • نقطتا تحويل النص إلى كلام: أُزيلت حقول الطلب creativity وexaggeration وstability. الطلب الذي ما زال يرسل أحدها يحصل على 400 مع property creativity should not exist، أو الرسالة نفسها للحقلين الآخرين.
  • نقطتا الرفع: الرفع الذي يتجاوز حد الحجم يُرفض الآن بالرمز 413 مع File too large أثناء استلام الجسم. قبل ذلك كان يُرفض بالرمز 400 مع Audio file exceeds the 50MB limit. بعد قراءة الملف كله.
  • نقطتا الرفع: تغيّرت رسالة رفض المدة. كانت Audio exceeds the 60-second limit. Use the async endpoint for longer audio. في النقطة المتزامنة، والنص نفسه مع 1800-second في النقطة غير المتزامنة. صارت Audio exceeds the 20-minute limit. وAudio exceeds the 1-hour limit.

حدود رُفعت:

  • POST /v1/text-to-speech/sync: من 500 إلى 5 000 حرف لـ text. تبقى النقطة غير المتزامنة عند 5 000، فصارت النقطتان تشتركان في حد واحد. كان الحد غير المتزامن قد صار 20 000 لفترة قصيرة في اليوم نفسه؛ وهو الآن 5 000.
  • POST /v1/speech-to-text/sync: مدة الصوت من دقيقة واحدة إلى 20 دقيقة.
  • POST /v1/speech-to-text: مدة الصوت من 30 دقيقة إلى ساعة واحدة.
  • نقطتا الرفع: حجم الملف من 50 ميجابايت إلى 150 ميجابايت.

أُضيف:

  • نقطتا تحويل النص إلى كلام: الحقول الاختيارية cfg (من 1 إلى 5، والافتراضي 2)، وnumSteps (16 أو 32 أو 64 أو 128، والافتراضي 32)، وtashkeel (قيمة منطقية، والافتراضي false). بقي speed (من 0.5 إلى 2، والافتراضي 1) كما هو. عند حذف حقل يُطبَّق الافتراضي، فيتصرف الطلب الذي لا يحملها كما كان من قبل.
  • Webhooks: صار حدثا job.completed وjob.failed يُرسلان عندما ينتهي مهمة غير متزامنة بدأت بمفتاح API. قبل هذا التاريخ كان يمكن الاشتراك في الحدثين لكنهما لم يكونا يُرسلان.

2026-06-08

كاسر:

  • نقطتا الرفع: تغيّرت رسائل رفض المدة من Audio exceeds 30 minute limit (got <seconds>s) وSync STT supports up to 60s. Use the async endpoint for longer audio. إلى Audio exceeds the 1800-second limit. Use the async endpoint for longer audio. وAudio exceeds the 60-second limit. Use the async endpoint for longer audio.
  • نقطتا الرفع: الطلب الذي لا يحمل جزء ملف يُرفض بالرسالة File is required بدلًا من Audio file is required.

2026-06-07

أول إصدار من v1:

  • تحويل النص إلى كلام: POST /v1/text-to-speech حتى 5 000 حرف، وPOST /v1/text-to-speech/sync حتى 500 حرف، وGET /v1/text-to-speech/voices، وGET /v1/text-to-speech/jobs، وGET /v1/text-to-speech/jobs/{jobId}.
  • تحويل الكلام إلى نص: POST /v1/speech-to-text حتى 30 دقيقة من الصوت، وPOST /v1/speech-to-text/sync حتى دقيقة واحدة، وكلاهما حتى 50 ميجابايت، وGET /v1/speech-to-text/jobs، وGET /v1/speech-to-text/jobs/{jobId}.
  • المصادقة بـ Authorization: Bearer ومفاتيح تبدأ بـ ek_.
  • حد معدل 100 طلب كل 60 ثانية لكل مفتاح على كل نقطة نهاية.
  • سجلات الطلبات في البوابة.
  • Webhooks مع حدثي spending.warning وspending.exhausted.

الأسئلة الشائعة

كيف أثبّت عميلي على إصدار معين؟

كل مسار يبدأ بـ /v1، وهذه البادئة هي الإصدار. لا يوجد header للإصدار ترسله.

ماذا يحدث إذا واصلت إرسال حقل تمت إزالته؟

يحصل على 400 مع property <name> should not exist. أزل الحقل؛ عندها يتصرف الطلب كما كان قبل أن يوجد الحقل.

هل يكسر حقل استجابة جديد عميلي؟

لا، إذا كان العميل يقرأ الحقول التي يحتاجها ويتجاهل الباقي. تُضاف الحقول دون إشعار؛ وحذف حقل أو إعادة تسميته تغيير كاسر وتُدرج هنا.