الأسئلة الشائعة
كيف أحصل على مفتاح API؟
قم بالتسجيل في /get-api-key/ باستخدام حساب Google أو البريد الإلكتروني. ستظهر لك الصفحة المفتاح النشط والرصيد. يمكنك إصدار مفتاح جديد في أي وقت، حيث يتوقف المفتاح القديم فوراً. لا توجد حاجة لخطوات معقدة، ابدأ بالأتمتة مباشرة.
ما هو هيكل الطلب؟
أرسل طلب POST إلى https://api.playa666.com/v1/audio/speech بجسون يحتوي على الحقل input للنص، وvoice للصوت المختار، وmodel (tts-1 أو tts-1-hd). يمكنك تحديد response_format وspeed. استخدم مفتاح الترخيص في رأس Authorization: Bearer. استلم ملف الصوت في الاستجابة.
هل تدعمون OpenAI SDK؟
نعم، الواجهة متوافقة تماماً مع شكل طلبات OpenAI. يمكنك استخدام مكتبات OpenAI SDK الرسمية عن طريق تغيير base_url إلى https://api.playa666.com/v1 واستخدام مفتاح API الخاص بنا. هذا يسهل دمج الخدمة في تطبيقاتك الحالية دون تغيير كبير في الكود.
ما هي تنسيقات الصوت المتاحة؟
تدعم الواجهة خمسة تنسيقات صوتية: mp3، wav، opus، flac، وpcm. يمكنك تحديد التنسيق المطلوب عبر حقل response_format في جسم الطلب. هذا يتيح لك اختيار الملف الأنسب لتطبيقاتك، سواء كانت ويب أو تطبيقات جوال أو أنظمة مدمجة.
كيف أغير سرعة الصوت؟
يمكنك التحكم في سرعة النطق عبر حقل speed في الطلب، حيث تتراوح القيم بين 0.25 و4.0. القيمة الافتراضية هي 1.0. هذه الميزة مفيدة لتسريع التعليمات أو إبطاء الكلام للتوضيح. السرعة تؤثر على مدة الملف الناتج دون تغيير جودة الصوت الأساسية.
ما هي أكواد الخطأ الشائعة؟
الطلبات الفاشلة تكون مجانية ويتم استرداد المبلغ بالكامل. إذا فشل التوليد، لا يتم خصم الرصيد. تأكد من صحة المفتاح والصوت المحدد. لا توجد ضمانات توفر (SLA) أو ضمانات وقت التشغيل. راقب حالة الاستجابة للتأكد من نجاح التوليد أو فشله.
ما هو الحد الأقصى للحروف؟
الحد الأقصى هو 4096 حرفاً في كل طلب. يشمل ذلك المسافات والعلامات الترقيمية. للنصوص الأطول، قم بتقسيم النص إلى أجزاء لا تتجاوز هذا الحد، ثم اجمع الملفات الصوتية الناتجة. هذا يضمن معالجة كل جزء بنجاح وتجنب حدود الواجهة.
كيف أعالج الطلبات الفاشلة؟
الطلبات الفاشلة مجانية تماماً، ويتم إرجاع المبلغ المخصم إلى رصيدك تلقائياً. لا حاجة لإعادة الفوترة. إذا فشل الطلب، تحقق من صحة المدخلات والمفتاح. يمكنك إعادة المحاولة أو تقسيم النص إذا كان طويلاً. الرصيد لا ينتهي، لذا استمر في الاستخدام دون قلق.
الطلب الأول
curl
curl https://api.playa666.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.playa666.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.playa666.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
لبدء الاستخدام، سجل حسابًا على playa666.com عبر Google أو البريد الإلكتروني. ستحتاج إلى رصيد أولي لتفعيل المفتاح، مع توفر تجربة مجانية بقيمة 0.50 دولار لمدة 7 أيام.
تتيح لك واجهة الصفحة إنشاء مفتاح فريد لكل حساب. يمكنك إصدار مفتاح جديد في أي وقت، حيث يتوقف المفتاح القديم فورًا، مما يضمن أمان الوصول لواجهة API.
إنشاء حساب جديد
سجّل عبر صفحة /get-api-key/ باستخدام حساب Google أو البريد الإلكتروني. يُنشأ الحساب لكل موقع بشكل مستقل.
يبدأ الحساب بدون رصيد تجريبي إذا استخدمت البريد الإلكتروني، بينما يمنح تسجيل Google رصيدًا أوليًا لمدة 7 أيام.
استرداد المفتاح
تظهر الصفحة المفتاح النشط مع رصيدك وعدد الأحرف المتاحة. استخدم هذا المفتاح في رأس الطلب Authorization: Bearer.
المفتاح هو رمز الوصول الوحيد لحسابك، ويمكن نسخه مباشرة إلى كودك البرمجي أو أدوات الاختبار.
إدارة المفاتيح النشطة
يمكنك إصدار مفتاح جديد في أي لحظة. عند الإصدار، يصبح المفتاح القديم غير صالح فورًا.
هذا الإجراء مفيد عند اكتشاف تسرب للمفتاح أو عند تبديل بيئة التطوير، دون الحاجة لإنشاء حساب جديد.
- مفتاح واحد نشط لكل حساب
- إلغاء فوري للمفتاح القديم
- لا حاجة لإعادة التسجيل
نموذج الطلب الأولي
تتطلب واجهة API لتحويل النص إلى كلام إرسال طلب HTTP من نوع POST إلى المسار /v1/audio/speech. يجب أن يحتوي جسم الطلب على البيانات بتنسيق JSON، حيث تحدد حقول مثل model و input و voice كيفية معالجة النص وتوليد الملف الصوتي.
تتضمن الحقول الأساسية input للنص (بحد أقصى 4096 حرفًا)، و model الذي يقبل القيم "tts-1" أو "tts-1-hd"، و voice الذي يحدد نبرة الصوت من بين الثماني خيارات المتاحة. يمكن إضافة خيارات اختيارية مثل speed للتحكم في السرعة و response_format لاختيار نوع الملف الصوتي المطلوب.
هيكل JSON للطلب
يُبنى الطلب ككائن JSON يحتوي على الحقول المطلوبة. يجب تحديد النص المراد تحويله في حقل input، واختيار النموذج المناسب (tts-1 أو tts-1-hd). يدعم النموذج تغيير سرعة النطق بين 0.25 و 4.0، مما يتيح مرونة في سرعة التسليم.
يمكن تحديد تنسيق الصوت المطلوب عبر حقل response_format، حيث تدعم الواجهة صيغ MP3، WAV، OPUS، FLAC، و PCM. إذا لم تُحدد اللغة، سيتم تخمينها تلقائيًا من النص، لكن يُنصح بتعيينها صراحةً للنصوص غير الإنجليزية المكتوبة بالحروف اللاتينية.
- model: "tts-1" أو "tts-1-hd"
- input: النص المراد تحويله (حتى 4096 حرف)
- voice: أحد الأصوات الثمانية المتاحة
- response_format: mp3, wav, opus, flac, pcm
- speed: رقم بين 0.25 و 4.0
- language: رمز ISO اختياري
المتطلبات الأساسية
يجب إرسال المفتاح في رأس الطلب Authorization بصيغة Bearer. يتبع الطلب نفس شكل طلبات OpenAI، مما يسهل التكامل. النص المدخل يجب ألا يتجاوز 4096 حرفًا في كل طلب، بما في ذلك المسافات وعلامات الترقيم.
تتم معالجة الطلبات بترتيب وصولها، وقد تنتظر في طابور عند ارتفاع الحمل. يتم احتساب كل حرف في النص المدخل في الفاتورة، مع مراعاة أن الطلبات الفاشلة لا تُ charged.
- المفتاح في رأس Authorization: Bearer
- حد النص: 4096 حرفًا للطلب
- معالجة الطلبات حسب الترتيب
- الطلبات الفاشلة مجانية
معالجة الأخطاء
تُرجع الواجهة رموز خطأ HTTP قياسية عند حدوث مشاكل في الطلب. في حال فشل التوليد، يتم إرجاع المبلغ المخصم بالكامل إلى رصيدك. يُنصح بالتحقق من صحة النموذج والصوت قبل الإرسال لتجنب الأخطاء.
إذا تجاوز النص الحد المسموح به، سيتم رفض الطلب. تأكد من تنسيق JSON صحيح واستخدام المفتاح النشط. يمكن إصدار مفتاح جديد إذا لزم الأمر، حيث يتوقف المفتاح القديم فورًا.
- رموز HTTP للأخطاء
- إرجاع كامل المبلغ للطلبات الفاشلة
- التحقق من صحة النموذج والصوت
- إصدار مفتاح جديد عند الحاجة

تكامل مع OpenAI SDK
تتوافق واجهة API الخاصة بنا مع هيكل طلبات OpenAI، مما يتيح لك استخدام مكتبات OpenAI الرسمية (أو أي مكتبة HTTP) دون حاجة لنظام SDK مخصص. كل ما عليك فعله هو تغيير عنوان الخادم الأساسي (base_url) في إعدادات العميل الخاص بك.
هذا النهج يبسط عملية التكامل بشكل كبير، حيث يمكنك الاعتماد على الأدوات المألوفة التي تستخدمها عادةً، مع ضمان توافق كامل في بنية الطلبات والاستجابات.
تغيير base_url
لتفعيل التكامل، قم بتحديث إعداد base_url في مكتبة OpenAI لتشير إلى https://api.playa666.com/v1. هذا التغيير البسيط يجعل جميع المكالمات تستخدم واجهتنا مباشرةً.
تأكد من أن مفتاح API الخاص بك يبدأ بـ tts- ويتم إرساله عبر رأس Authorization: Bearer. هذا يضمن مصادقة صحيحة للطلبات الواردة.
- العنوان الأساسي: https://api.playa666.com/v1
- صيغة المفتاح: Bearer tts-...
- توافق كامل مع نماذج tts-1 و tts-1-hd
استخدام المكتبات الرسمية
باستخدام OpenAI SDK، يمكنك استدعاء نقطة نهاية /v1/audio/speech بنفس الطريقة التي تستخدم بها OpenAI، مع تغيير المسار الأساسي فقط.
المكتبات الرسمية تدعم إرسال النصوص بصيغة JSON واستقبال ملفات الصوت مباشرةً، مما يقلل من تعقيد الكود ويحسن موثوقية التكامل.
- يدعم Python, Node.js, و Ruby
- لا حاجة لمكتبات وسيطة
- سهولة الصيانة والتحديث
أمثلة برمجية
في Python، قم بتعيين openai.base_url ثم استخدم Audio.speech.create مع تحديد النموذج والصوت والصيغة المطلوبة.
مثال بسيط: إرسال نص عربي إلى صوت 'Aria' بصيغة MP3 بسرعة 1.0، والحصول على الملف الصوتي مباشرةً.
- تعيين base_url
- استدعاء Audio.speech.create
- معالجة الاستجابة الصوتية
تنسيقات الصوت
توفر واجهة API مرونة عالية في اختيار تنسيق الملف الصوتي returned في الاستجابة، مما يسمح لك بضبط توازن الجودة والحجم حسب احتياجات تطبيقك. يدعم النظام أربعة تنسيقات رئيسية: MP3 وWAV وOPUS وFLAC، مع خيار PCM الخام.
يختلف كل تنسيق في خصائصه التقنية، مما يؤثر على استهلاك النطاق الترددي وجودة الاستماع. اختر التنسيق الأنسب لبيئة النشر الخاصة بك، سواء كانت تطبيقات الهاتف أو خوادم الويب.
دعم MP3 و WAV
يُعد MP3 الخيار الأمثل لمعظم التطبيقات بسبب صغره وحسن ضغطه، مما يقلل من استهلاك النطاق الترددي. بينما يوفر WAV جودة عالية غير مضغوطة، وهو مناسب للعمليات التي تتطلب دقة عالية دون ضغط البيانات.
- MP3: ضغط عالي، حجم صغير، مناسب للبث.
- WAV: جودة أصلية، حجم أكبر، غير مضغوط.
تنسيقات OPUS و FLAC
يوفر OPUS توازنًا ممتازًا بين الجودة والصغر، وهو مثالي للاتصالات عبر الإنترنت. أما FLAC فيقدم جودة عالية دون فقدان البيانات، مما يجعله خيارًا جيدًا للأرشفة أو المعالجة اللاحقة.
- OPUS: كفاءة عالية في الضغط، جودة ممتازة.
- FLAC: ضغط بدون فقدان، جودة عالية الدقة.
تنسيق PCM
يقدم تنسيق PCM بيانات صوتية خام وغير مضغوطة، مما يلغي أي معالجة إضافية. يُستخدم هذا التنسيق عندما تحتاج إلى التحكم الكامل في تدفق البيانات أو عند دمج الصوت مع أنظمة معالجة أخرى.
- بيانات صوتية خام.
- بدون ضغط، حجم كبير.
إعدادات الصوت
تتيح لك واجهة API التحكم الكامل في نبرة المحتوى الصوتي المنتج لمنتجاتك. يمكنك اختيار صوت من بين ثمانية خيارات متنوعة تناسب طبيعة تطبيقات السيارات والملاحة، سواء كانت إرشادية أو ترويجية.
يسمح لك النظام بضبط سرعة النطق بدقة لتتناسب مع تجربة المستخدم، مع دعم اللغة العربية (واللغات الأخرى). هذه الخيارات تضمن وضوح التعليمات دون الحاجة إلى تعديل يدوي للملفات الصوتية.
اختيار الصوت المناسب
يتوفر ثمانية أصوات افتراضية مبنية على تسجيلات مرخصة، تغطي احتياجات مختلفة من سرد القصة إلى الأخبار المباشرة.
الأصوات النسائية تشمل Aria للسرد الواضح، Nova للنبرة المتفائلة، Luna للحكايات، وSage للتعليميات الهادئة. أما الأصوات الذكارية فتشمل Felix للنبرة الحيوية، Milo للمحادثات الودية، Atlas للأخبار المحايدة، وOrion للمواضيع الوثائقية العميقة.
- Aria: سرد واضح ودافئ
- Nova: نبرة مشرقة ومتفائلة
- Luna: سرد قصصي هادئ
- Sage: تعليمي هادئ
- Felix: حيوي وترويجي
- Milo: ودّي ومحادث
تعديل سرعة النطق
يمكنك تعديل سرعة النطق ضمن نطاق يتراوح بين 0.25 و4.0 أضعاف السرعة الطبيعية. هذا الإعداد مفيد لضبط إيقاع التعليمات في تطبيقات الملاحة حسب سرعة حركة السيارة أو وضوح الكلام المطلوب.
السرعة الافتراضية توفر نطقاً طبيعياً، بينما يمكن زيادة السرعة لعرض بيانات سريعة أو تقليلها للتركيز على تفاصيل الوجهة.
تحديد اللغة
الدعم شامل لـ23 لغة، بما فيها العربية، الإنجليزية، الصينية، والفرنسية. يمكن لأي صوت نطق أي من هذه اللغات بدقة.
يتم تحديد اللغة تلقائياً من النص المدخل، لكن يُنصح بتحديد حقل اللغة صراحةً للنصوص غير الإنجليزية المكتوبة بالأحرف اللاتينية لضمان النطق الصحيح.
- الدعم يشمل 23 لغة عالمية
- تعيين اللغة يضمن دقة النطق
- الافتراضي هو الإنجليزية للنصوص اللاتينية

معالجة الأخطاء
تتضمن واجهة API آليات واضحة للإفلاس عن الأخطاء لضمان موثوقية التكامل. عند فشل عملية توليد الصوت، يتم إرجاع المبلغ كاملاً، مما يلغي أي تكلفة على المستخدم في الحالات غير الناجحة. هذا يضمن شفافية التكاليف حتى في السيناريوهات غير المتوقعة.
لضمان دقة البيانات، تعتمد المنصة على رموز HTTP قياسية تعكس حالة الطلب بدقة. لا يتم تخزين الملفات الصوتية المولدة، لذا يركز النظام على إيصال النتيجة أو السبب في الفشل فوراً عبر الاستجابة.
رموز الخطأ الشائعة
تستخدم الواجهة رموز HTTP المألوفة للإشارة إلى حالة كل طلب. رمز 401 يعني أن مفتاح API غير صالح، بينما يشير 429 إلى تجاوز حد الـ 60 طلباً في الدقيقة. رمز 400 ينذر بوجود خطأ في صيغة الطلب أو النص المدخل.
إذا كان النص يتجاوز حد 4096 حرفاً، قد تظهر أخطاء في المعالجة. من المهم دائماً التحقق من صحة المدخلات قبل الإرسال لتجنب تأخير الاستجابة.
- 401 Unauthorized: مفتاح API غير صالح
- 429 Too Many Requests: تجاوز حد المعدل
- 400 Bad Request: خطأ في صيغة الطلب
- 500 Internal Server Error: خطأ غير متوقع في الخادم
معالجة الطلبات الفاشلة
عند فشل الطلب، تُعاد المبلغ كاملاً إلى رصيدك. هذا يعني أن التكلفة لا تُحتسب إلا عند نجاح التوليد فعلياً. يُنصح بمراجعة استجابة JSON للبحث عن حقل 'error' الذي يحتوي على تفاصيل السبب.
لا تحتاج إلى استرداد يدوي للمبالغ؛ يتم ذلك تلقائياً. ومع ذلك، تأكد من إعادة محاولة الطلب بعد حل المشكلة الموضحة في الرسالة، مع مراعاة فترات الانتظار لتجنب تكرار خطأ المعدل.
تقارير الحالة
تحتفظ المنصة بسجلات الطلبات (الوقت، الحرف، الحالة) لأغراض الفوترة فقط. لا يتم تخزين الملفات الصوتية الناتجة، لذا لا توجد تقارير عن جودة الصوت بمرور الوقت.
يمكنك مراجعة رصيدك ومفاتيحك في لوحة التحكم لفهم استهلاكك وحالة حسابك. هذه السجلات دقيقة وتعكس الطلبات (بما فيها الفاشلة) لأغراض الفوترة.
الحدود والقيود
تحدد واجهة البرمجة حدودًا واضحة لضمان استقرار الخدمة عند الاستخدام المكثف. يفرض النظام حدًا أقصى للطلبات يسمح لك بالتخطيط الدقيق لاستهلاك الموارد دون مفاجآت غير متوقعة.
يتعامل النظام مع الأحمال العالية بآلية بسيطة تعتمد على معالجة الطلبات بالتسلسل. هذا يعني أن سرعة الاستجابة تعتمد على حجم النص وحالة الخادم في وقت التنفيذ.
حد الطلبات الدقيقة
يسمح النظام بـ 60 طلبًا في الدقيقة لكل مفتاح API. قبل إجراء أول إعادة شحن، يكون الحد 10 طلبات فقط في الدقيقة.
يتم احتساب كل استدعاء للواجهة، سواء نجح أو فشل، ضمن هذا العدد. يُنصح بمراقبة الاستخدام عبر لوحة التحكم لتجنب تجاوز الحد المفاجئ.
- 60 طلبًا في الدقيقة بعد الشحن
- 10 طلبات في الدقيقة قبل أول شحن
حد حجم النص
يمكنك إرسال ما يصل إلى 4096 حرفًا في كل طلب واحد. يشمل هذا العدد المسافات وعلامات الترقيم.
للنصوص الأطول، يجب تقسيمها إلى أجزاء لا تتجاوز هذا الحد ثم دمج الملفات الصوتية الناتجة لاحقًا.
معالجة الطوابير
تُعالج الطلبات واحدة تلو الأخرى. عند ارتفاع الحمل، قد ينتظر طلبك في قائمة الانتظار قبل البدء في المعالجة.
السرعة النموذجية تعادل الوقت الحقيقي تقريبًا للنصوص الطويلة (حوالي 25 حرفًا في الثانية)، لكن النصوص القصيرة قد تستغرق بضع ثوانٍ إضافية.

أمثلة CURL
تُعد أمثلة cURL الطريقة المباشرة والأسرع للتحقق من عمل واجهة API قبل البدء في البرمجة. كل طلب يحتاج إلى مفتاح صالح وتحديد النموذج والصوت.
يمكنك تجربة الطلبات الأساسية أو تلك التي تتضمن سرعة ولغة محددة، مع التأكد من استقبال ملف الصوت في الاستجابة.
طلب أساسي
أرسل نصاً قصيراً لتوليد صوت بصيغة MP3 افتراضية. تأكد من استبدال YOUR_API_KEY بمفتاحك الحقيقي.
curl -X POST https://api.playa666.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "مرحباً بك في عالم السيارات", "voice": "aria"}'
- النموذج: tts-1
- الصوت: aria
- التنسيق: mp3 (افتراضي)
طلب مع خيارات متقدمة
تخصيص سرعة النطق واللغة. السرعة تتراوح بين 0.25 و 4.0. اللغة اختيارية لكن موصى بها للنصوص غير الإنجليزية.
curl -X POST https://api.playa666.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "input": "توجيهات الملاحة آمنة وواضحة", "voice": "atlas", "speed": 1.2, "language": "ar", "response_format": "wav"}'
- النموذج: tts-1-hd
- السرعة: 1.2
- اللغة: ar
- التنسيق: wav
معالجة الأخطاء
عند فشل الطلب، ستحصل على كود خطأ JSON يوضح السبب، مثل نفاد الرصيد أو خطأ في النص. الطلبات الفاشلة مجانية.
curl -X POST https://api.playa666.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "", "voice": "nova"}'
استمع إلى الأصوات الثمانية
تم إنشاء كل عينة أدناه باستخدام هذه الواجهة البرمجية من نفس الجملة. نظام ملاحة ذكي يوجه رواد السيارات الناشئين نحو التميز التقني
23 لغة
يمكن لأي صوت التحدث بأي من هذه اللغات.
