الأسئلة الشائعة
ما هو مبدأ عمل الواجهة؟
تعمل الواجهة كخدمة سحابية: ترسل النص عبر طلب POST، وتُستقبل ملف صوتي. تعتمد على محرك واحد مع خيارين للنموذج، وتستخدم بروتوكول JSON القياسي. يتم معالجة الطلبات بشكل تسلسلي، مما قد يسبب تأخيرًا طفيفًا تحت الضغط، مع سرعة توليد تقارب الوقت الحقيقي للنصوص الطويلة.
ما هي نقاط النهاية المتاحة؟
تتوفر ثلاث نقاط نهاية رئيسية: POST /v1/audio/speech لتوليد الصوت، وGET /v1/voices لاستعراض الأصوات واللغات والصيغ والأسعار، وGET /v1/models لعرض النماذج المتاحة. جميع هذه النقاط تعمل ضمن الـ API الأساسي المحدد، مما يسهل التكامل مع التطبيقات القائمة.
كيف يتم إرسال النص؟
يتم إرسال النص ضمن جسم الطلب بصيغة JSON، باستخدام الحقل input. يجب أن لا يتجاوز النص 4096 حرفًا في كل طلب. تشمل الأحرف المسافات وعلامات الترقيم. يتم تحديد النموذج والصوت والصيغة المطلوبة ضمن نفس الطلب لضمان دقة التوليد حسب الإعدادات المحددة.
ما هي صيغ الاستجابة؟
تدعم الواجهة خمس صيغ صوتية: mp3، wav، opus، flac، وpcm. يمكن تحديد الصيغة المطلوبة عبر حقل response_format في الطلب. هذه الصيغ تغطي معظم احتياجات التطبيقات من التوزيع عبر الويب إلى المعالجة عالية الدقة، مع ضمان توافقها مع المكتبات القياسية.
كيف تتم المصادقة؟
تتم المصادقة باستخدام مفتاح API خاص، يُمرر في رأس الطلب Authorization: Bearer tts-... . يتوفر مفتاح نشط واحد لكل حساب، ويمكن إصدار مفتاح جديد في أي وقت، مما يؤدي إلى إيقاف المفتاح القديم فورًا. هذا يضمن أمان الوصول إلى موارد الواجهة دون تعقيدات إضافية.
ما هو الحد الأقصى للنص؟
الحد الأقصى للنص المدخل في كل طلب هو 4096 حرفًا. تشمل الأحرف المسافات وعلامات الترقيم. للنصوص الأطول، يجب تقسيمها إلى أجزاء لا تتجاوز هذا الحد، ثم دمج الملفات الصوتية الناتجة. هذا يضمن معالجة فعالة للنصوص دون تجاوز سعة الطلب المحددة.
ما هو حد الطلبات؟
الحد هو 60 طلبًا في الدقيقة لكل مفتاح API. قبل أول إيداع، يكون الحد 10 طلبات في الدقيقة. يتم معالجة الطلبات بشكل تسلسلي، مما قد يؤدي إلى الانتظار في الطابور تحت الضغط. هذا الحد يضمن استقرار الخدمة ويمنع استهلاك الموارد بشكل مفرط.
هل يتم دعم SDK الخاص بـ OpenAI؟
نعم، الواجهة متوافقة مع SDK الرسمي لـ OpenAI. يمكنك تغيير base_url إلى https://api.k111.info/v1 واستخدام مفتاح الواجهة الخاص بك. هذا يسهل التكامل مع التطبيقات القائمة التي تستخدم مكتبات OpenAI، دون الحاجة إلى تعديل كبير في كود التطبيق أو مكتباته.
كيف يتم معالجة الأخطاء؟
إذا فشل توليف الصوت، يتم إرجاع الطلب كفاشل دون خصم الرصيد. يتم إرجاع المبلغ بالكامل في حالة الفشل. يتم الاحتفاظ ببيانات الطلب (الوقت، الأحرف، الحالة) للفوترة فقط. هذا يضمن عدم خسارة الرصيد في حال حدوث مشاكل تقنية أثناء المعالجة أو النقل.
ما الفرق بين الطلبات الناجحة والفاشلة؟
الطلبات الناجحة تُخصم منها التكلفة وتُرجع ملف صوتي. الطلبات الفاشلة لا تُخصم منها التكلفة ويتم إرجاع المبلغ بالكامل. يتم الاحتفاظ بسجل الطلبات للفوترة، بما في ذلك حالات الفشل. هذا يضمن شفافية في الفوترة ويمنع الخصم المزدوج أو الخطأ في حساب الرصيد المتاح.
كيف يتم تحديد اللغة؟
يمكن تحديد اللغة تلقائيًا بناءً على النص المدخل، حيث يُفترض أن يكون النص اللاتيني إنجليزيًا افتراضيًا. لتحديد لغة غير الإنجليزية، يجب تحديد رمز ISO في حقل language. تدعم الواجهة 23 لغة، وأي صوت يمكنه التحدث بأي من هذه اللغات دون قيود إضافية.
ما هي الأصوات المتاحة؟
تتوفر 8 أصوات: نساء (aria, nova, luna, sage) ورجال (felix, milo, atlas, orion). كل صوت له نبرة مميزة، من الراوي الواضح إلى الموثق العميق. الأصوات مبنية على تسجيلات مرخصة من LibriVox، وتتميز بعلامة مائية غير مرئية تدل على أنها كلام مولد.
هل يمكن تغيير سرعة الصوت؟
نعم، يمكن ضبط سرعة الصوت بين 0.25 و4.0. يتم تحديد السرعة عبر حقل speed في الطلب. هذا يسمح بتسريع أو إبطاء الكلام حسب الحاجة، مع الحفاظ على جودة الصوت.
كيف يتم دمج النصوص الطويلة؟
يتم تقسيم النص إلى أجزاء لا تتجاوز 4096 حرفًا، وإرسال كل جزء كطلب منفصل. ثم يتم دمج الملفات الصوتية الناتجة. هذه العملية تتطلب تطبيق العميل لإدارة التقسيم والدمج، مما يضمن معالجة النصوص الطويلة دون تجاوز حدود الطلب المحددة.
هل الواجهة تدعم البرمجة المتوازية؟
الطلبات تُعالج بشكل تسلسلي، مما يعني أن الطلبات قد تنتظر في الطابور تحت الضغط. لا توجد ضمانات للوقت الفعلي. هذا قد يؤثر على سرعة الاستجابة في التطبيقات عالية الحمل، حيث يجب مراعاة الانتظار في الطابور عند تصميم سير العمل.
ما هي تكلفة الطلب الواحد؟
التكلفة هي 10 دولارات أمريكية لكل مليون حرف، أي 0.01 دولار لكل 1000 حرف. تشمل الأحرف المسافات وعلامات الترقيم. الطلبات الفاشلة مجانية. لا توجد خطط شهرية أو رسوم ثابتة. الفوترة تعتمد على الاستخدام الفعلي، مما يجعلها مثالية للمشاريع ذات الحجم المتغير.
المبدأ الأساسي للعملية
تعمل واجهة برمجة التطبيقات (API) الخاصة بنا كنظام سحابي بسيط وموثوق لتوليد الكلام من النص (TTS). يعتمد المبدأ الأساسي على إرسال طلب HTTP يحتوي على نص إلى خادمنا، حيث تتم معالجته وتحويله إلى ملف صوتي رقمي، ثم إرساله مرة أخرى إلى التطبيق المستقبِل.
إرسال النص عبر HTTP
يتم إرسال البيانات إلى نقطة النهاية POST https://api.k111.info/v1/audio/speech باستخدام بروتوكول HTTPS. يجب أن يحتوي جسم الطلب على النص المراد تحويله، الذي لا يتجاوز 4096 حرفاً، بالإضافة إلى تحديد النموذج والصوت والصيغة المطلوبة.
- استخدام HTTP POST مع جسم الطلب بصيغة JSON.
- إرسال النص المحدد في حقل
inputمع تحديد النموذج في حقلmodel.
معالجة الطلب في السحابة
يتم استلام الطلب ومعالجته على خوادم السحابة الخاصة بنا. يتم تقسيم النص تلقائياً إلى أجزاء لا يتجاوز كل منها 4096 حرفاً، ثم يتم توليد الصوت لكل جزء على حدة.
تتم معالجة الطلبات بالتسلسل، مما يعني أن الطلبات الإضافية قد تنتظر في طابور أثناء المعالجة، خاصة تحت الأحمال العالية.
استلام الملف الصوتي
بعد اكتمال التوليد، يتم إرسال الملف الصوتي كاستجابة للطلب. يمكن للمستخدم استلام الملف بصيغ متعددة مثل MP3 أو WAV أو OPUS أو FLAC.
يتم إرجاع الملف مباشرة في استجابة HTTP، مما يسمح للتطبيق المستقبِل بحفظه أو تشغيله فوراً دون الحاجة إلى تخزين وسيط معقد.
النقاط النهائية للواجهة
تتكون واجهة برمجة التطبيقات (API) من ثلاثة نقاط نهائية أساسية تدير دورة حياة توليد الصوت بالكامل. تبدأ العملية بإرسال النص إلى نقطة التوليف، بينما توفر النقاط الأخرى معلومات تعريفية حول الأصوات والنماذج المتاحة.
تعمل هذه النقاط معاً لتوفير تجربة تكامل سلسة، حيث تتيح للمطورين التحكم الدقيق في مخرجات الصوت عبر هياكل بيانات متوافقة مع المعايير المفتوحة.
نقطة توليف الصوت
نقطة POST /v1/audio/speech هي القلب النابض للخدمة. تستقبل طلبات JSON تحتوي على النص المطلوب تحويله، وتعيد استجابة تحتوي على الملف الصوتي المُنتج مباشرة. تدعم هذه النقطة حقول التحكم في السرعة والصوت واللغة.
يتم معالجة الطلبات في السحابة، مع مراعاة حدود الأحجام والسرعة المحددة مسبقاً.
- نقطة الإرسال:
POST /v1/audio/speech - تتطلب هيكل JSON مطابق لمواصفات OpenAI
- تعيد الملف الصوتي فور اكتمال التوليف
نقطة قائمة الأصوات
توفر النقطة GET /v1/voices قائمة بـ 8 أصوات افتراضية، وتحدد اللغات الـ 23 المدعومة، بالإضافة إلى الصيغ الصوتية المتاحة والأسعار. تتيح هذه البيانات للمطورين اختيار الصوت واللغة المناسبين لتطبيقهم بدقة.
تساعد هذه المعلومات في إعداد المتغيرات قبل إرسال طلب التوليف.
- نقطة الاستعلام:
GET /v1/voices - تعرض الأصوات الثمانية والدعم اللغوي
- توضح الصيغ والأسعار المتاحة
نقطة قائمة النماذج
توفر النقطة GET /v1/models تفاصيل حول النماذج المتاحة (tts-1 و tts-1-hd). كلا النموذجين يستخدمان محرك الصوت نفسه، مما يعني أن الجودة متطابقة، بينما يختلف السعر قليلاً حسب اختيار النموذج.
تتيح هذه النقطة التحقق من النماذج المدعومة قبل البدء في التكامل.
- نقطة الاستعلام:
GET /v1/models - تعرض نموذجي
tts-1وtts-1-hd - توضح توافق المحرك مع الأصوات
هيكل البيانات المرسلة
يُشكّل هيكل البيانات المرسلة إلى الواجهة الأساسية للنموذج التنبؤي، حيث يُحدد المدخل النصي والمعالج الصوتي والمخرج النهائي. يتبع الهيكل مواصفات قياسية لضمان التوافق مع المكتبات الشائعة، مما يسهل عملية الدمج التقنية.
يتم تجميع الحقول الرئيسية في جسم الطلب بصيغة JSON، وتشمل تحديد النص المراد تحويله، ونبرة الصوت المطلوبة، والصيغة التقنية للملف الصوتي المُنشأ. هذه المعطيات هي المحدد الوحيد لجودة ومحتوى المخرجات.
حقل النص المدخل
يحتوي هذا الحقل على النص الفعلي الذي سيتم تحويله إلى كلام، بحد أقصى 4096 حرفاً لكل طلب. تشمل الأحرف المسافة والعلامات الترقيية في الحساب الإجمالي.
يتم معالجة النص عبر الخوادم السحابية لإنتاج ملف صوتي متوافق مع الحروف المحددة. في حال تجاوز النص الحد المسموح، يجب تقسيمه يدوياً أو برمجياً قبل الإرسال.
- الحد الأقصى: 4096 حرفاً لكل طلب
- يشمل المسافات والعلامات في الحساب
- صيغة الطلب: JSON
حقل الصوت المطلوب
يحدد هذا الحقل الشخصية الصوتية المستخدمة في التوليد، من بين ثمانية خيارات متاحة (مثل Aria، Nova، Felix). كل صوت يتميز بنبرة صوتية ونبرة محددة.
يجب تحديد الصوت بدقة لضمان توافق النبرة مع طبيعة النص. يتم دعم لغات متعددة لكل صوت، مما يتيح مرونة في اختيار النبرة المناسبة.
- 8 أصوات متاحة (4 إناث، 4 ذكور)
- دعم متعدد اللغات لكل صوت
- قيم مثل: aria, nova, felix
حقل الصيغة الصوتية
يحدد تنسيق الملف الصوتي الناتج، مع خيارات تشمل MP3 و WAV و OPUS و FLAC و PCM.
تختلف الصيغ في حجم الملف وجودة الصوت، حيث توفر WAV دقة عالية، بينما يوفر MP3 حجماً أقل. يتم إرجاع الملف في استجابة HTTP.
- MP3 (شائع)
- WAV (عالي الجودة)
- OPUS و FLAC و PCM
المصادقة والأمان
تعتمد المصادقة على إرسال مفتاح API فريد لكل حساب ضمن رأس الطلب "Authorization: Bearer"، مع ضمان نقل البيانات عبر بروتوكول HTTPS الآمن.
يتيح النظام إصدار مفتاح جديد في أي وقت، مما يؤدي إلى إلغاء المفتاح القديم فوراً، مما يضمن سيطرة دقيقة على الوصول إلى الخدمة.
استخدام مفتاح Bearer
تتطلب كل نقطة نهاية طلب رأس HTTP مخصص يحمل المفتاح بصيغة Bearer. يضمن هذا الأسلوب توحيد الاتصال مع المكتبات القياسية مثل OpenAI SDK دون تعقيدات إضافية.
- المفتاح يبدأ بـ "tts-" ويُصدر لحساب واحد فقط.
- يتم التحقق من صحة الطلب قبل بدء المعالجة أو احتساب التكلفة.
أمان النقل عبر HTTPS
يتم نقل جميع البيانات الحساسة ومحتوى النصوص عبر قنوات مشفرة باستخدام بروتوكول HTTPS، مما يحمي نصوصك ومفاتيحك أثناء الانتقال بين خادمك وخادماتنا.
إدارة المفاتيح النشطة
يحتوي كل حساب على مفتاح نشط واحد فقط. عند إصدار مفتاح جديد، يصبح القديم غير صالح فوراً، مما يلغي الحاجة إلى مراجعة يدوية للجلسات القديمة.
معالجة النصوص الطويلة
عند إرسال نصوص تتجاوز حد الـ 4096 حرفاً، يقوم النظام بتقسيم النص تلقائياً إلى أجزاء متتالية، مع ضمان عدم تجاوز الحد المسموح به لكل جزء لضمان دقة التوليد. كل جزء يُعالج كطلب مستقل، مما يتيح مرونة أكبر في التعامل مع المحتوى الطويل دون فقدان السياق الصوتي.
بعد معالجة الأجزاء، يتم دمج الملفات الصوتية الناتجة. هذه الآلية تتيح تحويل النصوص الطويلة إلى ملفات صوتية.
تقسيم النص تلقائياً
يتم تقسيم النص المدخل تلقائياً إلى أجزاء لا يتجاوز كل منها 4096 حرفاً، بما في ذلك المسافات وعلامات الترقيم. هذه العملية تحدث داخل الخادم دون حاجة إلى أي إعداد مسبق من المطور، مما يضمن توافق النص مع حدود الواجهة التقنية بدقة.
ربط الملفات الصوتية
بعد توليد كل جزء، يتم دمج الملفات الصوتية الناتجة. هذه العملية تتم تلقائياً، مما يوفر الوقت ويقلل من التعقيد التقني عند استخدام الواجهة في التطبيقات التي تتطلب ملفات صوتية طويلة.
إدارة الطوابير
تتم معالجة الطلبات بترتيب وصولها، مما يعني أن الطلبات اللاحقة قد تنتظر في طابور إذا كان النظام تحت حمل عالي. هذا يضمن استقرار الخدمة ودقة التوليد، حتى في أوقات الذروة، مع الحفاظ على ترتيب الملفات المربوطة بشكل صحيح.
إعدادات الصوت واللغة
تتيح واجهة البرمجة التحكم الدقيق في مخرجات الصوت من خلال إعدادات الصوت والسرعة. يتم تحديد النبرة والأسلوب عبر اختيار أحد الأصوات الثمانية المتاحة، مع إمكانية ضبط سرعة النطق لتتناسب مع متطلبات التطبيق، حيث تتراوح السرعة بين 0.25 إلى 4.0.
تحديد الصوت المفضل
يمكنك اختيار الصوت المناسب من بين ثمانية خيارات محددة مسبقاً، تتنوع بين الذكور والإناث، لكل منها نبرة مميزة مثل الرواية الهادئة أو الأخبار المحايدة. يتم تحديد الصوت عبر حقل voice في طلب JSON.
- أصوات نسائية: aria, nova, luna, sage
- أصوات ذكورية: felix, milo, atlas, orion
ضبط سرعة النطق
تسمح الإعدادات بتسريع أو إبطاء سرعة قراءة النص لتتناسب مع احتياجات المستمعين. يتراوح معامل السرعة من 0.25 (بطيء جداً) إلى 4.0 (سريع جداً)، ويتم تحديده عبر حقل speed في الطلب.
تحديد لغة النص يدوياً
بالرغم من محاولة النظام تخمين اللغة تلقائياً بناءً على النص المدخل، فإن تحديد حقل language يضمن دقة أعلى، خاصة مع النصوص غير الإنجليزية المكتوبة بالأحرف اللاتينية. تدعم الواجهة 23 لغة محددة بدقة.

الصيغ الصوتية المتاحة
توفر الواجهة خيارات متعددة لتحويل النص إلى ملفات صوتية، مما يتيح لك اختيار التنسيق الأنسب لتطبيقك. يتم تحديد الصيغة عبر حقل response_format في طلب JSON، وتعمل كل صيغة على توفير توازن مختلف بين حجم الملف وجودة الصوت.
صيغة MP3 الشائعة
تُعد صيغة MP3 الخيار الافتراضي والأكثر شيوعاً، حيث توفر حجماً صغيراً للملف مع الحفاظ على جودة صوت مقبولة لمعظم التطبيقات. هذا يجعلها مناسبة للنقل عبر الشبكات وتقليل استهلاك عرض النطاق الترددي.
صيغة WAV عالية الجودة
تقدم صيغة WAV ملفات صوتية غير مضغوطة، مما يضمن دقة أعلى في النطق. تُستخدم هذه الصيغة في الحالات التي تتطلب جودة صوت خام، مثل معالجة الصوت اللاحقة أو التطبيقات الحساسة للشفافية الصوتية.
صيغ OPUS و FLAC
تدعم الواجهة أيضاً صيغ OPUS و FLAC، والتي تقدم كفاءة ضغط عالية وجودة صوت ممتازة. تعتبر OPUS مثالية للبث، بينما توفر FLAC ضغطاً بدون فقدان للبيانات، مما يناسب الأرشيف طويل الأمد.
الحدود التقنية للأداء
تعتمد واجهة برمجة التطبيقات على معالجة النص ضمن حدود تقنية محددة لضمان استقرار الخدمة. يفرض النظام حدًا أقصى لطول النص في كل طلب، بالإضافة إلى تحديد معدل الطلبات المسموح به لكل مفتاح واجهة.
يؤثر حجم الحمولة على زمن الاستجابة، حيث تُعالج الطلبات بشكل متسلسل. في أوقات الذروة، قد يتأخر تنفيذ الطلبات بسبب تراكمها في قوائم الانتظار، مما يتطلب من المطورين مراعاة هذه الحدود عند تصميم سير العمل.
حد 4096 حرفاً للطلب
تقبل الواجهة نصوصًا يصل طولها إلى 4096 حرفًا في الطلب الواحد، بما في ذلك المسافات وعلامات الترقيم. إذا تجاوز النص هذا الحد، يجب تقسيمه يدويًا أو عبر المنطق البرمجي إلى أجزاء أصغر قبل الإرسال.
يتم احتساب كل حرف وعلامة ترقيم ضمن السعة المسموح بها. هذا الحد يضمن معالجة فعالة للنص دون استهلاك موارد زائدة في كل عملية توليف صوتي فردية.
- الحد الأقصى: 4096 حرفًا للطلب الواحد.
- يشمل المسافات وعلامات الترقيم.
- يتطلب تقسيم النصوص الأطول إلى أجزاء.
حد 60 طلباً في الدقيقة
يُسمح بـ 60 طلبًا في الدقيقة لكل مفتاح واجهة نشط. قبل أول شحن رصيد، يقتصر الحد على 10 طلبات في الدقيقة. يمكن إصدار مفتاح جديد لاستبدال المفتاح الحالي، مما يوقف المفتاح القديم فورًا.
يتم احتساب كل طلب تحويل نص إلى صوت ضمن هذا المعدل. تجاوز الحد يؤدي إلى رفض الطلبات الزائدة حتى يمر وقت الدقيقة التالية أو يتم تخفيف الحمل.
- الحد القياسي: 60 طلبًا في الدقيقة.
- الحد المبدئي: 10 طلبات في الدقيقة.
- المعدل محسوب لكل مفتاح واجهة.
تأخير المعالجة في الأحمال العالية
تُعالج الطلبات بشكل متسلسل، مما يعني أن الطلبات الزائدة عن القدرة اللحظية للنظام تدخل في طابور الانتظار. قد يؤدي ذلك إلى تأخير في استلام الملف الصوتي مقارنة بوقت إرسال الطلب.
تتراوح سرعة التوليف النموذجية ما بين 25 حرفًا من النص لكل ثانية من الصوت المُنشأ. في النصوص القصيرة، يستغرق التوليف بضع ثوانٍ إضافية، بينما تكون النصوص الأطول أقرب إلى الزمن الحقيقي.
- المعالجة متسلسلة قد تسبب طوابير انتظار.
- النصوص القصيرة تستغرق بضع ثوانٍ.
- النصوص الطويلة تساوي الزمن الحقيقي تقريبًا.
التكامل مع المكتبات الخارجية
تتطلب التكاملات السريعة استخدام مكتبات OpenAI الموجودة، حيث تعمل الواجهة بنفس هيكل الطلبات. يتم إرسال النص والصوت عبر نفس البنية المعروفة، مما يلغي الحاجة إلى كتابة منطق جديد لتحويل البيانات.
يكفي تعديل عنوان الخادم الأساسي (base_url) في إعدادات المكتبة ليشير إلى https://api.k111.info/v1 واستخدام مفتاح API الخاص بالحساب. تعمل الأوامر القياسية مثل إنشاء الكلام مباشرة دون تعديلات جوهرية في الكود.
استخدام SDK الخاص بـ OpenAI
يمكنك استخدام حزم OpenAI الرسمية لأي لغة برمجة تدعمها. بعد ضبط عنوان الأساس، يتم استدعاء نقاط النهاية بنفس الطريقة المألوفة. يتعامل SDK مع الترميز JSON وإدارة الاتصال تلقائياً.
- يدعم جميع لغات OpenAI SDK الشائعة
- لا يحتاج إلى تعديل هيكل الطلبات
تغيير عنوان URL الأساسي
النقطة الوحيدة التي تحتاج إلى تغيير هي عنوان الواجهة الأساسي. قم بتعيينه إلى https://api.k111.info/v1 بدلاً من عنوان OpenAI الافتراضي. هذا يضمن توجيه الطلبات إلى خوادمنا مع الحفاظ على نفس منطق الاتصال.
الاستخدام المباشر عبر HTTP
للحصول على تحكم كامل، يمكن استخدام أي مكتبة HTTP قياسية لإرسال طلبات POST مباشرة. يجب تهيئة رأس المصادقة بمفتاح Bearer الخاص بك. يرسل الخادم استجابة تحتوي على الملف الصوتي أو كائن الخطأ في حال الفشل.
إدارة الأخطاء في التكامل
تتطلب التكاملات السليمة للواجهة البرمجية آلية واضحة للتعامل مع الحالات غير المتوقعة، بدءاً من الأخطاء في صياغة الطلب وصولاً إلى إدارة القيود الزمنية. يعتمد النظام على إرجاع أخطاء واضحة تحدد سبب الفشل، مما يسهل عملية التصحيح دون الحاجة إلى دعم مباشر.
يجب على المطورين ضبط سلوك التطبيق لمعالجة الأخطاء الشائعة مثل تجاوز حد المعدل أو فشل التوليف، مع التأكد من تسجيل الأخطاء بدقة لمراجعة الفواتير والتكاليف لاحقاً.
معالجة أخطاء الصيغة
عند إرسال طلب غير مكتمل أو يحتوي على حقول غير صحيحة، تُرجع الواجهة خطأ تحدد الحقل المعطوب. يجب التحقق من صحة البيانات قبل الإرسال لتجنب الهدر في الطلبات.
تأكد من أن النص لا يتجاوز الحد المسموح به وأن صيغة الصوت مدعومة. الطلبات الفاشلة لا تستهلك رصيدك، مما يسمح بإعادة المحاولة دون تكلفة إضافية.
- التحقق من صحة حقل النص والطول.
- التأكد من صحة معرف الصوت والصيغة المطلوبة.
- إعادة المحاولة عند استجابة خطأ واضح.
التعامل مع حدود المعدل
يتم تحديد حد 60 طلباً في الدقيقة لكل مفتاح. عند تجاوز هذا الحد، قد تتأخر معالجة الطلبات أو تُرفض مؤقتاً. يجب تطبيق آلية إعادة المحاولة مع تأخير عشوائي (Exponential Backoff) للتعامل مع الازدحام.
يبدأ الحد بـ 10 طلبات في الدقيقة قبل أول شحن، ثم يرتفع إلى 60 بعد الشحن. تخطيط الطلبات المسبقة يضمن استقرار التطبيق أثناء فترات الذروة.
- حد 60 طلباً في الدقيقة للمفاتيح المدفوعة.
- حد 10 طلبات في الدقيقة للمفاتيح الجديدة.
- استخدام إعادة المحاولة مع تأخير عند الازدحام.
التحقق من نجاح الطلب
عند نجاح التوليف، تُرجع الواجهة الملف الصوتي مباشرة. يجب التحقق من حالة الاستجابة (HTTP 200) للتأكد من استلام البيانات بنجاح. الطلبات الناجحة تُحاسب فوراً على الرصيد.
في حالة فشل التوليف بسبب خطأ في الخادم أو بيانات الدخول، يُعاد المبلغ كاملاً. يمكن تتبع حالة الطلب عبر سجلات الواجهة ومراجعة الرصيد المتاح لاحقاً.
- التحقق من كود الاستجابة 200.
- مراجعة الرصيد بعد كل طلب ناجح.
- التحقق من استرداد المبالغ في حالة الفشل.
مستقبل الواجهة التقنية
تستند الواجهة التقنية إلى بنية مستقرة تعتمد على نقاط النهاية المحددة في المستندات، مما يضمن اتساق هياكل الطلبات والاستجابة. لا نلتزم بتعهدات SLA أو ضمانات توفر محددة.
تتضمن الخطة المستقبلية دعم الصيغ الصوتية الحالية (MP3, WAV, OPUS, FLAC, PCM) دون إضافة ميزات معقدة مثل SSML أو التكيف العاطفي، والتركيز على تحسين سرعة المعالجة وتقليل زمن الانتظار في الطوابير عند زيادة الحمل.
استقرار النقاط النهائية
تعمل نقاط النهاية /v1/audio/speech و /v1/voices و /v1/models وفق معايير ثابتة ومتوافقة مع واجهات OpenAI المعروفة. هذا يضمن عدم الحاجة لتعديل كود التكامل الأساسي عند النشر في بيئة الإنتاج.
دعم الصيغ الصوتية
نركز على الحفاظ على جودة الصيغ المدعومة حالياً (MP3, WAV, OPUS, FLAC, PCM) وتوافرها لكل صوت ولغة. لا نخطط لإضافة صيغ جديدة أو ميزات متقدمة مثل التحكم في النطق الصوتي أو العواطف.
تحسينات الأداء المستقبلية
مع زيادة عدد الطلبات، نعمل على تحسين كفاءة معالجة الطوابير لضمان سرعة استجابة أقرب للوقت الحقيقي، خاصة للنصوص القصيرة. نحرص على معالجة الطلبات بالتسلسل حسب الأولوية دون إضافة تعقيدات في البنية التحتية.
استمع إلى الأصوات الثمانية
تم إنشاء كل عينة أدناه باستخدام هذه الواجهة البرمجية من نفس الجملة. يتم حفظ بيانات الطلبات الأساسية فقط لأغراض الفوترة، مثل وقت الطلب، عدد الأحرف، وحالة الطلب (نجاح أو فشل).
23 لغة
يمكن لأي صوت التحدث بأي من هذه اللغات.
