الأصوات والخيارات في تحويل النص إلى كلام

هذه الصفحة جدول مرجعي لتحويل النص إلى كلام: ما تعيده نقطة نهاية الأصوات، وكيف تختار صوتًا، وما يفعله كل حقل في طلب التوليد. تنطبق على POST /v1/text-to-speech/sync و POST /v1/text-to-speech، وهما تقبلان الجسم نفسه.

نقطة نهاية الأصوات

GET https://api.echonova.ai/v1/text-to-speech/voices

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

{
  "data": {
    "items": [
      {
        "id": "66e5ef3a9c1d2b4f8a7e6c01",
        "name": "ae_ahmed",
        "displayName": "Ahmed",
        "language": "ar",
        "gender": "Male"
      }
    ],
    "total": 1
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}

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"},
)
arabic = [v for v in response.json()["data"]["items"] if v["language"] == "ar"]

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/voices', {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const { data } = await response.json();
const arabic = data.items.filter((v) => v.language === 'ar');

اختيار صوت

صفِّ الأصوات بحسب language في كودك، فالنقطة لا تملك فلاتر. ar يختار الأصوات العربية، و en يختار الإنجليزية.

كائن الصوت لا يتضمن لهجته. اللهجة ثابتة للصوت: ترسل voiceId وحده، ويخرج الصوت بلهجته. لمعرفة لهجة صوت، افتح الأصوات في البوابة. تعرض كل بطاقة اسم الصوت المعروض ولهجته. طابق البطاقة بالـ API عبر displayName، أو عبر name عندما لا يكون للصوت اسم عرض، واستخدم id ذلك الصوت في طلبك.

اللهجات هي egyptian و emirati و saudi و kuwaiti و qatari و omani و lebanese و syrian و iraqi و fusha و american و british، إضافة إلى english وهو اسم قديم. قد يتغير أي اللهجات لها أصوات في وقت بعينه؛ ومصدر الحقيقة هو استدعاء الأصوات. الأصوات الإنجليزية تُبلغ language بقيمة en مهما كانت لهجتها.

مجموعة الأصوات ليست ثابتة. قد يُسحب صوت: يخرج من القائمة، ويحصل أي طلب يسميه على 404 Voice not found. يمكنك تخزين القائمة للراحة، لكن أعِد جلبها عند ظهور هذا الخطأ.

اختر صوتًا مرة واحدة، واحتفظ بقيمة id الخاصة به في إعداداتك، مع طريق للعودة إلى القائمة عندما يتوقف المعرّف عن العمل.

الموصى به

• اجلب القائمة عند بدء التشغيل، واختر بـ displayName و language، واحتفظ بقيمة id في إعداداتك، وأعد الجلب عند 404 Voice not found.

الأقل فاعلية

• استدعِ GET /v1/text-to-speech/voices قبل كل عملية توليد، وخذ أول صوت عربي أيًا كان في ذلك اليوم.

خيارات الطلب

تقبل نقطتا التوليد جسم JSON بهذه الحقول. تُزال المسافات البيضاء من بداية كل سلسلة ونهايتها قبل التحقق. الحقول غير المعروفة مرفوضة.

إذا حذفت speed أو cfg أو numSteps، فهذا يعني «استخدم القيمة الافتراضية»، والمهمة تسجّل القيمة التي استُخدمت فعلًا.

عن tashkeel

• tashkeel يطبَّق على أصوات الفصحى فقط. على صوت من لهجة أخرى يُنطق النص كما كُتب دون حركات، ولا يفشل الاستدعاء.
• tashkeel يسري على POST /v1/text-to-speech/sync فقط. أما POST /v1/text-to-speech فيقبل الحقل وينطق النص كما كُتب. للحصول على كلام مشكول، استخدم النقطة المتزامنة.
• text في المهمة هو النص الذي أرسلته؛ النص المشكول لا يُعاد.

مثال يضم كل الخيارات

curl -X POST https://api.echonova.ai/v1/text-to-speech/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "الطقس اليوم جميل والسماء صافية في المدينة",
    "voiceId": "VOICE_ID",
    "speed": 1,
    "cfg": 2,
    "numSteps": 48,
    "tashkeel": true
  }'

import requests

response = requests.post(
    "https://api.echonova.ai/v1/text-to-speech/sync",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "text": "الطقس اليوم جميل والسماء صافية في المدينة",
        "voiceId": "VOICE_ID",
        "speed": 1,
        "cfg": 2,
        "numSteps": 48,
        "tashkeel": True,
    },
)
print(response.json())

const response = await fetch('https://api.echonova.ai/v1/text-to-speech/sync', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'الطقس اليوم جميل والسماء صافية في المدينة',
    voiceId: 'VOICE_ID',
    speed: 1,
    cfg: 2,
    numSteps: 48,
    tashkeel: true,
  }),
});
console.log(await response.json());

المخرجات

تنتج النقطتان ملف صوت واحدًا لكل استدعاء، وتعرضه كـ audioUrl: في الاستجابة المتزامنة مباشرة، وفي كائن المهمة عندما تصبح المهمة غير المتزامنة completed.

الرصيد

يُحسب سعر الاستدعاء من حقل text قبل بدء المهمة: كل حرف في text، مع المسافات وفواصل الأسطر، بسعر 1 credit لكل حرف. يُخصم من رصيد مساحة العمل قبل التوليد، ويُعاد إذا فشلت المهمة. الأسعار وأمثلة الحساب وحد الرصيد لكل مفتاح موجودة في الرصيد.

الحدود

تشترك النقطتان في حد النص نفسه. الفرق بينهما هو طريقة استلام النتيجة، لا كمية النص التي يقبلانها.

الأخطاء

كل خطأ يستخدم الغلاف المعتاد مع success: false، وتظهر الرسالة في errorMessage. تسرد أخطاء التحقق كل قاعدة فاشلة في رسالة واحدة مفصولة بفواصل.

أخطاء المصادقة، أي 401 و403 الأخرى، مدرجة في المصادقة. أما 429 الخاص بمعدل الطلبات فيرد في حدود معدل الطلبات.

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

كيف أعرف اللهجة التي ينطقها الصوت؟

افتح الأصوات في البوابة؛ تعرض كل بطاقة اللهجة. كائن الصوت في API يحمل language فقط.

لماذا لا يفعل tashkeel شيئًا في مهمتي؟

إما أن الصوت ليس الفصحى، أو أنك استخدمت POST /v1/text-to-speech. تُضاف الحركات عبر POST /v1/text-to-speech/sync مع صوت من الفصحى.

هل أستطيع معاينة صوت عبر API؟

لا. previewUrl غائب عن الاستجابة. عاين الأصوات في البوابة من الأصوات، أو أنشئ جملة قصيرة بـ POST /v1/text-to-speech/sync.

ماذا يغيّر cfg و numSteps؟

كلاهما يضبط التوليد. اتركهما على الافتراضي إلا إذا كنت تقارن المخرجات في تجارب استماع خاصة بك. القيم المقبولة في الجدول أعلاه، وأي قيمة خارجها تُرفض بـ 400.

هل أستطيع الحصول على MP3 أو OGG؟

لا. الصوت بصيغة WAV. حوّله عندك إذا احتجت صيغة أخرى.

صفحات ذات صلة

• توليد الكلام بشكل متزامن
• توليد الكلام من النص
• عرض الأصوات المتاحة
• دليل البدء لتحويل النص إلى كلام
• الرصيد
• الأخطاء
• نظرة عامة على API المطورين