https://api.echonova.aiالمطورون
نظرة عامة على API المطورين
ما تفعله API المطورين، ونقاط النهاية الخمس عشرة التي تعرضها، وكيف يُصادَق الطلب ويُجاب ويُحتسب.
تتيح لك API المطورين أن تستدعي أنظمتك الخاصة خدمات الكلام في إيكونوڤا عبر HTTPS. تعرض ثلاث خدمات: تحويل النص إلى كلام، الذي يحوّل النص إلى مقطع صوتي يقرؤه صوت من مكتبة الأصوات، وتحويل الكلام إلى نص، الذي يفرّغ ملفًا صوتيًا، وتنقية الصوت، الذي ينقّي تسجيلًا قصيرًا. تستدعيها بمفتاح API تنشئه في البوابة، وتُخصم كل استدعاء بالرصيد من مساحة عملك.
نقاط النهاية
تضم الواجهة خمس عشرة نقطة نهاية، كلها تحت /v1. لكل واحدة صفحة مرجع فيها حقول الطلب، وشكل الاستجابة، وأمثلة الكود.
| الطريقة | المسار | ما تفعله | المرجع |
|---|---|---|---|
POST |
/v1/text-to-speech |
ابدأ مهمة تحويل نص إلى كلام، وأعد معرّفها | توليد الكلام من النص |
POST |
/v1/text-to-speech/sync |
ولّد الكلام وأعد رابط المقطع الصوتي في استدعاء واحد | توليد الكلام بشكل متزامن |
GET |
/v1/text-to-speech/voices |
اعرض الأصوات التي يمكنك استخدامها | عرض الأصوات المتاحة |
GET |
/v1/text-to-speech/jobs |
اعرض مهام API في مساحة العمل لتحويل النص إلى كلام | عرض مهام تحويل النص إلى كلام |
GET |
/v1/text-to-speech/jobs/{jobId} |
اعرض مهمة واحدة لتحويل النص إلى كلام | تفاصيل مهمة TTS |
POST |
/v1/speech-to-text |
ارفع ملفًا صوتيًا، وابدأ مهمة تفريغ، وأعد معرّفها | تفريغ ملف صوتي |
POST |
/v1/speech-to-text/sync |
ارفع ملفًا صوتيًا وأعد التفريغ النصي في استدعاء واحد | تفريغ ملف صوتي بشكل متزامن |
GET |
/v1/speech-to-text/jobs |
اعرض مهام API في مساحة العمل لتحويل الكلام إلى نص | عرض مهام تحويل الكلام إلى نص |
GET |
/v1/speech-to-text/jobs/{jobId} |
اعرض مهمة واحدة لتحويل الكلام إلى نص | تفاصيل مهمة STT |
POST |
/v1/sound-cleaning |
ارفع صوتًا تصل مدته إلى 10 دقائق، وأعد رابط الملف المنقّى | تنقية الصوت |
GET |
/v1/sound-cleaning/jobs |
اعرض مهام API في مساحة العمل لتنقية الصوت | عرض مهام تنقية الصوت |
GET |
/v1/sound-cleaning/jobs/{jobId} |
اعرض مهمة واحدة لتنقية الصوت | تفاصيل مهمة تنقية الصوت |
DELETE |
/v1/text-to-speech/jobs/{jobId} |
احذف مهمة واحدة لتحويل النص إلى كلام وملفها المخزّن | حذف مهمة TTS |
DELETE |
/v1/speech-to-text/jobs/{jobId} |
احذف مهمة واحدة لتحويل الكلام إلى نص وملفها المخزّن | حذف مهمة STT |
DELETE |
/v1/sound-cleaning/jobs/{jobId} |
احذف مهمة واحدة لتنقية الصوت وملفها المخزّن | حذف مهمة تنقية الصوت |
يستطيع أي مفتاح API في مساحة العمل له وصول إلى تلك الخدمة أن يعرض مهامها ويجلبها ويحذفها، حتى المهام التي أنشأها مفتاح حُذف لاحقًا. المفتاح الذي لا وصول له إلى الخدمة يحصل على 403. مهمة من مساحة عمل أخرى، أو مهمة أُنشئت في البوابة، ترد بـ 404. لا تُحذف إلا المهمة المكتملة أو الفاشلة.
الرابط الأساسي والمصادقة
يذهب كل طلب إلى مضيف واحد، وتُظهره الملاحظة في أعلى هذه الصفحة؛ راجع الرابط الأساسي. يرسل كل طلب مفتاح API الخاص بك كرمز Bearer في header Authorization؛ راجع المصادقة.
شكل الاستجابة
كل استجابة، سواء كانت ناجحة أو خطأ، هي كائن JSON واحد بالحقول الأربعة نفسها. تُعيد الاستدعاءات الناجحة الرمز HTTP 200، بما في ذلك استدعاءات POST.
{
"success": true,
"statusCode": 200,
"errorMessage": null,
"data": {}
}عند الخطأ، تكون success بقيمة false، وdata بقيمة null، وstatusCode تطابق حالة HTTP، وتحمل errorMessage نصًا قصيرًا يمكنك تسجيله.
الاستدعاءات المتزامنة وغير المتزامنة
يتوفر لتحويل النص إلى كلام ولتحويل الكلام إلى نص نقطة نهاية متزامنة ونقطة نهاية غير متزامنة. أما تنقية الصوت فمتزامنة فقط. تنتظر نقطة النهاية المتزامنة حتى يكتمل العمل، وتعيد النتيجة في الاستجابة. تعيد نقطة النهاية غير المتزامنة فورًا jobId وstatus؛ تنتقل المهمة عبر pending وprocessing وتنتهي بـ completed أو failed، وتجلب النتيجة من نقطة نهاية المهمة، أو تستلمها عبر webhook. يشرح الاستدعاءات المتزامنة وغير المتزامنة كيف تختار بينهما.
Webhooks
بدلًا من الاستعلام الدوري عن المهمة، يمكنك تسجيل نقطة نهاية HTTPS في البوابة ضمن المطورون، في تبويب خطافات الويب. ترسل إيكونوڤا بعدها طلبًا موقّعًا لأربعة أحداث: job.completed وjob.failed عند انتهاء مهمة، وspending.warning وspending.exhausted عندما يقترب مفتاح من حد الرصيد أو يبلغه. راجع إعداد Webhook للإعداد، والتحقق من توقيع Webhook للفحص الذي يجب أن تُجريه نقطة النهاية لديك.
الأسئلة الشائعة
أي نقطة نهاية أستدعيها أولًا؟
GET /v1/text-to-speech/voices. تحتاج إلى مفتاحك فقط، ولا تُحتسب عليها أي تكلفة، والرمز 200 يثبت أن المفتاح والمضيف صحيحان.
هل تعيد استدعاءات POST الرمز 201؟
لا. كل استدعاء ناجح، بما في ذلك POST، يعيد الرمز HTTP 200 مع success بقيمة true.
هل يستطيع مفتاح أن يرى مهام مفتاح آخر؟
نعم، داخل مساحة عمل واحدة. يستطيع أي مفتاح API في مساحة العمل له وصول إلى تلك الخدمة أن يعرض مهامها ويجلبها ويحذفها، حتى المهام التي أنشأها مفتاح حُذف لاحقًا. المفتاح الذي لا وصول له إلى الخدمة يحصل على 403. حدود المعدل وحدود الرصيد تبقى لكل مفتاح على حدة.
هل API المطورين هي نفسها البوابة؟
الخدمات الكلامية نفسها. تضيف البوابة «صفحة المكتبة» والوكلاء، وهذان غير موجودين في الواجهة.
صفحات ذات صلة
اقرأ هذه الصفحات بالترتيب التالي: