المصادقة | توثيق EchoNova

الرابط الأساسي https://api.echonova.ai

تُصادَق كل طلبات API المطورين بمفتاح API يُرسل كرمز Bearer. هذه الصفحة موجهة للمهندس الذي يربط الـ header بالعميل، ولكل من يقرأ 401 أو 403 في الاستجابة.

أرسل المفتاح في header Authorization بالمخطط Bearer:

Authorization: Bearer YOUR_API_KEY

تُقرأ الـ header بصرامة. يجب أن تتحقق القواعد الثلاث كلها، وإلا يُرفض الطلب قبل فحص المفتاح.

القاعدة	التفاصيل
جزءان	القيمة هي المخطط، ثم مسافة واحدة، ثم الرمز. المسافات الزائدة أو الأجزاء الإضافية تفشل الطلب.
المخطط `Bearer`	حساس لحالة الأحرف. تفشل `bearer` و `Token`.
الرمز يبدأ بـ `ek_`	أي بادئة أخرى تفشل، بما في ذلك الرمز الفارغ.

صيغة المفتاح

المفتاح هو النص ek_ متبوعًا بـ 64 حرفًا من base64 الآمن للروابط، أي 67 حرفًا في المجموع. تعرض البوابة السر كاملًا مرة واحدة فقط، عند الإنشاء، وبعدها تعرض أول 8 أحرف فقط. ينتمي المفتاح إلى مساحة العمل التي أُنشئ فيها؛ راجع الرابط الأساسي. لإنشاء مفتاح، راجع احصل على مفتاح API.

أمثلة الكود

curl https://api.echonova.ai/v1/text-to-speech/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.echonova.ai/v1/text-to-speech/voices",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/voices', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
console.log(await response.json());

ما الذي تتحقق منه الواجهة

تُنفَّذ الفحوص بهذا الترتيب على كل طلب. أول فحص يفشل ينهي الطلب.

الترتيب	الفحص	عند الفشل
1	تتبع الـ header القواعد الثلاث أعلاه	`401`
2	يوجد مفتاح بهذا السر	`401`
3	لم يُحذف المفتاح	`401`
4	الحالة للمفتاح مُفعَّلة	`401`
5	لم يُغلق حساب مساحة العمل	`401`
6	لمساحة العمل اشتراك	`403`
7	الاشتراك نشط أو في الفترة التجريبية	`403`
8	يحق للمفتاح استدعاء هذه الخدمة	`403`

يُطبَّق الفحص 8 على المفتاح المقيّد الخدمات فقط. لا تحفظ البوابة مفتاحًا دون خدمة واحدة على الأقل. المفتاح الذي أُنشئ قبل هذا التغيير دون اختيار أي خدمة ما زال يستطيع استدعاء كل الخدمات، لذلك افتحه واختر خدماته. يُفحص المفتاح المقيّد حسب المسار: يحتاج كل مسار /v1/text-to-speech، بما في ذلك قائمة الأصوات، إلى وصول نص إلى كلام، ويحتاج كل مسار /v1/speech-to-text إلى وصول كلام إلى نص، ويحتاج كل مسار /v1/sound-cleaning إلى وصول تنقية الصوت.

يحدّث الطلب الذي يجتاز الفحوص الثمانية كلها تاريخ آخر استخدام للمفتاح في البوابة.

الأخطاء

كل استجابة 401 تحمل الرسالة نفسها، لذلك لا يخبرك الجسم وحده بأي سبب من أسباب 401 الخمسة وقع. تحقق منها بالترتيب.

الحالة	`errorMessage`	السبب	الحل
`401`	`Unauthorized`	لا يوجد header `Authorization`، أو المخطط ليس `Bearer`، أو الرمز لا يبدأ بـ `ek_`.	أرسل `Authorization: Bearer ek_...` كما هو موضح أعلاه.
`401`	`Unauthorized`	لا يطابق الرمز أي مفتاح. السر مكتوب بخطأ، أو ينتمي إلى مساحة عمل أخرى.	قارن أول 8 أحرف بقائمة البوابة. استخدم مفتاحًا من مساحة العمل هذه.
`401`	`Unauthorized`	تم حذف المفتاح.	أنشئ مفتاحًا جديدًا.
`401`	`Unauthorized`	المفتاح معطّل.	فعّله من زر التبديل في صفه ضمن المطورون، مفاتيح واجهة برمجة التطبيقات.
`401`	`Unauthorized`	حساب مالك المفتاح مغلق.	استخدم مفتاحًا من حساب مفتوح.
`403`	`Subscription not found`	مساحة العمل التي يتبع لها المفتاح ليس لها اشتراك.	سجّل الدخول إلى البوابة لتلك المساحة، وتأكد من وجود خطة.
`403`	`Subscription expired or inactive`	الاشتراك في حالة غير نشطة وغير تجريبية.	جدّد الاشتراك، ثم أعد المحاولة.
`403`	`This API key does not have access to Text-to-Speech services`	المفتاح مقيّد، ونص إلى كلام ليس من خدماته.	تعديل المفتاح ومنح نص إلى كلام، أو استخدم مفتاحًا آخر.
`403`	`This API key does not have access to Speech-to-Text services`	المفتاح مقيّد، وكلام إلى نص ليس من خدماته.	تعديل المفتاح ومنح كلام إلى نص، أو استخدم مفتاحًا آخر.
`403`	`This API key does not have access to Sound Cleaning services`	المفتاح مقيّد، وتنقية الصوت ليست من خدماته.	تعديل المفتاح ومنح تنقية الصوت، أو استخدم مفتاحًا آخر.

جسم الخطأ له الشكل نفسه في كل استجابة أخرى:

{
  "data": null,
  "statusCode": 401,
  "success": false,
  "errorMessage": "Unauthorized"
}

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

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

لماذا تحمل كل استجابة 401 الرسالة نفسها؟

تغطي Unauthorized أسباب 401 الخمسة في الجدول. تحقق أولًا من صيغة الـ header، ثم قارن أول 8 أحرف من سرك بقائمة البوابة، ثم تحقق من الحالة للمفتاح.

هل يحصل المفتاح المعطّل على 401 أم 403؟

401. استجابات 403 تخص اشتراك مساحة العمل وخدمات المفتاح، ولا يصل إليها إلا مفتاح مُفعَّل.

هل يمكنني إرسال المفتاح في مكان آخر غير header `Authorization`؟

لا. معامل الاستعلام، أو الكوكي، أو header مخصص يُتجاهل، ويحصل الطلب على 401.

هل يحدّث الطلب المرفوض آخر استخدام؟

لا. يتحرك آخر استخدام فقط عندما يجتاز الطلب الفحوص الثمانية كلها.

Header