التوثيق التقني الشامل لواجهة تحويل النص الى صوت

بواسطة فريق Sout التحريري · تم التحديث 2026-11-18

يوفر هذا الدليل الإرشادي التوثيق التقني الكامل لواجهة برمجة التطبيقات (API) الخاصة بـ Sout، المصممة خصيصاً لمطوري المحتوى والمعلنين الذين يبحثون عن حلول صوتية احترافية لإنتاج البودكاست والإعلانات المسموعة. سنشرح لك خطوة بخطوة كيفية ربط واجهتك البرمجية، بدءاً من الحصول على مفتاح الوصول، مروراً بإعداد مكتبات OpenAI SDK لتسهيل التكامل، وصولاً إلى فهم حقول الطلب الأساسية مثل اختيار النموذج والصوت واللغة بدقة.

سيتضمن هذا القسم أيضاً تفاصيل تقنية عملية حول الصيغ الصوتية المدعومة (MP3, WAV, OPUS, FLAC, PCM)، وكيفية ضبط سرعة القراءة والتحكم في اللغة لضمان مخرجات دقيقة. سنستعرض أيضاً حدود الاستخدام، مثل حد الـ 4096 حرفاً لكل طلب، وآليات التعامل مع الأخطاء، بالإضافة إلى نصائح لتحسين الأداء عند معالجة نصوص طويلة، مما يضمن لك بناء تجربة صوتية موثوقة وسريعة دون حاجة لتعقيدات تقنية غير ضرورية.

التوثيق التقني الشامل لواجهة تحويل النص الى صوت

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

ما هو endpoint الخاص بالواجهة؟

الواجهة تستخدم نقطة النهاية POST https://api.playlucky168.com/v1/audio/speech لإرسال النص واستقبال ملف صوتي. يمكنك أيضًا استخدام GET /v1/voices للتحقق من الأصوات والصيغ والأسعار، وGET /v1/models لعرض النماذج المتاحة.

هل أحتاج إلى مفتاح خاص؟

نعم، يتطلب الاتصال مفتاحاً يبدأ بـ tts- يُمرر عبر رأس Authorization: Bearer. يمكنك الحصول على المفتاح من صفحة /get-api-key/ بعد التسجيل، حيث يظهر لك الرصيد والمفتاح النشط.

كيف أغير base_url؟

إذا كنت تستخدم مكتبات OpenAI SDK، قم بتغيير قيمة base_url لتشير إلى https://api.playlucky168.com/v1. هذا يسمح لك باستخدام نفس شكل الطلبات المتعارف عليه مع واجهتنا الخاصة.

ما هو الحد الأقصى للنص؟

الحد الأقصى للنص المدخل في كل طلب هو 4096 حرفاً. إذا كان النص أطول من ذلك، يجب تقسيمه إلى أجزاء لا يتجاوز كل منها هذا الحد، ثم دمج الملفات الصوتية الناتجة.

ما هي الصيغ المدعومة؟

تدعم الواجهة صيغ mp3، wav، opus، flac، وpcm. يمكنك تحديد الصيغة المطلوبة عبر حقل response_format في جسم الطلب، مع مراعاة أن الصيغ المختلفة قد تؤثر على حجم الملف النهائي.

كيف أحدد الصوت؟

حدد الصوت عبر حقل voice في الطلب، حيث تتوفر ثمانية أصوات: aria، nova، luna، sage، felix، milo، atlas، وorion. كل صوت يقدم نبرة مميزة تناسب أنواع المحتوى المختلفة.

هل يمكنني تغيير السرعة؟

نعم، يمكنك ضبط سرعة النطق بين 0.25 و4.0 عبر حقل speed. هذا يسمح لك بإبطاء أو تسريع الصوت ليناسب إيقاع المحتوى الذي تنتجه، مع الحفاظ على جودة النطق الطبيعية.

كيف أتحقق من الأخطاء؟

يتم إرجاع الأخطاء عبر استجابة HTTP مع رمز الحالة ورسالة توضيحية. الطلبات الفاشلة لا تُخصم منها الرصيد، ويتم إرجاع المبلغ بالكامل، لذا يمكنك إعادة المحاولة دون قلق بشأن التكلفة.

هل تدعمون SSML؟

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

كيف أتعامل مع النصوص الطويلة؟

قم بتقسيم النص إلى أجزاء لا يتجاوز كل منها 4096 حرفاً. أرسل كل جزء عبر الواجهة، ثم اجمع الملفات الصوتية الناتجة باستخدام أدوات معالجة الصوت لضمان استمرارية الاستماع دون انقطاع.

ما هي محدودية الطلبات؟

الحد هو 60 طلباً في الدقيقة لكل مفتاح. قبل أول إيداع، يكون الحد 10 طلبات في الدقيقة. يتم معالجة الطلبات بالتسلسل، وقد ينتظر الطلب في الطابور تحت الضغط لضمان جودة الخدمة.

هل يمكنني إصدار مفتاح جديد؟

نعم، يمكنك إصدار مفتاح جديد في أي وقت من صفحة /get-api-key/. عند إصدار المفتاح الجديد، يتوقف المفتاح القديم فوراً، مما يضمن أمان حسابك وسهولة إدارة الوصول إلى الواجهة البرمجية.

ما هو تأثير اللغة الافتراضية؟

إذا لم تحدد اللغة، يتم تخمينها من النص (النصوص اللاتينية تُعتبر إنجليزية افتراضياً). للغة غير الإنجليزية المكتوبة بحروف لاتينية، يوصى بتحديد حقل language بوضوح لضمان نطق صحيح ودقيق.

هل يمكنني استخدام Python؟

نعم، يمكنك استخدام مكتبة OpenAI Python SDK أو أي مكتبة HTTP قياسية. فقط قم بتعديل base_url إلى https://api.playlucky168.com/v1 واستخدم مفتاحك الخاص في رأس المصادقة لإرسال الطلبات.

الطلب الأول

curl

curl https://api.playlucky168.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playlucky168.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.playlucky168.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中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

البدء السريع

رسم توضيحي لموجة الصوت لـ: البدء السريع

ابدأ رحلتك مع واجهة تحويل النص إلى صوت عبر إنشاء حساب على الموقع للحصول على مفتاح API الفريد الخاص بك. هذا المفتاح هو جواز الوصول الوحيد إلى الخدمة، ويظهر مع رصيدك الأولي وعدد الأحرف المتاحة لك.

بعد الحصول على المفتاح، يمكنك إرسال نصك الأول مباشرة عبر واجهة RESTful. استخدم النص المحدد والصوت المفضل للحصول على ملف صوتي جاهز للاستخدام في إنتاجك القادم.

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

قم بالتسجيل عبر صفحة إنشاء مفتاح API، سواء عبر حساب Google أو البريد الإلكتروني وكلمة المرور. سيظهر لك المفتاح الفريد على لوحة التحكم، بالإضافة إلى رصيدك التجريبي (0.50 دولار) إذا كنت مسجلاً عبر Google، وعدد الأحرف المتبقية.

أول طلب

أرسل طلب POST إلى نقطة النهاية المحددة مع تضمين النص في حقل input. حدد النموذج المناسب (tts-1 أو tts-1-hd) والصوت المفضل (مثل aria أو nova). ستتلقى استجابة تحتوي على الملف الصوتي مباشرة.

تجربة curl

يمكنك اختبار الواجهة بسهولة عبر سطر الأوامر باستخدام curl. انسخ الكود التالي، واستبدل YOUR_API_KEY بمفتاحك، و'Hello World' بالنص الذي تريد تحويله. سيعود لك الملف الصوتي بصيغة MP3 افتراضياً.

  • curl -X POST "https://api.playlucky168.com/v1/audio/speech" \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • --data "{\"model\": \"tts-1\", \"input\": \"مرحباً بالعالم\", \"voice\": \"nova\"}"

إعداد OpenAI SDK

رسم توضيحي لموجة الصوت لـ: إعداد OpenAI SDK

تتيح لك واجهة API التوافق مع مكتبات OpenAI الرسمية، حيث يعمل الطلب بنفس شكل endpoint الصوتيات، مما يسهل دمج الخدمة في مشاريعك الحالية دون الحاجة لمكتبات خاصة. هذا التصميم يضمن لك استخدام الأدوات التي تعرفها بالفعل مع إمكانية تغيير نقطة الاتصال (base_url) بسرعة.

لبدء الاستخدام، قم بتثبيت حزمة OpenAI SDK الخاصة بلغة البرمجة التي تستخدمها، ثم قم بتعيين متغير البيئة API_KEY بمفتاحك الخاص من لوحة التحكم. بعد ذلك، عيّن قيمة base_url لتشير إلى https://api.playlucky168.com/v1.

تغيير base_url

لتوجيه الطلبات إلى خوادمنا بدلاً من خوادم OpenAI، قم بتعيين متغير البيئة OPENAI_BASE_URL أو مرره مباشرة في إعدادات العميل. القيمة الصحيحة هي https://api.playlucky168.com/v1. هذا يضمن أن كل طلبات SDK ستصل إلى واجهة الصوت الخاصة بنا.

استخدام المكتبة

بمجرد ضبط الاتصال، يمكنك استدعاء دالة audio.speech بنفس الطريقة المعتادة. تأكد من إرسال الحقول الأساسية: model (تستخدم tts-1 أو tts-1-hd)، input للنص، وvoice لتحديد الصوت المطلوب. تدعم المكتبة استقبال الرد بصيغة ثنائية (binary) أو كائن استجابة (Response object).

  • تستخدم نفس كائنات الطلب SpeechParams المعروفة.
  • تدعم صيغ المخرجات: mp3, wav, opus, flac, pcm.

مثال JavaScript

إليك مثال بسيط باستخدام Node.js لإنتاج ملف صوتي. تأكد من تثبيت الحزمة عبر npm. الكود التالي يوضح كيفية تغيير الاتصال واستخدام مفتاحك لإنشاء صوت للنص المحدد.

  • const { OpenAI } = require("openai");
  • const openai = new OpenAI({
  • apiKey: process.env.OPENAI_API_KEY,
  • baseURL: "https://api.playlucky168.com/v1"
  • });
  • const response = await openai.audio.speech.create({
  • model: "tts-1",
  • voice: "nova",
  • input: "مرحباً، هذا اختبار سريع."
إعداد OpenAI SDK

حقول الطلب

رسم توضيحي لموجة الصوت لـ: حقول الطلب

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

النص المدخل

الحقل input يقبل نصوصاً تصل إلى 4096 حرفاً. يُحسب كل حرف، بما في ذلك المسافات وعلامات الترقيم، ضمن السعة المدفوعة. إذا تجاوز النص هذا الحد، يجب تقسيمه إلى أجزاء متتالية ثم دمج الملفات الصوتية الناتجة يدوياً.

  • الحد الأقصى: 4096 حرفاً لكل طلب.
  • المسافات وعلامات الترقيم تُحتسب ضمن الأحرف.

اختيار النموذج

يحدد الحقل model محرك التوليد. الخياران المتاحان هما tts-1 و tts-1-hd. كلا النموذجين يستخدمان نفس محرك الصوت ونفس الأسعار، مما يعني عدم وجود فرق في الجودة الصوتية أو التكلفة عند التبديل بينهما.

تحديد الصوت

يحدد الحقل voice الشخصية الصوتية من بين 8 خيارات. يمكن للنساء مثل Aria أو Nova، أو الرجال مثل Felix و Milo، نطق أي لغة مدعومة بدقة عالية.

  • Felix: حماسي وإعلاني.
  • Milo: ودّي ومحاور.

الصيغ الصوتية

رسم توضيحي لموجة الصوت لـ: الصيغ الصوتية

تتيح واجهة البرمجة (API) اختيار صيغة ملف الصوت المناسبة لموارد الخادم أو مشغل الوسائط الخاص بك. يتم تحديد الصيغة عبر حقل response_format في جسم الطلب، وتدعم النظام الصيغ الشائعة والمضغوطة.

صيغة MP3

تُعد MP3 الخيار الأكثر شيوعاً لمقاطع البودكاست والإعلانات المسموعة بفضل حجمها الصغير وتوافقها الواسع مع جميع مشغلات الصوت والمتصفحات الحديثة. هي الصيغة الافتراضية الموصى بها لتوفير عرض النطاق الترددي (Bandwidth).

صيغة WAV

توفر WAV جودة صوت غير مضغوطة (Lossless) مع معدل بت عالٍ، مما يجعلها مثالية للمحررين الذين يحتاجون إلى معالجة الصوت في برامج المونتاج دون فقدان أي دقة. هذه الصيغة تستهلك مساحة تخزين أكبر قليلاً مقارنة بـ MP3.

صيغ أخرى

نوفر دعمًا لـ Opus و FLAC و PCM لتلبية احتياجات تقنية محددة. Opus يوفر ضغطاً عالي الجودة، بينما يوفر FLAC ضغطاً بدون فقدان البيانات، وPCM يوفر بيانات خام غير معالجة.

  • Opus: ضغط عالي مع الحفاظ على الجودة.
  • FLAC: جودة ممتازة بدون فقدان البيانات.
  • PCM: بيانات صوتية خام غير مضغوطة.

إعدادات الصوت

رسم توضيحي لموجة الصوت لـ: إعدادات الصوت

تتيح واجهة التطبيق مرونة كاملة في ضبط سرعة النطق وتوجيه النطق اللغوي لضمان ملاءمة المحتوى الإعلاني أو البودكاست. يتم التحكم في السرعة عبر معامل speed الذي يقبل قيمًا تتراوح بين 0.25 و4.0، مما يسمح بتسريع النصوص الإعلية السريعة أو إبطائها للعبريات الهادئة.

التحكم بالسرعة

يحدد الحقل speed سرعة النطق مقارنة بالسرعة الطبيعية (1.0). القيم الأصغر من 1.0 تبطئ الصوت، بينما تزيد القيم الأكبر السرعة. النصوص الطويلة تستغرق وقتًا أطول بمعدل يتناسب مع السرعة المختارة، حيث يتطلب النص الطويل حوالي 25 حرفًا لكل ثانية من الصوت عند السرعة الطبيعية.

  • النطاق المسموح: 0.25 إلى 4.0.
  • القيمة الافتراضية: 1.0 (السرعة الطبيعية).

تحديد اللغة

يمكنك تحديد اللغة صراحةً باستخدام حقل language برمز ISO. هذه الخطوة ضرورية للنصوص المكتوبة بحروف لاتينية التي ليست إنجليزية، لضمان دقة النطق. النظام يدعم 23 لغة محددة، بما في ذلك العربية، الإنجليزية، الصينية، الفرنسية، وغيرها.

  • اللغات المدعومة: العربية، الصينية، الدنماركية، الهولندية، الإنجليزية، الفنلندية، الفرنسية، الألمانية، اليونانية، العبرية، الهندية، الإيطالية، اليابانية، الكورية، الملايوية، النرويجية، البولندية، البرتغالية، الروسية، الإسبانية، السواحيلية، السويدية، التركية.

اللغة الافتراضية

عند عدم تحديد حقل language، يحاول النظام تخمين اللغة من النص المدخل. النص المكتوب بحروف لاتينية يُعتبر افتراضيًا إنجليزيًا. إذا كان النص يحتوي على حروف غير لاتينية، يتم التعرف عليها تلقائيًا. يضمن التحديد الصريح تجنب أخطاء النطق في اللغات المختلطة.

إعدادات الصوت

معالجة الأخطاء

رسم توضيحي لموجة الصوت لـ: معالجة الأخطاء

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

تتبع الواجهة معايير HTTP القياسية لإعلامك بحالة الطلب. توفر هذه الرموز توجيهاً واضحاً لحل المشكلات التقنية أو استنفاد الموارد بسرعة.

رموز الخطأ الشائعة

يرجى الانتباه إلى رمز 429 عندما تتجاوز حد الطلبات (60 طلب/دقيقة)، ورمز 401 عند عدم صحة المفتاح، ورمز 503 عند ازدحام الخوادم. كل رمز يشير إلى سبب محدد يتطلب إجراءً مختلفاً من المطور.

  • 429 Too Many Requests: تجاوز حد السرعة.
  • 401 Unauthorized: المفتاح غير صالح.
  • 503 Service Unavailable: الخادم مشغول حالياً.

إعادة المحاولة

في حال ظهور خطأ مؤقت مثل 503، يُنصح باستخدام آلية إعادة المحاولة مع زيادة زمنية تدريجية (Exponential Backoff). هذا الأسلوب يخفف الضغط على الخادم ويزيد من احتمالية نجاح الطلب عند توفر السعة.

التحقق من الصحة

تأكد من أن النص لا يتجاوز 4096 حرفاً وأن حقل voice يطابق أحد القيم الثمانية المتاحة. تحقق أيضاً من صحة تنسيق JSON قبل الإرسال لتجنب أخطاء المعالجة الأولية التي قد تؤثر على حساب التكلفة.

  • تأكد من عدم تجاوز حد 4096 حرفاً لكل طلب.
  • تحقق من صحة مفتاح API في رأس الطلب.

حدود الواجهة

رسم توضيحي لموجة الصوت لـ: حدود الواجهة

تتطلب واجهة برمجة التطبيقات (API) فهم الحدود التقنية لضمان تدفق سلس للبيانات، خاصة عند التعامل مع حجم كبير من النصوص أو عدد متكرر من الطلبات. هذه الحدود مصممة لضمان جودة الخدمة واستقرار الخوادم.

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

محدودية الطلبات

تخضع الواجهة لحد أقصى 60 طلبًا في الدقيقة لكل مفتاح API. هذا الحد كافٍ لمعظم حالات الاستخدام، بما في ذلك توليد نصوص صوتية سريعة للأعلانات أو حلقات البودكاست.

يبدأ الحد الأدنى من الطلبات عند 10 طلبات في الدقيقة لحسابك الجديد قبل أن يتم شحن الرصيد الأول. بمجرد شحن رصيدك، يرتفع الحد تلقائيًا إلى 60 طلبًا في الدقيقة.

حجم النص

يمكنك إرسال نصوص بحد أقصى 4096 حرفًا لكل طلب. بما أن المسافات وعلامات الترقيم تُحسب ضمن هذا العدد، يُنصح بتقسيم النصوص الطويلة إلى فقرات أقصر.

لتوليد مقطع صوتي طويل، يمكنك تقسيم النص إلى أجزاء لا تتجاوز 4096 حرفًا، ثم دمج الملفات الصوتية الناتجة باستخدام أدواتك المفضلة.

إدارة المفاتيح

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

يتم إصدار المفاتيح عبر صفحة /get-api-key/ بعد التسجيل. يُنصح بتغيير المفتاح دوريًا لتعزيز الأمان، خاصة إذا تم استخدامه في بيئات متعددة.

  • حد الطلبات: 60 طلبًا/دقيقة بعد الشحن.
  • حجم النص الأقصى: 4096 حرفًا/طلب.
  • نظام المفاتيح: مفتاح واحد نشط.
  • إصدار مفتاح جديد: إيقاف السابق فورًا.
حدود الواجهة

نصائح الأداء

رسم توضيحي لموجة الصوت لـ: نصائح الأداء

لتحسين كفاءة الاستخدام، يجب تقسيم النصوص التي تتجاوز 4096 حرفًا إلى أجزاء متساوية الحجم ثم دمج الملفات الصوتية الناتجة. هذا يضمن معالجة مستقرة ويمنع فشل الطلبات الطويلة.

بما أن الطلبات تُعالج بالتسلسل، قد تواجه تأخيرًا طفيفًا تحت ضغط الحمل. استغلال الحدود المسموح بها (60 طلبًا في الدقيقة) بذكاء يحسن سير العمل دون تجاوز السعة.

تقسيم النصوص الطويلة

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

  • لا تتجاوز 4096 حرفًا لكل طلب.
  • ربط الملفات يضمن استمرارية السرد.

إدارة الطلبات

تعمل الخوادم بنظام الطابور، لذا قد يتأخر الرد قليلاً عند الازدحام. راقب معدل الطلبات لتجنب التأخير غير الضروري في إنتاج المحتوى.

تحسين الاستهلاك

يتم احتساب المسافات وعلامات الترقيم كحروف. احذف الفواصل الزائدة قبل الإرسال لتقليل التكلفة. الأخطاء في التوليد لا تُخصم من الرصيد.

استمع إلى الأصوات الثمانية

تم إنشاء كل عينة أدناه باستخدام هذه الواجهة البرمجية من نفس الجملة. استخدم صوتك لخلق القصص التي تلامس القلوب في عالم الإعلانات.

صورة رمزية للصوت aria
ariaأنثى
صورة رمزية للصوت nova
novaأنثى
صورة رمزية للصوت luna
lunaأنثى
صورة رمزية للصوت sage
sageأنثى
صورة رمزية للصوت felix
felixذكر
صورة رمزية للصوت milo
miloذكر
صورة رمزية للصوت atlas
atlasذكر
صورة رمزية للصوت orion
orionذكر

23 لغة

يمكن لأي صوت التحدث بأي من هذه اللغات.

المصادر ومزيد من القراءة

  1. Wikipedia
  2. MDN: Web Speech API
  3. IETF RFC 7845: Ogg Opus
  4. Node.js documentation
  5. W3C WAI: making audio and video accessible
  6. ISO 639 language codes
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. Creative Commons Attribution 4.0
  9. FFmpeg documentation
  10. TRON developer hub: TRC-20
  11. openai-node on GitHub
  12. LibriTTS-R corpus (OpenSLR 141)

المزيد في هذا الموقع