الأسئلة الشائعة
ما هو هيكل الطلب؟
يتم إرسال النص عبر طلب POST إلى المسار /v1/audio/speech بصيغة JSON. يجب تضمين الحقل 'input' للنص، و'voice' لتحديد الصوت، و'model' (tts-1 أو tts-1-hd). يمكن تحديد الصيغة الصوتية وسرعة النطق اختياريًا. يجب إرفاق مفتاح API في رأس المصادقة Authorization بصيغة Bearer.
ما هي الصيغ المدعومة؟
الواجهة تدعم خمس صيغ صوتية: mp3، wav، opus، flac، وpcm. يمكنك تحديد الصيغة المطلوبة عبر حقل response_format في جسم الطلب. هذه الصيغ متوافقة مع معظم أنظمة التشغيل وبرامج التشغيل الصوتية القياسية.
كيف أستخدم مكتبة OpenAI؟
يمكنك استخدام مكتبة OpenAI الرسمية لتعديل base_url إلى https://api.ma99.info/v1 واستخدام مفتاح API الخاص بنا. الهيكل مطابق تمامًا لواجهة OpenAI، مما يسهل التكامل. فقط قم بتغيير نقطة النهاية الأساسية في إعدادات SDK، ثم استخدم نفس دالة إنشاء الصوت المعتادة.
ما هو الحد الأقصى للأحرف؟
الحد الأقصى هو 4096 حرفًا لكل طلب، بما في ذلك المسافات والعلامات الترقيية. للنصوص الأطول، يجب تقسيم النص إلى أجزاء لا تتجاوز هذا الحد، ثم دمج الملفات الصوتية الناتجة. هذا يضمن معالجة مستقرة وفعالة للنصوص الطويلة دون تجاوز حدود المعالجة في الواجهة.
ما هو حد الطلبات؟
الحد المسموح به هو 60 طلبًا في الدقيقة لكل مفتاح API. قبل أول إيداع، يكون الحد 10 طلبات في الدقيقة فقط. يتم معالجة الطلبات بالتسلسل، مما قد يؤدي إلى طوابير الانتظار تحت الضغط. تجاوز الحد قد يؤدي إلى رفض الطلبات مؤقتًا حتى يستريح المعدل.
هل هناك دعم لـ SSML؟
لا، الواجهة لا تدعم لغة تحديد نطق النصوص (SSML). لا توجد وسوم للتحكم في التوقف أو النبرة أو سرعة الكلمات الفردية أو القاموس الصوتي المخصص. يتم الاعتماد على النطق التلقائي للنص العادي فقط. إذا كنت بحاجة إلى تحكم دقيق في النطق، يجب تعديل النص المدخل يدويًا أو استخدام أدوات خارجية.
كيف أتعامل مع الأخطاء؟
إذا فشل التوليد، يتم إرجاع المبلغ بالكامل دون خصم. يجب التحقق من أكواد الحالة في الاستجابة ومعالجة الأخطاء الشائعة مثل تجاوز الحد أو صيغة غير صحيحة. الأخطاء لا تكلف، لذا يمكنك إعادة المحاولة بأمان. تأكد من معالجة الاستثناءات في كودك للتعامل مع حالات الفشل.
هل يمكنني تغيير السرعة؟
نعم، يمكنك ضبط سرعة النطق بين 0.25 و4.0 عبر حقل speed. هذا يسمح بتسريع أو إبطاء النطق حسب الحاجة. السرعة تؤثر على مدة الملف الصوت النهائي. يمكن ضبط هذه القيمة لكل طلب على حدة لتناسب احتياجات نظام الإعلان الصوتي.
الطلب الأول
curl
curl https://api.ma99.info/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.ma99.info/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.ma99.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | أنثى |
nova | أنثى |
luna | أنثى |
sage | أنثى |
felix | ذكر |
milo | ذكر |
atlas | ذكر |
orion | ذكر |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
الحصول على مفتاح API
تتيح واجهة Nassim للمطورين الوصول الفوري إلى خدمة تحويل النصوص إلى كلام عبر نظام حسابات مخصص. يجب على فرق المطاعم والفنادق تسجيل حساب جديد من خلال صفحة /get-api-key/ باستخدام حساب Google أو عبر البريد الإلكتروني وكلمة المرور.
يتم إنشاء حساب منفصل لكل موقع (ma99.info)، مما يضمن إدارة واضحة للموارد. بعد اكتمال التسجيل، يصبح المستخدم قادراً على توليد مفتاح الـ API الخاص به، وهو العنصر الأساسي لمصادقة جميع طلبات الواجهة البرمجية.
تسجيل الحساب
يمكنك التسجيل عبر النقر على زر تسجيل الدخول باستخدام حساب Google، أو اختيار إنشاء حساب جديد عبر البريد الإلكتروني وكلمة المرور. يُفضل استخدام البريد الإلكتروني إذا كنت تفضل إدارة الحساب بشكل مستقل عن حسابات جوجل.
يتم إنشاء الحساب فوراً وبدون انتظار موافقة يدوية. إذا سجلت باستخدام البريد الإلكتروني، لن تحصل على رصيد تجريبي أولي، بينما يحصل مستخدمو Google على رصيد تجريب بقيمة 0.50 دولار لمدة 7 أيام.
- التسجيل متاح عبر Google أو البريد الإلكتروني
- الحسابات خاصة بكل موقع (ma99.info)
- الرصيد التجريبي متاح لمستخدمي Google فقط
نسخ المفتاح
بعد تسجيل الدخول، ستظهر صفحة لوحة التحكم التي تحتوي على مفتاح الـ API الخاص بك. يتم عرض المفتاح بتنسيق يبدأ بـ tts- في قسم المصادقة.
يجب نسخ هذا المفتاح ولصقه في حقل Authorization: Bearer عند إجراء الطلبات. هذا المفتاح هو المسؤول الوحيد عن مصادقة طلباتك، ويجب حمايته من الوصول غير المصر به.
- المفتاح يبدأ بـ
tts- - يستخدم في رأس الطلب
Authorization: Bearer - مفتاح واحد نشط لكل حساب
إصدار مفتاح جديد
إذا فقدت مفتاحك أو أردت تجديد الأمان، يمكنك إصدار مفتاح جديد من صفحة لوحة التحكم. عند إصدار مفتاح جديد، يتوقف المفتاح القديم فوراً ولا يمكنه قبول طلبات جديدة.
هذه العملية فورية ولا تتطلب إعادة تسجيل. يُنصح بإصدار مفتاح جديد بعد أي شك في تسريبه لضمان استمرارية عمل خدمات الإعلانات الصوتية في الفروع الكبيرة.
- إصدار فوري للمفتاح الجديد
- إيقاف المفتاح القديم تلقائياً
- لا حاجة لإعادة تسجيل الدخول
نموذج الطلب الأولي
يبدأ التكامل بإرسال طلب POST إلى المسار /v1/audio/speech ببيانات JSON تحتوي على النص والصوت المطلوب. يدعم النظام النموذجين tts-1 وtts-1-hd بنفس المحرك والسعر.
استخدام cURL
يمكنك اختبار الواجهة مباشرة عبر سطر الأوامر. استبدل <YOUR_API_KEY> بالمفتاح الخاص بحسابك في Nassim:
- curl -X POST https://api.ma99.info/v1/audio/speech \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{"model": "tts-1", "input": "مرحباً بكم في مطعمنا الفاخر", "voice": "aria", "response_format": "mp3"}'
هيكل JSON
يجب أن يحتوي جسم الطلب على الحقل input للنص (حتى 4096 حرف)، وvoice لتحديد الصوت، وresponse_format لتحديد الصيغة (mp3 أو wav أو opus أو flac أو pcm). حقل model يقبل tts-1 أو tts-1-hd.
- model: "tts-1" أو "tts-1-hd"
- input: نص التحويل (حتى 4096 حرف)
- voice: أحد الأصوات الثمانية
- response_format: mp3, wav, opus, flac, pcm
المعرفات الصوتية
تتوفر ثمانية أصوات افتراضية للعمل في بيئات المطاعم والفنادق. اختر الصوت المناسب لطبيعة الإعلان أو التوجيه، مثل صوت "sage" للتعليمات الهادئة أو "felix" للإعلانات النشطة.
- aria: راوية دافئة وواضحة
- nova: صوت مشرق وحيوي
- luna: صوت ناعم لسرد القصص
- sage: صوت تعليمي هادئ
- felix: صوت حماسي للإعلانات
- milo: صوت ودود وحواري
استخدام مكتبات OpenAI
تتيح واجهة برمجة تطبيقات Nassim التوافق الكامل مع مكتبات OpenAI الرسمية، مما يسمح لك باستدعاء خدمات تحويل النص إلى كلام باستخدام نفس أدوات SDK المعروفة. يتطلب ذلك تعديل الرابط الأساسي (Base URL) في إعدادات العميل ليشير إلى الخادم الخاص بنا، مع الحفاظ على هيكل الطلبات والمعايير القياسية.
يعمل هذا التكامل على تبسيط عملية الدمج في الأنظمة القائمة، حيث يمكنك استخدام نفس نموذج "tts-1" و "tts-1-hd" المتاح عبر واجهتنا. هذا النهج يضمن سهولة الانتقال وعدم الحاجة لتعلم مكتبات جديدة، مع ضمان عمل الطلبات عبر البروتوكول المعتمد.
تغيير الرابط الأساسي
لتوجيه الطلبات إلى خوادم Nassim، قم بتحديث حقل base_url في تكوين SDK الخاص بك إلى https://api.ma99.info/v1. هذا التغيير هو الإعداد الوحيد اللازم لجعل المكتبة ترسل الطلبات إلى واجهة برمجة التطبيقات الخاصة بنا بدلاً من خوادم OpenAI الافتراضية.
- الرابط الأساسي الجديد:
https://api.ma99.info/v1 - لا حاجة لتغيير هيكل الطلبات أو الحقول
- يدعم الإصدارات الحديثة من SDK
استخدام نفس النموذج
نستخدم نفس أسماء النماذج المعتمدة: tts-1 و tts-1-hd. كلا النموذجين يعملان على نفس محرك الصوت ويحملان نفس السعر، مما يعني أن الكود المكتوب للنموذج الأول سينطبق تماماً على الثاني دون تعديل في المنطق البرمجي.
توافق SDK الرسمي
تعمل مكتبات OpenAI الرسمية (Python, Node.js, etc.) بشكل كامل مع واجهتنا عند ضبط الرابط الأساسي والمفتاح الصحيح، حيث يتطابق شكل الطلب مع واجهة OpenAI. يتم التعامل مع الطلبات استناداً إلى المعايير القياسية المعروفة، مما يضمن استقرار الاتصال وسهولة تصحيح الأخطاء باستخدام الأدوات المعهودة.
الصيغ الصوتية المدعومة
توفر واجهة Nassim مرونة في اختيار صيغة الصوت المولد لتناسب متطلبات أنظمة الإعلان والإرشاد داخل المطاعم والفنادق الكبيرة. تدعم الخوادم خمس صيغ صوتية قياسية عبر حقل response_format في الطلب، مما يضمن توافقاً مباشراً مع مشغلات الوسائط المتعددة وأنظمة البث الداخلي المعتمدة.
MP3 للأغراض العامة
تُعد صيغة MP3 الخيار الأمثل لمعظم حالات الاستخدام التشغيلية، حيث توفر توازناً بين جودة الصوت وحجم الملف الصغير. تُستخدم عادةً في أنظمة الإعلانات الصوتية قصيرة المدى والإرشادات الموجهة للضيوف، مما يسهل تخزينها ونقلها عبر الشبكات الداخلية دون استهلاك عرض نطاق واسع.
WAV للجودة العالية
تقدم صيغة WAV جودة صوت غير مضغوطة، مما يجعلها مناسبة للأنظمة التي تتطلب دقة عالية في إعادة إنتاج الصوت. تُستخدم غالباً في التسجيلات الداخلية أو عند الحاجة إلى معالجة الصوت لاحقاً بواسطة برامج تشغيل متقدمة في أنظمة المطاعم الكبيرة.
OPUS و FLAC و PCM
تدعم الواجهة أيضاً صيغ OPUS و FLAC و PCM لتلبية احتياجات تقنية محددة. تتيح OPUS ضغطاً فعالاً للجودة العالية، بينما توفر FLAC جودة استوديو بدون فقدان البيانات، وPCM تنسيق الخام غير المعالج. توفر هذه الخيارات مرونة للمطورين الذين يتعاملون مع أنظمة صوتية متخصصة أو تحتاج إلى معالجة صوتية متقدمة.
معالجة الأخطاء
تتبع الواجهة معايير HTTP القياسية للإبلاغ عن حالة الطلب. تُرجع الأخطاء الفورية رموز مثل 400 (بيانات غير صالحة) أو 401 (مفتاح غير صالح)، بينما تعكس رموز 5xx مشكلات مؤقتة في الخادم.
تضمن الأخطاء المبلغ عنها استرداد المبلغ بالكامل دون خصم من الرصيد. يتطلب ذلك التحقق من رمز الحالة قبل معالجة الاستجابة أو تحديث واجهة المستخدم.
رموز الحالة
يتم تصنيف الأخطاء ضمن فئتين رئيسيتين: أخطاء العميل التي تتطلب تصحيحاً في الطلب (مثل الحروف الزائدة عن 4096)، وأخطاء الخادم التي قد تتكرر. يجب أن تتعامل الأنظمة الأوتوماتيكية مع هذه الفروق بشكل مختلف لتجنب استهلاك النطاق الترددي دون داع.
- 400 Bad Request: تنسيق JSON غير صحيح أو حقل النص فارغ.
- 401 Unauthorized: مفتاح API منتهي الصلاحية أو غير موجود.
- 429 Too Many Requests: تجاوز حد الـ 60 طلباً في الدقيقة.
- 500/503: أخطاء مؤقتة في خدمة التوليف.
الاستعلام عن الأخطاء
تحتوي استجابة الخطأ على حقل error يحدد سبب الفشل بدقة. في حالة الأخطاء المالية أو التقنية، يتم إرجاع المبلغ المخصص للطلب فوراً إلى رصيد الحساب.
يُنصح بمراجعة السجلات (Logs) الخاصة بالخدمة عند تكرار نفس الخطأ، خاصة إذا كان يتعلق بنفاد الرصيد أو عدم وجود اتصال بالشبكة.
إعادة المحاولة
يُنصح باستخدام استراتيجية إعادة المحاولة ذاتية التكيف (Exponential Backoff) في حالة أخطاء الخادم (5xx). ابدأ بمحاولة بعد ثانية واحدة، ثم ضعف الفترة بين كل محاولة.
تجنب إعادة المحاولة الفورية المتكررة (Spin-loop) لأنها قد تزيد من ازدحام طابور المعالجة، خاصة في أوقات الذروة عندما تكون الأنظمة مشغولة.

الحدود ومحدودية الاستخدام
تخضع الواجهة لقيود صارمة تضمن استقرار الخدمة لفرق العمل الكبيرة. الحد الأقصى هو 60 طلباً في الدقيقة لكل مفتاح API، مع تقييد 10 طلبات في الدقيقة قبل أول إيداع.
يتم معالجة الطلبات بشكل تسلسلي، مما قد يتسبب في تأخير بسيط تحت الضغط. يجب تقسيم النصوص الطويلة يدوياً إلى أجزاء لا تتجاوز 4096 حرفاً لضمان اكتمال التوليد.
60 طلباً في الدقيقة
يتم تحديد سعة الإرسال بناءً على مفتاح الحساب النشط. الحد القياسي هو 60 طلباً في الدقيقة، بينما يبدأ الحساب الجديد بـ 10 طلبات فقط في الدقيقة. يرتفع هذا الحد تلقائياً بعد أول عملية إيداع.
4096 حرفاً لكل طلب
يحتوي الحقل input على حد أقصى قدره 4096 حرفاً، بما في ذلك المسافات وعلامات الترقيم. إذا تجاوز النص هذا الحد، يجب تقسيمه إلى أجزاء متتالية ثم دمج الملفات الصوتية الناتجة.
طابور المعالجة
تتم معالجة الطلبات بترتيب وصولها. في أوقات الذروة، قد ينتظر الطلب في الطابور قبل بدء التوليد. السرعة التقريبية تساوي الوقت الحقيقي للنص (حوالي 25 حرفاً في الثانية) للنصوص الطويلة.
إعدادات الصوت
تتيح لك واجهة برمجة التطبيقات التحكم الدقيق في نبرة الصوت وسرعته ولغته لضمان ملاءمة المحتوى لبيئة المطاعم والفنادق. يمكن تحديد الصوت واللغة في كل طلب على حدة، مما يسهل التكامل مع أنظمة الإعلانات الصوتية الحالية.
اختيار الصوت المناسب
يتوفر ثماني أصوات افتراضية تغطي احتياجات مختلفة، من السرد الواضح إلى اللهجة المريحة. يمكن اختيار الصوت المناسب لكل نوع من المحتوى، مثل الإعلانات أو الإرشادات.
- أصوات نسائية: aria, nova, luna, sage
- أصوات ذكورية: felix, milo, atlas, orion
ضبط السرعة
يمكن تعديل سرعة النطق بين 0.25 و4.0 ضعف السرعة الطبيعية. يُنصح بالسرعات المتوسطة لضمان الوضوح في البيئات الصاخبة.
السرعات الأعلى قد تكون مناسبة للإعلانات السريعة، بينما تناسب السرعات الأقل المحتوى التعليمي أو الإرشادي.
- الحد الأدنى: 0.25x
- الحد الأقصى: 4.0x
تحديد اللغة
يمكن تحديد لغة النص باستخدام رمز ISO اختياريًا. إذا لم يتم تحديدها، يتم تخمين اللغة تلقائيًا من النص المكتوب بالحروف اللاتينية (الإنجليزية افتراضيًا).
يُفضل تحديد اللغة صراحةً للنصوص غير الإنجليزية المكتوبة بالحروف اللاتينية لضمان دقة النطق.
- 23 لغة مدعومة
- تخمين تلقائي عند عدم التحديد
الاستجابة والبيانات
عند نجاح طلب التوليد، تُعاد ملفات الصوت مباشرة في استجابة HTTP بصيغة تتوافق مع الحقل response_format المحدد في الطلب. لا يتم تخزين الملفات الناتجة في الخوادم؛ فالحفاظ عليها يكون مسؤوليتك بعد استلامها عبر واجهة برمجة التطبيقات.
تتضمن الاستجابة بيانات تعريف مثل المعرف الفريد للطلب (request_id) لتتبع الفواتير. لا توجد بيانات صوتية إضافية مُرفقة تُستخدم للتدريب.
استقبال ملف الصوت
يتم إرسال البيانات الصوتية الخام في جسم الاستجابة مباشرة. يمكن لكائنات النظام أو المكتبات البرمجية معالجة هذه البيانات وتخزينها أو تشغيلها فوراً. لا حاجة لخطوة استرجاع منفصلة بعد التحميل.
- لا يتم تخزين الملفات الناتجة في خوادمنا.
- يمكنك تخزين الملفات التي تستلمها في خوادمك الخاصة.
- لا توجد بيانات إضافية تُستخدم لتدريب النماذج.
نموذج البيانات
تتضمن الاستجابة الناجحة معرف الطلب الفريد (request_id) لتتبع الفواتير. يُرجى الاحتفاظ بهذا المعرف لمطابقة طلبات الدفع في لوحة التحكم.
يتم إرجاع الأخطاء بصيغة JSON قياسية تحتوي على error وmessage وcode، مما يسهل معالجتها برمجياً في أنظمة المطاعم والفنادق.
request_id: معرف فريد لتتبع الطلب.error: كود الخطأ في حال الفشل.message: وصف نصي للخطأ.
المعالجة المتسلسلة
يتم معالجة الطلبات بالتسلسل. قد يؤدي الحمل العالي إلى تأخير بسيط في توليد الصوت، خاصة في الجمل القصيرة التي تستغرق بضع ثوانٍ.
السرعة التقريبية هي 25 حرفاً من النص في الثانية الواحدة. لضمان سلاسة الإعلانات الصوتية، يُنصح بإرسال النصوص ضمن حدود الأحرف المسموح بها.
- المعالجة تتم بالتسلسل (Queue).
- السرعة: 25 حرف/ثانية تقريباً.
- قد تحدث تأخيرات بسيطة تحت الحمل.
استمع إلى الأصوات الثمانية
تم إنشاء كل عينة أدناه باستخدام هذه الواجهة البرمجية من نفس الجملة. عند فشل عملية التوليد، يتم إرجاع المبلغ المخصم بالكامل، مما يضمن عدم دفع مقابل خدمات غير مستلمة.
23 لغة
يمكن لأي صوت التحدث بأي من هذه اللغات.
