الأسئلة الشائعة
كيف أحصل على مفتاح API؟
سجّل حسابك عبر صفحة /get-api-key/ باستخدام حساب Google أو البريد الإلكتروني. سيظهر مفتاح الوصول مباشرة في لوحة التحكم. يمكنك إصدار مفتاح جديد في أي وقت، حيث يتوقف المفتاح القديم فوراً. لا توجد خطط شهرية أو رسوم اشتراك، فقط رصيد مستهلك حسب الاستخدام الفعلي.
ما هي صيغ الصوت المدعومة؟
تدعم واجهة برمجة التطبيقات خمس صيغ صوتية: mp3، wav، opus، flac، و pcm. يمكنك تحديد الصيغة المطلوبة عبر حقل response_format في طلبك. اختر mp3 أو opus للتوفير في الحجم، أو wav و flac لجودة عالية غير مضغوطة حسب احتياجات تطبيقك الطبي.
هل يدعم OpenAI SDK؟
نعم، تعمل الواجهة بنفس شكل طلبات OpenAI. يمكنك استخدام مكتبات OpenAI SDK الرسمية عن طريق تغيير base_url إلى https://api.getjl3.com/v1 واستخدام مفتاحك الخاص. هذا يسهل التكامل السريع مع تطبيقاتك الحالية دون الحاجة لتعلم بروتوكولات جديدة أو كتابة كود اتصال معقد.
ما هو الحد الأقصى لطول النص؟
الحد الأقصى هو 4096 حرفاً في كل طلب، بما في ذلك المسافات وعلامات الترقيم. للنصوص الأطول، قم بتقسيم النص إلى أجزاء أصغر واستدعي الواجهة عدة مرات، ثم ادمج الملفات الصوتية الناتجة. هذا يضمن معالجة دقيقة لكل جزء دون تجاوز حدود الذاكرة أو وقت المعالجة.
كيف أحدد اللغة؟
حدد اللغة باستخدام رمز ISO في حقل language. إذا لم تحددها، سيتم تخمينها تلقائياً بناءً على النص (اللاتيني يُفترض أنه إنجليزي). لدعم اللغة العربية بدقة، حدد الرمز 'ar' لضمان نطق صحيح، خاصة إذا كان النص يحتوي على مصطلحات طبية متخصصة قد تختلف نطقها افتراضياً.
ما هي سرعة الصوت الممكنة؟
يمكنك ضبط سرعة القراءة بين 0.25 و 4.0. القيمة الافتراضية 1.0 تعني السرعة الطبيعية. هذه المرونة مفيدة لتوجيه المرضى كبار السن أو تسريع المحتوى التعليمي. السرعة لا تؤثر على جودة الصوت الأساسي، بل على معدل نطق الحروف والكلمات في الملف النهائي.
هل يمكنني استخدام عدة مفاتيح؟
لا، يوجد مفتاح نشط واحد فقط لكل حساب. يمكنك إصدار مفتاح جديد في أي وقت، مما يوقف المفتاح القديم فوراً. هذا مفيد لتوزيع الحمل بين فرق العمل المختلفة أو عزل التطبيقات عن بعضها. يمكنك إصدار مفتاح جديد في أي وقت، مما يلغي صلاحية المفتاح القديم فوراً.
ماذا يحدث عند تجاوز الحد؟
يتم رفض الطلبات الزائدة عن 60 طلباً في الدقيقة لكل مفتاح. ستحتاج إلى الانتظار حتى ينتهي الوقت المحدد أو استخدام مفتاح آخر. إذا لم يكن لديك رصيد كافٍ، سيتم رفض الطلب. لا توجد غرامات فورية، فقط توقف الخدمة حتى يتوفر الرصيد أو ينتهي وقت الحد.
كيف أعرف حالة الطلب؟
يعيد الـ API استجابة فورية تحتوي على حالة الطلب. إذا نجح، ستحصل على رابط التحميل أو البيانات الثنائية للصوت. إذا فشل، ستصلك رسالة خطأ مع سبب الرفض (مثل عدم وجود رصيد أو خطأ في النموذج). الطلبات الفاشلة لا تستهلك رصيدك وتُسترد بالكامل.
هل البيانات مشفرة؟
يتم استخدام بروتوكول HTTPS لنقل البيانات بين خادومك وخادمنا، مما يضمن تشفير النص والصوت أثناء النقل. النص المدخل يُستخدم فقط لتوليد الصوت ولا يُستخدم للتدريب. البيانات الوصفية (الوقت، الأحرف) تُحفظ للفوترة فقط. لا نحتفظ بالنص أو الصوت النهائي بعد التسليم مباشرة.
ما هو الفرق بين tts-1 و tts-1-hd؟
كلاهما يستخدمان نفس محرك الصوت ونفس السعر ($10 لكل مليون حرف). لا يوجد فرق في الجودة أو المحرك، كلاهما يستخدم نفس المحرك ونفس السعر. اختر النموذج المناسب حسب جودة الصوت المطلوبة لتطبيقاتك الطبية، مع العلم أن التكلفة متطابقة لكلا الخيارين.
كيف أدمج مع تطبيق React؟
استخدم مكتبة openai أو axios لإرسال طلب POST إلى https://api.getjl3.com/v1/audio/speech. مرر النص والصوت المطلوب كـ JSON. استلم الملف الصوتي من الاستجابة. تأكد من إرسال مفتاح API في رأس Authorization. يمكنك تخزين الملف مؤقتاً في الذاكرة أو عرضه مباشرة للمستخدم.
هل هناك رسوم إضافية؟
لا توجد رسوم إضافية. السعر ثابت $10 لكل مليون حرف، بما في ذلك المسافات. الطلبات الفاشلة مجانية. لا توجد رسوم شهرية أو اشتراكات أو عمولات. الدفع يتم فقط عبر الرصيد المضاف، والذي لا ينتهي. لا توجد فواتير ضرائب أو رسوم بنكية مخفية.
كيف أدير مفاتيح API؟
يمكنك إدارة مفاتيحك من لوحة التحكم في صفحة /get-api-key/. يمكنك عرض الرصيد، الاستخدام، وإصدار مفتاح جديد. عند إصدار مفتاح جديد، يصبح القديم غير صالح فوراً. لا حاجة لإعادة تكوين التطبيقات إذا كنت تستخدم المفتاح الحالي، لكن الإصدار الجديد يوفر أماناً إضافياً.
الطلب الأول
curl
curl https://api.getjl3.com/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.getjl3.com/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.getjl3.com/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
ابدأ بإنشاء حساب عبر صفحة التسجيل، حيث يمكنك الاختيار بين تسجيل الدخول بحساب Google أو استخدام بريدك الإلكتروني وكلمة مرور. إذا استخدمت Google، ستحصل تلقائيًا على رصيد تجريب بقيمة $0.50 صالح لمدة 7 أيام، بينما يبدأ الحساب الآخر من الصفر.
بمجرد الدخول، سترى مفتاح API الخاص بك ورصيدك الحالي في لوحة التحكم. يمكنك نسخ المفتاح واستخدامه فوراً في طلباتك، وهو متوافق مع مكتبات OpenAI الرسمية.
إنشاء حساب
التسجيل سريع ولا يتطلب تفاصيل معقدة. اختر الطريقة التي تناسبك: Google للدخول السريع مع تجربة مجانية، أو البريد الإلكتروني للحساب القياسي.
لا توجد اشتراكات شهرية أو حدود دنيا عند الإنشاء. الحساب مخصص لموقع getjl3.com فقط.
جلب المفتاح
يظهر المفتاح فوراً بعد التسجيل بصيغة تبدأ بـ tts-. انسخه واحفظه في مكان آمن لاستخدامه في الهيدر Authorization.
المفتاح يعمل فوراً بعد الإنشاء. يمكنك استخدامه لإرسال طلبات التحويل مباشرة.
- يظهر المفتاح فوراً بعد التسجيل
- يبدأ بصيغة tts-
- يستخدم في هيدر Authorization
إدارة المفاتيح
لديك مفتاح نشط واحد لكل حساب. إذا أردت تجديد الأمان، يمكنك إصدار مفتاح جديد، مما يوقف المفتاح القديم فوراً.
لا حاجة لإعادة التكوين الطويلة؛ التغيير فوري ولا يؤثر على الطلبات الجارية بشكل جذري.
أول طلب CURL
لبدء استخدام واجهة برمجة تطبيقات موجات الطبية، تحتاج إلى إرسال نصك عبر نقطة النهاية الخاصة بتوليد الصوت. يتبع هذا الطلب نفس البنية المستخدمة في واجهات برمجة التطبيقات الشائعة، مما يسهل التكامل مع التطبيقات الصحية التي تعتمد على معايير معروفة.
يتم إرسال النص المطلوب تحويله إلى صوت كجزء من جسم الطلب بصيغة JSON. سترد الواجهة بملف صوتي جاهز للاستخدام مباشرة في أدلة المرضى أو المحتوى التعليمي.
هيكل الطلب
تتم عملية الإرسال عبر بروتوكول HTTPS باستخدام طريقة POST إلى المسار التالي: https://api.getjl3.com/v1/audio/speech. يجب أن يتضمن رأس الطلب (Header) حقل Authorization بقيمة المفتاح الخاص بك بصيغة Bearer tts-...، وأن يكون نوع المحتوى Content-Type: application/json.
- طريقة الإرسال: POST
- نقطة النهاية:
/v1/audio/speech - نوع البيانات: JSON
حقول الطلب
يجب تحديد الحقل input بنص المريض أو التوجيه الطبي، بحد أقصى 4096 حرفاً. يُحدد الحقل model النموذج المستخدم، حيث يتوفر خياران: tts-1 و tts-1-hd، وكلاهما يعمل بنفس المحرك والسعر. يمكن ضبط سرعة القراءة عبر الحقل speed، وتحدد الصيغة المطلوبة عبر response_format.
model: tts-1 أو tts-1-hdinput: النص المراد تحويلهvoice: أحد الأصوات الثمانيةresponse_format: mp3, wav, opus, flac, pcmspeed: من 0.25 إلى 4.0language: كود اللغة اختياري
الاستجابة
عند نجاح الطلب، سترد الواجهة بملف الصوت بالصيغة المختارة مرفقاً في جسم الاستجابة. في حال فشل عملية التوليب، سيتم إرجاع الخطأ دون خصم أي رصيد من حسابك، مما يضمن دقة التكاليف في تطبيقاتك الصحية.
استخدام OpenAI SDK
تتطلب التكامل السهل مع واجهة برمجة التطبيقات استخدام مكتبة OpenAI SDK المعروفة، مع تعديل نقطة النهاية الأساسية لتوجيه الطلبات إلى خوادم موجات الطبية بدلاً من خوادم OpenAI الأصلية.
يضمن هذا النهج توافق النموذج مع واجهة /v1/audio/speech كما هو موضح في حقل الطلب، مما يسمح لك باستغلال الميزات القياسية دون الحاجة إلى كتابة منطق HTTP مخصص من الصفر.
تغيير base_url
قم بتعيين متغير البيئة OPENAI_BASE_URL أو معلمة الاتصال base_url في كائن العميل إلى https://api.getjl3.com/v1. هذا يوجه جميع الطلبات المرسلة عبر المكتبة إلى نقطة النهاية الصحيحة الخاصة بنا.
- تأكد من استخدام الإصدار 1.0.0 أو أحدث من حزمة
openaiلدعم هذا الإعداد بدقة. - لا تقم بتغيير
api_key، استخدم مفتاحtts-...الخاص بك كما هو.
استخدام المكتبة الرسمية
استخدم الكلاس Audio المتاح داخل كائن العميل لإجراء مكالمات الصوت. يمكنك تحديد النموذج (tts-1 أو tts-1-hd)، والصوت المطلوب، والصيغة (مثل mp3 أو wav)، وسرعة النطق ضمن حدود السرعة المسموحة.
- المكتبة تدعم إرسال النص مباشرة وتلقي ملف الصوت الثنائي في الاستجابة.
- تتبع تلقائي للرموز المميزة (tokens) والحروف حسب سياسة الفوترة.
أمثلة الكود
```python from openai import OpenAI client = OpenAI( base_url="https://api.getjl3.com/v1", api_key="tts-your-key-here" ) response = client.audio.speech.create( model="tts-1", voice="aria", input="مرحباً، هذا دليل طبي تجريبي.", response_format="mp3" ) with open('guide.mp3', 'wb') as f: f.write(response.content) ```
لا يدعم الـ API البث (streaming)؛ يتم إرسال النص ككل (بحد 4096 حرفاً) واستلام ملف الصوت كاملاً في الاستجابة.
الصيغ المدعومة
تتيح واجهة برمجة التطبيقات اختيار صيغة ملف الصوت المناسبة لاحتياجات تطبيقك الصحي، من خلال تحديد الحقل response_format في الطلب. كل صيغة توازن بين حجم الملف وجودة الصوت، مما يساعدك على التحكم في استهلاك النطاق الترددي وتخزين الملفات الصوتية للأدلة الطبية.
يمكنك اختيار MP3 أو WAV أو OPUS أو FLAC أو PCM. هذه الخيارات تغطي معظم احتياجات التكامل، من التشغيل على المتصفحات إلى المعالجة الآلية الدقيقة في الخلفية.
MP3
يعد MP3 الصيغة الافتراضية والأكثر شيوعًا، نظرًا لضغطه العالي وتوافقه الواسع. إنه مثالي لبث الأدلة الصوتية للمرضى عبر الإنترنت، حيث يوفر حجم ملف صغير مع جودة صوت واضحة وكافية للفهم.
WAV
تقدم WAV جودة صوت غير مضغوطة ودقيقة، مما يجعلها مناسبة للمعالجات اللاحقة أو التحليل الدقيق للنطق. حجم الملف أكبر مقارنة بـ MP3، لذا يُنصح باستخدامها عند الحاجة إلى أعلى دقة صوتية دون فقدان.
OPUS, FLAC, PCM
توفر OPUS و FLAC ضغطًا فعالاً مع الحفاظ على جودة عالية، بينما تقدم PCM بيانات صوتية خام غير معالجة. تُستخدم هذه الصيغ غالبًا في بيئات التطوير المتقدمة أو عند الحاجة إلى معالجة صوتية مخصصة في التطبيقات الصحية.
الأصوات واللغات
تتوفر ثمانية أصوات افتراضية تدعم جميع اللغات الـ 23 المتاحة في المنصة. يمكنك اختيار صوت يناسب نبرة الأدلة الطبية، من السرد الدافئ (أريا) إلى الصوت الهادئ التعليمي (ساج)، أو الصوت العميق المناسب للمحتوثات (أوريون).
قائمة الأصوات
الأصوات الأنثوية تشمل: aria (سردية دافئة)، nova (مشرقة ومرحة)، luna (ناعمة للحكايات)، و sage (هادئة وتعليمية). أما الذكور فيوفرون: felix (نشط للترقيات)، milo (ودود وحواري)، atlas (محايد للأخبار)، و orion (عميق للتوثيق).
إعداد اللغة
الحد الأقصى للأحرف
يبلغ الحد الأقصى 4096 حرفاً لكل طلب (بما في ذلك المسافات). للنصوص الأطول، قسّم النص إلى أجزاء واستدمج ملفات الصوت الناتجة. التوليد بطيء نسبياً، حيث يستغرق توليد ثانية واحدة حوالي 25 حرفاً من النص.

معالجة الأخطاء
عند حدوث خطأ أثناء المعالجة، يُرجى التأكد من صحة المفتاح والحدود المسموحة. كل طلب فاشل لا يستهلك رصيدًا من رصيدك، مما يضمن عدم خصم الأموال عن الخدمات غير المنجزة.
رموز الخطأ
تُرجع الواجهة أكواد HTTP قياسية مثل 401 عند انتهاء صلاحية المفتاح، أو 429 عند تجاوز حد الطلبات (60 طلبًا في الدقيقة). تُرسل رسالة خطأ JSON توضح السبب بدقة.
- 401: المفتاح غير صالح أو منتهي الصلاحية
- 429: تجاوز حد معدل الطلبات
- 500: خطأ داخلي في الخادم (نادر)
معالجة الطلبات الفاشلة
إذا فشل التوليد لأي سبب، لا يتم خصم الرصيد. يمكنك التحقق من حالة الطلب عبر سجل الاستخدام في لوحة التحكم، حيث تظهر الرصيد المتبقي والحالة النهائية.
إعادة المحاولة
في حال الخطأ المؤقت (مثل 500)، يمكنك إعادة إرسال نفس الطلب. يُفضل استخدام آلية إعادة المحاولة مع تأخير عشوائي لتجنب ازدحام الطابور، خاصة أثناء فترات الذروة.
- أعد المحاولة فقط عند أخطاء الخادم
- تجنب إعادة الإرسال المتكرر خلال ثوانٍ معدودة
حدود الاستخدام
تضمن واجهة برمجة التطبيقات سلاسة الاستخدام اليومي من خلال حدود واضحة ومعروفة. تبدأ الحسابات الجديدة بحد 10 طلبات في الدقيقة، ثم يرتفع الحد تلقائياً إلى 60 طلباً في الدقيقة بعد أول شحن للرصيد. هذا الإطار كافٍ لمعظم سيناريوهات توليد الأدلة التعليمية والمحتوى الطبي القصير.
الحد في الدقيقة
تتم معالجة الطلبات ضمن الحد المسموح به دون حاجة لتدخل يدوي. إذا تجاوزت طلباتك الحد، ستستلم خطأً واضحاً يمكنك من ضبط وتيرة الاستدعاء في تطبيقك. الحد 60 طلباً في الدقيقة يتناسب مع احتياجات فرق المنتجات التي تحتاج إلى توليد محتوى متقطع أو دفعة صغيرة.
- 10 طلبات/دقيقة للحسابات الجديدة حتى أول شحن
- 60 طلباً/دقيقة للحسابات المفعّلة والشحن مكتمل
معالجة النصوص الطويلة
الواجهة تقبل نصوصاً تصل إلى 4096 حرفاً في كل طلب فردي، بما في ذلك المسافات والعلامات الترقيمية. إذا كان دليل المريض أو المحتوى التعليمي أطول من ذلك، يجب عليك تقسيم النص برمجياً إلى أجزاء متجانبة لا تتجاوز هذا الحد، ثم دمج الملفات الصوتية الناتجة لاحقاً.
- الحد الأقصى للطلب الواحد: 4096 حرفاً
- المسافات والعلامات الترقيمية تُحسب ضمن الأحرف
طابور المعالجة
الطلبات تُعالج بالتسلسل، مما يعني أن طلباً جديداً قد ينتظر في طابور إذا كانت الخوادم مشغولة بطلبات سابقة. هذا لا يؤثر على دقة الصوت أو سعر الطلب، لكنه قد يضيف بضع ثوانٍ إضافية من الانتظار في أوقات الذروة.
نقاط النهاية الأخرى
توفر واجهة برمجة التطبيقات نقاط نهاية إضافية تتيح لك استكشاف الخيارات المتاحة دون إرسال نصوص للتوليد. هذه النقاط مفيدة بشكل خاص لفرق المنتجات التي تحتاج إلى فهم هيكلة البيانات قبل البدء في التكامل مع التطبيقات الصحية.
يمكنك استخدام هذه النقاط للتحقق من توفر الأصوات أو نماذج النموذج الحالية، مما يضمن توافق تطبيقك مع أحدث تحديثات الخدمة دون الحاجة إلى إرسال طلبات توليد صوتية تجريبية.
GET /v1/voices
يعيد هذا الرابط قائمة بجميع الأصوات الثمانية المتاحة، مع تفاصيل كل صوت (الاسم، النوع، الوصف)، واللغات المدعومة، والصيغ الصوتية القابلة للتصدير، وأسعار الاستخدام لكل صوت. يساعد هذا في اختيار الصوت المناسب للمحتوى التعليمي أو الأدلة الطبية.
- قائمة الأصوات: aria, nova, luna, sage, felix, milo, atlas, orion
- اللغات المدعومة: 23 لغة، بما في ذلك العربية
- الصيغ المتاحة: mp3, wav, opus, flac, pcm
- السرعة: نطاق قابل للتعديل من 0.25 إلى 4.0
GET /v1/models
يعرض هذا الرابط نماذج التحويل المتاحة حالياً، وهي "tts-1" و "tts-1-hd". كلا النموذجين يعملان بنفس المحرك ولهما نفس السعر، مما يعني أنك لن تحتاج إلى تغيير الكود الأساسي إذا قررت التبديل بينهما لاحقاً.
- النماذج المتاحة: tts-1, tts-1-hd
- السعر: متطابق لكلا النموذجين ($0.01 لكل 1000 حرف)
استعلامات إضافية
يمكنك استخدام نقاط النهاية هذه للاختبار السريع أو التحقق من صحة المفتاح والتكوين. تتطلب نقاط النهاية /v1/voices و /v1/models مفتاح API للتحقق من الهوية.
استمع إلى الأصوات الثمانية
تم إنشاء كل عينة أدناه باستخدام هذه الواجهة البرمجية من نفس الجملة. تصلك إجابات الدعم الفني عبر البريد الإلكتروني المسجل في حسابك.
23 لغة
يمكن لأي صوت التحدث بأي من هذه اللغات.
