احصل على مفتاح API

يتيح لك مفتاح API أن يستدعي خادمك الخاص واجهة API المطورين نيابةً عن مساحة عملك. تنشئ المفتاح في البوابة، وتنسخ السر مرة واحدة، ثم ترسله رمز Bearer في كل طلب.

ما تحتاجه

• حساب في إيكونوڤا ومساحة عمل. سجّل الدخول عبر /auth/sign-in.
• صلاحية مالك مساحة العمل، وتشمل الإذن developer_api.manage.
• اشتراك نشط أو في الفترة التجريبية على مساحة العمل. ترفض الواجهة المفاتيح من مساحة عمل بلا اشتراك.
• خانة متاحة ضمن حد خطتك للمفاتيح النشطة. تخبرك البوابة عندما تبلغ الحد.

الخطوات

الخطوة 1: افتح تبويب مفاتيح واجهة برمجة التطبيقات

انتقل إلى /developers?tab=api-keys، أو افتح المطورون في البوابة واختر تبويب مفاتيح واجهة برمجة التطبيقات. تظهر هنا المفاتيح التي أنشأتها من قبل.

الخطوة 2: أنشئ المفتاح

اضغط إنشاء مفتاح جديد، ثم املأ النموذج.

اضغط إنشاء.

اجعل كل مفتاح لنظام واحد. عندها يمكن تعطيل مفتاح مُسرَّب دون إيقاف أي شيء آخر، ويذكر استدعاء في سجل الطلبات النظام الذي أجراه.

الموصى به

• billing-service، ووصول على نص إلى كلام (TTS) فقط، وحد الرصيد أعلى قليلًا من استخدامه الشهري المعتاد.

الأقل فاعلية

• main، ووصول على كل الخدمات، دون حد للرصيد، ويشاركه كل نظام تشغّله.

الخطوة 3: احفظ السر

يتحول الحوار إلى تم إنشاء المفتاح بنجاح ويعرض السر تحت المفتاح السري. يبدأ السر بـ ek_. اضغط نسخ لوضعه في الحافظة، أو تنزيل JSON لحفظ ملف يحمل اسم المفتاح ويحتوي السر في secret_key.

الخطوة 4: أرسل طلبًا

أرسل السر رمز Bearer في header Authorization. يعرض هذا الاستدعاء الأصوات التي يستطيع مفتاحك استخدامها:

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());

تعني استجابة 200 مع قائمة الأصوات أن المفتاح يعمل.

ماذا يحدث بعد ذلك

• يظهر المفتاح في القائمة مع الاسم، وأول 8 أحرف من السر، وتاريخ الإنشاء، وآخر استخدام، والحالة.
• يحدّث كل طلب يجتاز المصادقة آخر استخدام.
• استخدم زر التبديل في الصف لتعطيل المفتاح أو تفعيله. يُرفض المفتاح المعطّل حتى تفعّله من جديد.
• افتح قائمة الصف لـ تعديل الاسم وحد الرصيد والخدمات والحالة، أو لـ حذف المفتاح. يطلب الحذف تأكيدًا ولا يمكن التراجع عنه.
• إذا كان للمفتاح حد للرصيد، يبدأ الاستخدام من بداية دورة الفوترة ويُعاد ضبطه عند أول استدعاء يُحتسب عليه رصيد في دورة جديدة؛ راجع الرصيد. عندما يتجاوز الاستخدام 80% من الحد، يُرسل حدث Webhook باسم spending.warning مرة واحدة في كل دورة. وعندما يبلغ الاستخدام الحد، يُرسل spending.exhausted مع كل استدعاء من هذا النوع.
• يُرفض أي استدعاء يتجاوز الحد برمز 429، أيًّا كانت الخدمة التي يخصها. لا يُخصم شيء.

الحدود

استكشاف الأخطاء وإصلاحها

401 Unauthorized

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

403 Subscription expired or inactive

مساحة العمل التي يتبع لها المفتاح ليس لها اشتراك نشط أو في الفترة التجريبية. جدّد الاشتراك، ثم أعد المحاولة.

403 This API key does not have access to Text-to-Speech services

للمفتاح خدمة واحدة على الأقل على وصول، والخدمة التي استدعيتها ليست بينها. الرسالة نفسها موجودة لكلام إلى نص وتنقية الصوت. عدّل المفتاح وامنح وصول للخدمة، أو استخدم مفتاحًا آخر.

429 Monthly spending limit exhausted

كان استدعاء سيتجاوز حد رصيد المفتاح لدورة الفوترة هذه. ارفع الحد من تعديل، أو أفرغه لرصيد غير محدود، أو انتظر الدورة التالية.

تم بلوغ حد مفاتيح API

تعرض البوابة هذا الحوار عندما يستنفد عدد المفاتيح النشطة في خطتك. احذف مفتاحًا لم تعد تستخدمه، أو رقِّ الخطة.

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

هل يمكنني رؤية السر مرة أخرى؟

لا. تعرض البوابة أول 8 أحرف فقط. احذف المفتاح وأنشئ مفتاحًا جديدًا.

هل يعمل مفتاح واحد مع كل مساحات العمل؟

لا. ينتمي المفتاح إلى مساحة العمل التي أُنشئ فيها. راجع الرابط الأساسي.

ماذا يفعل تعطيل المفتاح؟

تحصل الطلبات المرسلة به على 401 حتى تفعّله من جديد. يحتفظ المفتاح باسمه وحد رصيده وخدماته واستخدامه.

ماذا يحدث لحد الرصيد عند تعديله؟

يسري الحد الجديد على الطلب التالي. يبقى الاستخدام المسجل في هذه الدورة محسوبًا.

من يستطيع إنشاء المفاتيح أو حذفها؟

مالك مساحة العمل، الذي يملك دوره الإذن developer_api.manage.

صفحات ذات صلة

• الرابط الأساسي
• المصادقة
• نظرة عامة على API المطورين
• عرض الأصوات المتاحة
• ما هي إيكونوڤا