المساعدة

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

الأسئلة التي يطرحها المطورون قبل أن يفتحوا صفحات API المطورين، من المفاتيح والعناوين الأساسية إلى المهام و Webhooks وحدود المعدل والأرصدة والأخطاء.

كيف أحصل على مفتاح API؟

افتح المطورون في البوابة، واختر تبويب مفاتيح واجهة برمجة التطبيقات، ثم اختر إنشاء مفتاح جديد. تحتاج مساحة العمل إلى اشتراك نشط أو فترة تجريبية. يبدأ السر بـ ek_ ويُعرض مرة واحدة، لذا استخدم نسخ أو تنزيل JSON قبل أن تغلق النافذة. بعد ذلك تعرض البوابة أول 8 أحرف فقط، وفقدان السر يعني حذف المفتاح وإنشاء مفتاح جديد. انظر احصل على مفتاح API.

كيف أرسل المفتاح مع الطلب؟

في header Authorization بالمخطط Bearer، هكذا: Authorization: Bearer YOUR_API_KEY. تُقرأ الترويسة بصرامة: Bearer حساسة لحالة الأحرف، ويجب أن يبدأ الرمز بـ ek_. والمفتاح المرسل كمعامل استعلام، أو ككوكي، أو في header آخر يُتجاهل، فيحصل الطلب على 401. انظر المصادقة.

أي عنوان أساسي أستدعيه؟

كل طلب يذهب إلى مضيف واحد، والملاحظة في أعلى كل صفحة من صفحات المطورين تعرضه. يعمل المفتاح لمساحة العمل التي يملكها فقط، ولا تعبر المفاتيح والمهام و Webhooks وسجلات الطلبات بين مساحات العمل. انظر الرابط الأساسي.

لماذا أحصل على 401 Unauthorized؟

كل 401 يحمل الرسالة نفسها، لذا راجع الأسباب الخمسة بالترتيب: header Authorization مفقود، أو لا يتبعه Bearer ثم رمز يبدأ بـ ek_؛ أو لا يطابق أي مفتاح الرمز لأنه كُتب بشكل خاطئ أو أنه غير معروف؛ أو حُذف المفتاح؛ أو عُطّل؛ أو أن الحساب الذي يملك المفتاح مغلق. قارن أول 8 أحرف بالقائمة تحت مفاتيح واجهة برمجة التطبيقات، وتحقق من الحالة للمفتاح. انظر المصادقة.

ما الواجهات التي يملكها API؟

خمس عشرة نقطة نهاية، كلها تحت /v1، وهو الإصدار الوحيد. يملك تحويل النص إلى كلام: التوليد المتزامن، وبدء مهمة، وسرد الأصوات، وسرد المهام، والحصول على مهمة، وحذف مهمة. ويملك تحويل الكلام إلى نص: التفريغ المتزامن، وبدء مهمة، وسرد المهام، والحصول على مهمة، وحذف مهمة. وتنقية الصوت: تنقية المقطع الصوتي، وسرد المهام، والحصول على مهمة، وحذف مهمة. كل استجابة كائن JSON واحد فيه success وstatusCode وerrorMessage وdata، والاستدعاء الناجح يعيد HTTP 200 حتى مع POST. ويستطيع أي مفتاح في مساحة العمل له وصول إلى منتج أن يسرد مهام API الخاصة بذلك المنتج ويحصل عليها ويحذفها، أيًّا كان المفتاح الذي أنشأها. أما صفحة المكتبة والوكلاء فهما في البوابة. انظر نظرة عامة على API المطورين.

كيف أولّد كلامًا؟

استدعِ GET /v1/text-to-speech/voices، واحتفظ بـ id الصوت الذي تريده، ثم أرسل text وvoiceId إلى POST /v1/text-to-speech/sync لتحصل على رابط الصوت في الاستجابة نفسها، أو إلى POST /v1/text-to-speech لتحصل على معرّف المهمة. الحقول speed وcfg وnumSteps وtashkeel اختيارية، وtext يقبل من 1 إلى 500 حرف في النقطتين، وaudioUrl رابط موقّع لملف WAV ينتهي صلاحيته، لذا نزّل الملف فور وصوله. انظر دليل البدء لتحويل النص إلى كلام.

كيف أحوّل الصوت إلى نص؟

أرسل الملف كجزء file في طلب multipart/form-data إلى POST /v1/speech-to-text/sync أو إلى POST /v1/speech-to-text، للصوت حتى 10 دقائق. وكلاهما يقبل 150 ميجابايت كحد أقصى، ويجب أن يبدأ Content-Type للجزء بـ audio/ وتحدده أنت، لأن امتداد الملف لا يُقرأ. والنص الناتج سلسلة واحدة مع durationSeconds. أرسل identify_speakers=true لتحصل أيضًا على النص في مقاطع موقّتة، لكل منها متحدثه، ونزّل أي مهمة مكتملة بصيغة TXT أو ترجمة SRT أو JSON من GET /v1/speech-to-text/jobs/{jobId}/export. لا توجد طوابع زمنية للكلمات. يقبل الحقل الاختياري language القيم auto أو ar أو en. يترك auto القرار للخدمة، وهي تعمل بالعربية اليوم، وتتعامل أيضًا مع الكلام الإنجليزي النظيف والمختلط. استخدم ar للعربية وللمختلط بين العربية والإنجليزية. واستخدم en للكلام الإنجليزي وحده، لأن العربية المرسلة بـ en تعود مشوّهة. انظر دليل البدء لتحويل الكلام إلى نص.

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

المتزامنة حين ينتظر شخص النتيجة في الطلب نفسه، ويكون الإدخال ضمن الحد المتزامن. وغير المتزامنة للدفعات، أو للعملاء ذوي مهلة HTTP قصيرة، أو حين تريد أن يخبرك Webhook بانتهاء المهمة. تكلّف الطريقتان الأرصدة نفسها للإدخال نفسه، وتشترك نقطتا تحويل النص إلى كلام في حد 500 حرف، فطول النص لا يفرض الاختيار أبدًا. انظر الاستدعاء المتزامن وغير المتزامن.

كيف أعرف أن المهمة غير المتزامنة انتهت؟

استعلم دوريًا عن GET /v1/text-to-speech/jobs/{jobId} أو GET /v1/speech-to-text/jobs/{jobId} كل بضع ثوانٍ، حتى يصبح status بقيمة completed أو failed. أو سجّل Webhook واستقبل job.completed ومعه النتيجة بداخله. المهمة التي تبقى processing لأكثر من 10 دقائق تُعلَّم failed خلال 15 دقيقة من POST، ويُسترد رصيدها، ولا يرسل هذا الفشل أي Webhook. لذا استعلم عن المهمة مرة واحدة إذا لم يصلك أي حدث بعد 15 دقيقة. انظر الاستدعاء المتزامن وغير المتزامن.

كيف أُعدّ Webhook؟

افتح المطورون، واختر تبويب خطافات الويب، ثم اختر إنشاء Webhook، وأعطه اسمًا، ورابط نقطة نهاية (يُنصح بـ HTTPS)، وواحدًا على الأقل من اكتمل الطلب وفشل الطلب وتنبيه الرصيد ونفد الرصيد. يبدأ سر التوقيع بـ whsec_ ويظهر مرة واحدة في نافذة إضافة نقطة النهاية فور أن تختار إنشاء، مع زر نسخ. انسخه واحفظه. لا يمكن عرضه مرة أخرى، وبعد ذلك لا يظهر إلا أول 12 حرفًا منه. انظر إعداد Webhook.

كيف أتحقق من توقيع Webhook؟

خذ جسم الطلب الخام كبايتات، واربط X-Webhook-Timestamp ونقطة والجسم، واحسب HMAC-SHA256 على هذا النص بالسر الكامل الذي يبدأ بـ whsec_. ثم قارن النتيجة السداسية العشرية بحروف صغيرة مع X-Webhook-Signature بمقارنة بزمن ثابت. ارفض طابعًا زمنيًا يبعد أكثر من 300 ثانية عن ساعتك، وهي النافذة المنصوح بها، وأجب بـ 2xx خلال 10 ثوانٍ، ثم عالج الحدث بعد ذلك. انظر التحقق من توقيع Webhook.

لماذا وصل نقطة النهاية الحدث نفسه مرتين، أو أوقف Webhook نفسه؟

يحصل التسليم على 3 محاولات، تفصل بين الأولى والثانية 5 ثوانٍ، وبين الثانية والثالثة 10 ثوانٍ. وأي استجابة غير 2xx خلال 10 ثوانٍ تُحسب فشلًا، فالمعالج البطيء يُعاد إرسال الحدث إليه فيراه مرة أخرى. لذا أزل التكرار بالاعتماد على jobId مع header X-Webhook-Event، وأجب أولًا ثم عالج. وعند فشل 5 تسليمات متتالية بعد كل محاولاتها، يُعطَّل Webhook وتعرض البوابة معطّل؛ أصلح نقطة النهاية ثم فعّله من جديد. والأحداث التي وقعت أثناء تعطيله لا تُعاد. انظر التسليم والمحاولات والإخفاقات.

ما حدود المعدل؟

100 طلب كل 60 ثانية، تُحسب لمفتاح واحد على نقطة نهاية واحدة. لكل مفتاح عدّ منفصل، واستدعاءات مفتاح واحد لنقطة نهاية لا تُحسب على استدعاءاته لنقطة أخرى. كل استعلام دوري يُحسب. وإذا تجاوز المفتاح الحد رفضته نقطة النهاية لمدة 60 ثانية، بالرمز 429 وThrottlerException: Too Many Requests وترويسة Retry-After، لذا انتظر بقدر تلك الثواني قبل أن تعيد المحاولة. انظر حدود المعدل.

كم تكلّف استدعاءات API؟

يكلّف تحويل النص إلى كلام 1 credit لكل حرف من text، بما فيها المسافات. ويكلّف تحويل الكلام إلى نص 100 credits لكل دقيقة من الصوت، تُحتسب بالثانية. يُخصم كل مبلغ قبل تشغيل العمل، ويُسترد إذا فشلت المهمة. والحقل creditsConsumed في كل مهمة هو المبلغ الذي خُصم، وهو عدد صحيح من الأرصدة. وطلبات GET لا تكلّف شيئًا. انظر الأرصدة.

ماذا يفعل حد الرصيد على المفتاح؟

يحدد كم رصيدًا يحق لذلك المفتاح أن ينفقه في كل دورة فوترة، ولا يضيف أرصدة ولا يغيّر الأسعار. يُرفض استدعاء تحويل النص إلى كلام الذي يتجاوز الحد بالرمز 429 وMonthly spending limit exhausted دون ترويسة Retry-After. أما استدعاء تحويل الكلام إلى نص فيعمل دائمًا ويُحسب بعد ذلك. ويرسل المفتاح الذي له حد أيضًا spending.warning مرة واحدة في كل دورة عند 80%، وspending.exhausted في كل استدعاء عند الحد أو بعده. انظر الأرصدة.

كيف يبدو الخطأ، وأيها أستطيع إعادة المحاولة له؟

الخطأ هو الغلاف نفسه، مع success بقيمة false، وdata بقيمة null، والسبب في errorMessage. ولا يُحتسب أي طلب ينتهي بخطأ. أعد المحاولة فقط مع 429 للحد بعد ثوانٍ Retry-After، ومع الاستجابتين 503 و504، مع تأخير متزايد. أما 400 و401 و402 و403 و404 فتعيد الإجابة نفسها حتى تغيّر الطلب أو المفتاح أو الرصيد. ولا تضع POST أبدًا خلف إعادة محاولة تلقائية، لأن كل POST ينشئ مهمة جديدة وخصمًا جديدًا. انظر الأخطاء وأعد الطلبات بأمان.

أين أجد أمثلة الكود؟

كل صفحة من صفحات المطورين تعرض طلبها بصيغ cURL و Python و Node. وصفحة أمثلة الكود فيها برنامجان كاملان لكل لغة: مهمة تحويل نص إلى كلام غير متزامنة، من الطلب حتى ملف الصوت المحفوظ، ومهمة تحويل كلام إلى نص غير متزامنة، من الرفع حتى النص المفرّغ. يعمل كل واحد منهما بتعديل واحد فقط، هو مفتاح API الخاص بك.

أين تظهر مهام API في البوابة؟

في تبويب سجل الطلبات تحت المطورون، الذي يعرض آخر 50 طلبًا أُرسل بمفتاح معروف، بأي أسلوب وبأي حالة، مع حالته وأسلوبه ومساره واسم مفتاحه ووقته. أما الطلبات المرفوضة بـ 401 (مفتاح مفقود أو غير صالح)، وحد المعدل 429 لكل عنوان IP، و429 الخاص بالمفتاح بعد الأول في نافذة الحد نفسها، والجسم الأكبر من 100 كيلوبايت (413)، والجسم الذي ليس JSON صالحًا (400)، فلا تُسجَّل. والمهام التي أُنشئت بمفتاح API لا تظهر في صفحة المكتبة ولا في السجل. اقرأها من GET /v1/text-to-speech/jobs وGET /v1/speech-to-text/jobs وGET /v1/sound-cleaning/jobs، فهي تعيد مهام API لمساحة العمل كلها، أيًّا كان المفتاح الذي أنشأها. انظر اقرأ سجل الطلبات.