التوثيق
المطورون
مفاتيح API، والمصادقة، والمهام، وWebhook، وأمثلة الشيفرة.
ابدأ
- نظرة عامة على API المطورينما تفعله API المطورين، ونقاط النهاية الخمس عشرة التي تعرضها، وكيف يُصادَق الطلب ويُجاب ويُحتسب.
- الرابط الأساسيالمضيف الواحد الذي تصله كل طلبات Developer API، وكيف تُرقَّم المسارات، ومساحة العمل التي ينتمي إليها مفتاح API.
- احصل على مفتاح APIأنشئ مفتاحًا في البوابة، واحفظ السر مرة واحدة، وأرسل أول طلب موثّق.
- المصادقةheader `Authorization`، وصيغة مفتاح API، والفحوص التي يمر بها كل طلب، وكل خطأ مصادقة مع سببه وطريقة إصلاحه.
- حدود معدل الطلباتكم طلبًا يستطيع مفتاح API واحد أن يرسله في الدقيقة، وheaders التي تُبلغ بالعدد، وشكل استجابة 429، وكيف تتراجع بأمان.
- الرصيدكم تكلّف كل خدمة من الرصيد، وكيف يتحول استخدام الذكاء الاصطناعي إلى رصيد، وأمثلة محسوبة، وكيف يُطبَّق حد رصيد المفتاح.
- الاستدعاءات المتزامنة وغير المتزامنةأي أسلوب استدعاء يناسب الطلب، وكيف تمر المهمة بحالاتها الأربع، وكيف تستعلم عن النتيجة دوريًا.
- أعد المحاولة بأمانميّز بين إعادة محاولة لا تكلّفك شيئًا وأخرى تنشئ مهمة ثانية، واحتفظ بمعرّف المهمة حتى لا تضطر إلى إرسال طلب مرتين، وتراجع بالشكل الصحيح عند الاستجابتين 429 و5xx.
- أمثلة الكودبرنامجان كاملان لكل لغة، الأول لمهمة تحويل نص إلى كلام غير متزامنة من الطلب حتى ملف صوتي محفوظ، والثاني لمهمة تحويل كلام إلى نص غير متزامنة من الرفع حتى النص المفرّغ، مع الغلاف الاستجابي الذي تقرؤه كلها.
- ربط إيكونوڤا بـ Claudeأضف إيكونوڤا موصلًا في Claude، واعرف ما تفعله كل أداة، ومن يستطيع الربط، وكيف تفصل الربط، وكيف تُعالَج بياناتك.
نص إلى كلام
- دليل البدء لتحويل النص إلى كلاماعرض قائمة الأصوات، وحوّل جملة عربية واحدة إلى مقطع صوتي عبر نقطة النهاية المتزامنة، ثم احفظ الملف، وشغّل الطلب نفسه كمهمة غير متزامنة واستعلم عنها دوريًا حتى تكتمل.
- الأصوات والخيارات في تحويل النص إلى كلامقائمة الأصوات، وما يعنيه كل حقل فيها، وكيف تختار صوتًا حسب اللغة، وكل خيار في الطلب مع نوعه ومداه وقيمته الافتراضية وأثره.
- POSTإنشاء كلام من نصتبدأ مهمة تحويل نص إلى كلام لنص من 1 إلى 500 حرف، وتعيد `jobId` الخاص بها. احصل على المقطع الصوتي من `GET /v1/text-to-speech/jobs/{jobId}`، أو من حدث `job.completed` في Webhook. الأصوات المستنسخة تعمل مع نقطة النهاية المتزامنة فقط.
- POSTإنشاء الكلام بشكل متزامن (يعيد رابط المقطع الصوتي في طلب واحد، بحد أقصى 500 حرف)تُنشئ كلامًا لنص من 1 إلى 500 حرف في طلب واحد، وتعيد رابط المقطع الصوتي مع الرصيد المخصوم.
- GETعرض الأصوات المتاحةتعرض مكتبة الأصوات في إيكونوڤا. أرسل معرّف الصوت في الحقل `voiceId` عند إنشاء الكلام.
- GETعرض مهام تحويل النص إلى كلامتعرض مهام API في مساحة عمل هذا المفتاح، مقسّمة إلى صفحات باستخدام `offset` و`limit`. يحتاج المفتاح إلى وصول إلى تحويل النص إلى كلام.
- GETتفاصيل مهمة تحويل النص إلى كلامتعيد مهمة API واحدة في مساحة عمل هذا المفتاح، مع رابط مقطعها الصوتي بعد اكتمالها، أيًا كان المفتاح الذي أنشأها. المهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تحويل النص إلى كلام.
- DELETEحذف مهمة تحويل نص إلى كلام منتهية ومقطعها الصوتيتحذف مهمة API مكتملة أو فاشلة في مساحة عمل هذا المفتاح، مع مقطعها الصوتي، أيًا كان المفتاح الذي أنشأها. المهمة التي لا تزال قيد التنفيذ تُرجع الرمز `400`، والمهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تحويل النص إلى كلام.
كلام إلى نص
- دليل البدء السريع لتحويل الكلام إلى نصانسخ ملفًا صوتيًا قصيرًا في استدعاء واحد، واقرأ النص المفرّغ ومدته، وشغّل ملفًا طويلًا كمهمة غير متزامنة واستعلم عنها دوريًا حتى تنتهي، ثم نزّله كترجمة بتسميات المتحدثين.
- صيغ تحويل الكلام إلى نص ومخرجاتهما تقبله نقطتا الرفع، والفحوصات التي تعمل قبل بدء المهمة، وكل حقل تحمله الاستجابات، وتحديد المتحدثين، وتنزيلات TXT وSRT وJSON، ومعنى durationSeconds.
- POSTتحويل ملف صوتي إلى نصتبدأ مهمة تحويل الكلام إلى نص لملف صوتي مرفوع حتى 10 دقائق و150 ميجابايت، وتعيد `jobId` الخاص بها. احصل على النص المفرّغ من `GET /v1/speech-to-text/jobs/{jobId}`، أو من حدث `job.completed` في Webhook.
- POSTتحويل الصوت إلى نص بشكل متزامن (يعيد النص المفرّغ في طلب واحد، حتى 10 دقائق)تحوّل ملفًا صوتيًا مرفوعًا حتى 10 دقائق و150 ميجابايت إلى نص في طلب واحد، وتعيد النص المفرّغ مع الرصيد المخصوم.
- GETعرض مهام تحويل الكلام إلى نصتعرض مهام API في مساحة عمل هذا المفتاح، مقسّمة إلى صفحات باستخدام `offset` و`limit`. يحتاج المفتاح إلى وصول إلى تحويل الكلام إلى نص.
- GETتفاصيل مهمة تحويل الكلام إلى نصتعيد مهمة API واحدة في مساحة عمل هذا المفتاح، مع نصها المفرّغ بعد اكتمالها، أيًا كان المفتاح الذي أنشأها. المهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تحويل الكلام إلى نص.
- DELETEحذف مهمة تحويل الكلام إلى نص منتهية ومقطعها الصوتيتحذف مهمة API مكتملة أو فاشلة في مساحة عمل هذا المفتاح، مع مقطعها الصوتي، أيًا كان المفتاح الذي أنشأها. المهمة التي لا تزال قيد التنفيذ تُرجع الرمز `400`، والمهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تحويل الكلام إلى نص.
- GETتنزيل مهمة مكتملة لتحويل الكلام إلى نص بصيغة TXT أو SRT أو JSONتعيد النص المفرّغ لمهمة API مكتملة في مساحة عمل هذا المفتاح في ملف: `txt` هو النص المفرّغ، و`srt` ترجمة لا يتجاوز كل مقطع منها 7 ثوانٍ وسطرين من 42 حرفًا، ويبدأ كل مقطع بتسمية متحدثه حين حُدّد المتحدثون، و`json` يحمل النص والمتحدثين والمقاطع الموقّتة. يحدد `lang` لغة تسميات المتحدثين. المهمة التي لم تكتمل تُرجع `400`، والمهمة التابعة لمساحة عمل أخرى تُرجع `404`. يحتاج المفتاح إلى وصول إلى تحويل الكلام إلى نص.
تنقية الصوت
- دليل البدء لتنقية الصوتنظّف تسجيلًا يصل إلى 10 دقائق في استدعاء واحد، واقرأ رابط الملف المنقّى وتكلفته، واضبط أداة التنقية، ثم اعرض مهامك السابقة.
- POSTتنقية الصوت بشكل متزامن (يعيد رابط الملف المنقّى في طلب واحد، حتى 10 دقائق و150 ميجابايت)تنقّي ملفًا مرفوعًا بصيغة MP3 أو WAV أو FLAC أو OGG/Opus، حتى 10 دقائق و150 ميجابايت، في طلب واحد، وتعيد المهمة مع رابط الملف المنقّى. حقول الضبط كلها اختيارية، والحقل المحذوف يأخذ قيمته الافتراضية.
- GETعرض مهام تنقية الصوتتعرض مهام API في مساحة عمل هذا المفتاح، مقسّمة إلى صفحات باستخدام `offset` و`limit`. يحتاج المفتاح إلى وصول إلى تنقية الصوت.
- GETتفاصيل مهمة تنقية الصوتتعيد مهمة API واحدة في مساحة عمل هذا المفتاح، مع رابط ملفها المنقّى، أيًا كان المفتاح الذي أنشأها. المهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تنقية الصوت.
- DELETEحذف مهمة تنقية صوت منتهية ومقطعها الصوتيتحذف مهمة API منتهية في مساحة عمل هذا المفتاح، مع ملفيها الأصلي والمنقّى، أيًا كان المفتاح الذي أنشأها. المهمة التابعة لمساحة عمل أخرى تُرجع الرمز `404`. يحتاج المفتاح إلى وصول إلى تنقية الصوت.
خطافات الويب
- إعداد Webhookأنشئ نقطة نهاية Webhook في البوابة، واختر الأحداث التي تستقبلها، واحتفظ بسر التوقيع، ثم عطّلها أو احذفها لاحقًا.
- أحداث Webhookالأحداث الأربعة التي ترسلها إيكونوڤا، و headers في كل تسليم، والجسم JSON الدقيق لكل حدث.
- التحقق من توقيع Webhookأعد حساب توقيع HMAC-SHA256 في كل تسليم، وقارنه في وقت ثابت، وارفض الطلبات القديمة أو غير الموقعة.
- التسليم وإعادة المحاولة والفشلما الذي يُحتسب تسليمًا ناجحًا، وجدول إعادة المحاولة، وقيم حالة التسليم، ومتى يُعطَّل Webhook، وكيف تتعامل مع التكرار.
العمليات
- قراءة نشاط API الخاص بكافتح صفحة النشاط في المطورون، واقرأ تبويبات نظرة عامة والاتجاهات والاستكشاف والسجلات، واعرف بالضبط أي الطلبات والرصيد تحسبهما الصفحة.
- قراءة سجل الطلباتافتح تبويب سجل الطلبات، واقرأ معنى كل عمود، واعثر على الاستدعاء الذي أرسله نظامك، واعرف الطلبات التي لا تُسجَّل أبدًا.
- الأخطاءكل حالة HTTP وكل errorMessage تعيدها واجهة API الإصدار v1، ومتى يحدث كل منها، وما الذي تفعله حياله، وكيف تبلغ المهام غير المتزامنة عن فشلها.
- أفضل الممارسات لزمن الاستجابةكيف تحصل على النتائج أسرع وتضيّع طلبات أقل، باستخدام نقاط النهاية المتزامنة وغير المتزامنة، وحد المعدل، ومهلة المهمة، وWebhooks كما تعمل فعلًا.
- أفضل الممارسات للأمانكيف تمنع تسرّب مفتاح API، وتحدّ مما يستطيع المفتاح المتسرّب فعله، وتستبدل المفتاح بأمان، ولا تثق إلا بـ Webhooks الحقيقية، وتدقّق ما فعلته مفاتيحك.