أفضل الممارسات لزمن الاستجابة

يُقضى الوقت بين طلبك والنتيجة القابلة للاستخدام في أربعة أماكن: اتصالك بالواجهة، والعمل نفسه، والفترة بين انتهاء العمل وعلمك به، وتنزيل النتيجة. تمنحك الواجهة خيارًا عند كل خطوة. تشرح هذه الصفحة أي خيار أسرع ولماذا، باستخدام حدود الواجهة وتوقيتاتها.

اختر أسلوب الاستدعاء حسب الحجم، لا حسب العادة

لكل خدمة نقطة نهاية متزامنة تُبقي الاتصال مفتوحًا حتى تكون النتيجة جاهزة، ونقطة نهاية غير متزامنة تجيب فورًا بـ jobId. الاستدعاء المتزامن هو أقصر طريق لنتيجة واحدة: طلب واحد، واستجابة واحدة، دون استدعاء ثانٍ. ويتحدد بحجم الإدخال.

نقطة النهاية	الحد الأقصى للإدخال	ما تحصل عليه
POST /v1/text-to-speech/sync	500 حرف من text	jobId، وstatus، وaudioUrl، وdurationSeconds، وcreditsConsumed
POST /v1/speech-to-text/sync	10 دقائق من الصوت، و150 ميجابايت	jobId، وstatus، وtranscription، وdurationSeconds، وlanguage، وnumbersAsDigits، وcreditsConsumed
POST /v1/text-to-speech	500 حرف من text	jobId وstatus
POST /v1/speech-to-text	10 دقائق من الصوت، و150 ميجابايت	jobId وstatus

يشترك نقطتا تحويل النص إلى كلام في الحد 500 حرف، وتشترك نقطتا تحويل الكلام إلى نص في الحد 10 دقائق، فالنقطة غير المتزامنة لا تمنحك إدخالًا أطول. ما تمنحك إياه هو اتصال حر: لا تبقى عمليتك مفتوحة أثناء تشغيل العمل، ولا يمكن لتفريغ طويل أن يصطدم بمهلة في مكدس HTTP لديك. استخدم الاستدعاء المتزامن عندما تحتاج إلى النتيجة في الطلب نفسه، مثلًا لتجيب مستخدمًا ينتظر. واستخدم الاستدعاء غير المتزامن عندما يمكن أن تصل النتيجة لاحقًا، أو عندما تملك عناصر كثيرة لمعالجتها. ويُقارن الأسلوبان بالتفصيل في الاستدعاء المتزامن وغير المتزامن.

للنص الأطول من 500 حرف، قسّمه عند حدود الجمل، وأرسل الأجزاء كمهام غير متزامنة منفصلة. يعود كل جزء بـ audioUrl خاص به، وتدمج الملفات على جانبك.

دع النتيجة تصلك

تمر المهمة غير المتزامنة بالحالتين pending وprocessing، وتنتهي بـ completed أو failed. يمكنك أن تعلم بالنهاية بطريقتين:

الطريقة	التأخير بعد انتهاء المهمة	الطلبات التي تكلفها
Webhook باسم job.completed أو job.failed	ثوانٍ. يُرسَل التسليم عند انتهاء المهمة، بمهلة 10 ثوان لكل محاولة، ويُعاد بعد 5 ثوان ثم 10 ثوان إذا فشل.	لا شيء على مفتاحك.
الاستعلام الدوري عبر GET .../jobs/{jobId}	حتى فاصل استعلام واحد.	طلب واحد لكل استعلام، يُحسب من حد المعدل.

يحمل جسم Webhook النتيجة نفسها: audioUrl لتحويل النص إلى كلام، وtranscription لتحويل الكلام إلى نص، وdurationSeconds للاثنين. لا تحتاج إلى استدعاء نقطة المهمة بعد وصول الحدث. سجّل نقطة نهاية في إعداد Webhook، وتحقق من كل تسليم كما في التحقق من توقيع Webhook.

الموصى به

• Webhook على job.completed وjob.failed، مع استعلام واحد عن المهمة إذا لم يصل أي حدث بعد 15 دقيقة من POST.

الأقل فاعلية

• حلقة استعلام لكل مهمة، تعمل من لحظة عودة POST حتى يتغير الحالة.

إذا كان لا بد من الاستعلام، فاحسب الأرقام أمام حد المعدل أولًا. يمكن لمفتاح أن يرسل 100 طلب لكل 60 ثانية على كل نقطة نهاية، ونقطة المهمة هي نقطة نهاية واحدة مهما كان jobId. استعلم بفاصل ثابت: 3 ثوان لتحويل النص إلى كلام، و5 ثوان لتحويل الكلام إلى نص، ولا تنزل أبدًا عن ثانية واحدة. النمط الكامل في أعد المحاولة بأمان. عند 3 ثوان، تكلّف المهمة الواحدة 20 طلبًا في الدقيقة، فخمس مهام تُستعلم معًا بمفتاح واحد تملأ الحد. وعند 5 ثوان تكون 12 طلبًا في الدقيقة، وثماني مهام. وما زاد على ذلك، فأطِل الفاصل، أو وزّع المهام على عدة مفاتيح، أو انتقل إلى Webhooks. وتوقف عن الاستعلام فور أن تصبح status قيمة completed أو failed، فالاستعلام الأسرع لا ينهي المهمة أبكر.

استعلم عن المهمة عندما لا يأتي أي حدث

تُعلَّم المهمة التي تبقى في processing أكثر من 10 دقائق بأنها failed، ويكون error فيها Job timed out — AI server did not respond، وتتغير الحالة خلال 15 دقيقة من POST. لا ترسل هذه المهلة أي job.failed Webhook، فالعميل الذي يستمع إلى الأحداث فقط لن يعرف عنها أبدًا. ضع مهلتك الخاصة: إذا لم يصل أي من الحدثين بعد 15 دقيقة من POST، فاجلب المهمة مرة واحدة واقرأ status.

أعد استخدام الاتصال

كل طلب إلى الواجهة يمر عبر HTTPS، والاتصال الجديد يدفع ثمن مصافحة TCP ومصافحة TLS قبل أن يُرسل أول بايت من طلبك. احتفظ بعميل HTTP واحد لكل عملية، ودعه يعيد استخدام الاتصالات. في Python، أنشئ requests.Session() واحدًا واستدعه لكل طلب. وفي Node، يحتفظ fetch المدمج بالاتصالات حية افتراضيًا، فلا تنشئ وكيلًا جديدًا لكل استدعاء. الحلقة الضيقة التي تستعلم باتصال جديد في كل مرة تقضي وقتًا في المصافحات أكثر مما تقضيه في الواجهة.

خزّن قائمة الأصوات مؤقتًا

تعيد GET /v1/text-to-speech/voices كل الأصوات النشطة في استجابة واحدة، دون ترقيم صفحات ودون مرشّحات، فلا فائدة من استدعائها مع كل طلب. اجلبها عند بدء العملية، واحتفظ بها في الذاكرة، وصفِّها محليًا بحسب language. وأعد جلبها عندما يجيب استدعاء توليد بالرمز 404 مع Voice not found، وهذا ما تقوله الواجهة عندما يُعطَّل صوت منذ أن خزّنت القائمة. الحقول موجودة في أصوات تحويل النص إلى كلام وخياراته.

أرسل صوتًا تستطيع الواجهة قياسه

تقرأ نقطتا الرفع مدة الملف من بياناته الوصفية قبل تشغيل أي عمل، لتطبيق الحد 10 دقائق ولتسعير الاستدعاء. الملف الذي لا تُقرأ مدته لا يُرفض: يُقبل ويُسعَّر من حجمه بدلًا من ذلك، بمعدل ثانية واحدة لكل 16 000 بايت، مع التقريب إلى الأعلى. وما إذا كان ذلك أكثر من الطول الحقيقي أو أقل يعتمد على معدل البت في الملف، ولا يُصحَّح الاحتساب بعد ذلك. فاكتب الملفات بصيغة سليمة حتى يطابق الاحتساب الصوت، وفضّل حاوية مضغوطة: الملف الأصغر يقضي وقتًا أقل في النقل.

نزّل الصوت مرة واحدة

audioUrl رابط موقّع إلى ملف الصوت، والرابط ينتهي. نزّل الملف عندما تستلم الرابط، واحفظه لديك، وقدّمه من هناك. لا تضمّن الرابط في صفحة أو رسالة ستُفتح لاحقًا. وإذا انتهى رابط، فإن GET /v1/text-to-speech/jobs/{jobId} يعيد رابطًا جديدًا في كل استدعاء.

امنح كل نظام مفتاحه الخاص

يُحسب حد المعدل لكل مفتاح API على كل نقطة نهاية، لا لكل مساحة عمل. فقد تدفع مهمة دفعية مشغولة على مفتاح مشترك خدمة تفاعلية على المفتاح نفسه إلى 429. أنشئ مفتاحًا لكل نظام يستدعي الواجهة، فيكون لكل منها 100 طلب لكل 60 ثانية، ولا يؤخر حد أحدها الآخرين. وتحدد خطتك عدد المفاتيح النشطة التي تستطيع مساحة العمل امتلاكها؛ راجع احصل على مفتاح API.

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

هل نقطة النهاية غير المتزامنة أسرع؟

لا. يستغرق العمل الوقت نفسه في الحالتين. تُحرر نقطة النهاية غير المتزامنة اتصالك، وتتيح لك تشغيل مهام كثيرة في وقت واحد. أما المتزامنة فتعطيك النتيجة في جولة واحدة.

هل الاستعلام الأكثر تكرارًا ينهي المهمة أبكر؟

لا. يستهلك فقط حصتك البالغة 100 طلب في الدقيقة أسرع. تنتهي المهمة عندما ينتهي العمل.

كم يمكنني أن أنتظر استدعاءً متزامنًا؟

لا يوجد حد زمني من جهة الخادم للاستدعاء المتزامن. اضبط مهلة عميلك حسب حجم الإدخال: ملف مدته 10 دقائق يستغرق أطول من ملف مدته 10 ثوان.

هل المهلة 15 دقيقة مضمونة؟

نعم. المهمة التي تبقى في processing أكثر من 10 دقائق تُعلَّم failed خلال 15 دقيقة من POST، فلا تبقى المهمة في processing أطول من ذلك أبدًا.

صفحات ذات صلة

• الاستدعاء المتزامن وغير المتزامن
• أعد المحاولة بأمان
• حد معدل الطلبات
• إعداد Webhook
• أحداث Webhook
• التسليم وإعادة المحاولة والأخفاق في Webhooks
• دليل البدء السريع لتحويل النص إلى كلام
• دليل البدء السريع لتحويل الكلام إلى نص
• الأخطاء
• أفضل الممارسات للأمان