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

المطورون

حدود معدل الطلبات

كم طلبًا يستطيع مفتاح API واحد أن يرسله في الدقيقة، وheaders التي تُبلغ بالعدد، وشكل استجابة 429، وكيف تتراجع بأمان.

تحد الواجهة عدد الطلبات التي يستطيع مفتاح واحد إرسالها إلى نقطة نهاية واحدة خلال 60 ثانية. تعرض هذه الصفحة الأرقام، وheaders التي تُبلغ بموقعك، واستجابة 429 بالضبط حتى تتعامل معها في الكود.

الحد

البند القيمة
الطلبات المسموحة 100
النافذة 60 ثانية. يُحتسب كل طلب ضمن الحد لمدة 60 ثانية بعد إرساله.
النطاق مفتاح API واحد على نقطة نهاية واحدة. لكل مفتاحين عدّادان منفصلان، والاستدعاءات التي يرسلها مفتاح إلى /v1/text-to-speech لا تُحتسب على استدعاءاته إلى /v1/speech-to-text/jobs.
الحظر عندما يتجاوز مفتاح 100 طلب على نقطة نهاية، ترفض تلك النقطة المفتاح لمدة 60 ثانية. لا تُحتسب الطلبات المرفوضة. وعند انتهاء الحظر يبدأ العدّاد من الصفر.
ينطبق على كل نقاط النهاية الخمس عشرة تحت /v1.

يُقيَّد POST /v1/sound-cleaning أيضًا بحجم الرفع، لا بعدد الطلبات فقط: صوت مدته 10 دقائق أو أقل، وحجمه 150 ميجابايت أو أقل، بصيغة MP3 أو WAV أو FLAC أو OGG/Opus. راجع دليل البدء لتنقية الصوت.

العدّاد لكل مفتاح، لا لكل مساحة عمل. إذا كانت عدة أنظمة تشترك في مساحة عمل، فأعطِ كل نظام مفتاحه الخاص حتى لا يحظر نظام مزدحم الأنظمة الأخرى.

Response headers

يعيد الطلب المقبول ثلاثة headers تبيّن موقع المفتاح على نقطة النهاية. ويعيد الطلب المرفوض header Retry-After بدلًا منها.

Header متى المعنى
X-RateLimit-Limit طلب مقبول الحد، أي 100.
X-RateLimit-Remaining طلب مقبول الطلبات المتبقية في النافذة، و0 كحد أدنى.
X-RateLimit-Reset طلب مقبول الثواني حتى تُعاد ضبط النافذة.
Retry-After طلب مرفوض الثواني حتى ينتهي الحظر.

استجابة 429

يحصل الطلب المرفوض على رمز HTTP 429 مع هذا الجسم:

{
  "data": null,
  "statusCode": 429,
  "success": false,
  "errorMessage": "ThrottlerException: Too Many Requests"
}

يوجد 429 آخر مختلف. عندما يدفع أي استدعاء المفتاح فوق حد رصيده، يقول الجسم Monthly spending limit exhausted ولا يُرسل header Retry-After. الانتظار لا يزيله؛ راجع الرصيد. تحقق من errorMessage قبل أن تعيد المحاولة.

ما تفعله

  • اقرأ Retry-After، وانتظر عدد الثواني المذكور، ثم أعد المحاولة. لا تعد المحاولة قبل ذلك؛ الطلبات المرسلة أثناء الحظر تُرفض، والحظر لا يقصر.
  • إذا أعدت المحاولة عند أخطاء أخرى أيضًا، فاستخدم التراجع الأُسّي مع عشوائية (jitter)، حتى لا تتحول موجة أخطاء إلى موجة طلبات.
  • راقب X-RateLimit-Remaining وخفّف السرعة قبل أن يصل إلى 0.
  • استخدم مفتاحًا لكل نظام. الحد لكل مفتاح، فالمفاتيح المنفصلة تملك نوافذ منفصلة.

ابقَ تحت الحد أثناء انتظار المهام

الاستعلام الدوري هو الطريقة المعتادة لتجاوز الحد. كل استعلام طلب على نقطة نهاية المهمة، أيًا كان jobId، لذلك دَع النتيجة تصلك حيثما أمكن.

الموصى به

  • Webhook على job.completed وjob.failed، وهو لا يكلّف أي طلب، مع استعلام واحد بعد 15 دقيقة من الصمت كاحتياط.

الأقل فاعلية

  • حلقة تستعلم عن /v1/text-to-speech/jobs/{jobId} كل 500 ميلي ثانية لكل مهمة قيد التنفيذ.

إذا كان لا بد من الاستعلام، فاستخدم فاصلًا ثابتًا لا يقل عن 3 ثوانٍ لتحويل النص إلى كلام، و5 ثوانٍ لتحويل الكلام إلى نص. راجع إعادة الطلبات بأمان للحلقة.

يوجد حد ثانٍ بالحجم نفسه، أي 100 طلب كل 60 ثانية لكل نقطة نهاية، ويُحتسب لكل عنوان IP للعميل. ولا يحتسب إلا الطلبات التي يرفضها فحص مفتاح API: مفتاح مفقود أو غير صالح (401)، أو مفتاح لا يملك صلاحية الخدمة (403)، أو خطة مساحة عمل غير نشطة أو غير موجودة (403). الطلب بمفتاح صالح لا يحجبه هذا الحد أبدًا. تُقيَّد المفاتيح الصالحة لكل مفتاح فقط. ويحصل عنوان IP المحجوب على جسم 429 أعلاه مع Retry-After، حتى لو أرسل مفتاحًا سيئًا.

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

هل الحد لكل مساحة عمل أم لكل مفتاح؟

لكل مفتاح، ولكل نقطة نهاية. لمفتاحين في مساحة عمل واحدة عدّادان منفصلان، والاستدعاءات التي يرسلها مفتاح إلى /v1/text-to-speech لا تُحتسب على استدعاءاته إلى /v1/speech-to-text/jobs.

هل تمدّ الطلبات المرفوضة الحظر؟

لا. لا تُحتسب الطلبات المرفوضة، وينتهي الحظر عندما يقول Retry-After. ولا تقصّره أيضًا.

هل تُحتسب الاستعلامات الدورية؟

نعم. كل طلب GET على نقطة نهاية مهمة هو طلب على حد تلك النقطة.

كيف أميّز هذا الخطأ 429 عن 429 حد الإنفاق؟

من errorMessage. هذا الخطأ يقول ThrottlerException: Too Many Requests ويحمل Retry-After، أما خطأ الإنفاق فيقول Monthly spending limit exhausted ولا يحمل header.