دليل المطور الشامل لواجهة برمجة تحويل النص إلى كلام

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

يهدف هذا الدليل إلى تمكين فرق الموارد البشرية والتدريب المؤسسي من دمج خدمة تحويل النص إلى كلام في سير عملهم التقني بسهولة. نوضح لك خطوة بخطوة كيفية الحصول على مفتاح API، وإعداد المتغيرات الأساسية، وإرسال أول طلب للحصول على ملف صوتي عالي الجودة. يتوافق الهيكل مع واجهة OpenAI المعروفة، مما يسهل عملية التكيف مع أنظمة التدريب عن بُعد أو المقر دون الحاجة إلى تعلم بروتوكولات جديدة.

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

دليل المطور الشامل لواجهة برمجة تحويل النص إلى كلام

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

كيف أحصل على مفتاح API؟

سجّل حسابك في صفحة /get-api-key/ باستخدام Google أو البريد الإلكتروني. ستظهر لك الصفحة المفتاح النشط، الرصيد، ومثال جاهز. يمكنك إصدار مفتاح جديد في أي وقت، حيث يتوقف المفتاح القديم فوراً. هذا المفتاح ضروري للمصادقة عبر رأس Authorization: Bearer tts-... عند إرسال الطلبات.

ما هي صيغة الطلب؟

أرسل طلب POST إلى https://api.play5977.com/v1/audio/speech. يجب أن يحتوي الجسم على حقل input للنص (حتى 4096 حرف)، و voice لاختيار الصوت، و response_format للصيغة، و speed للسرعة. يمكنك تحديد language اختياريًا. استخدم مفتاح API في رأس Authorization: Bearer.

هل يدعم الطلب الصوت المباشر؟

لا، لا يدعم المنتج البث المباشر (Streaming) أو WebSocket. يتم توليد ملف صوتي كامل وإرجاعه في الاستجابة. تُعالج الطلبات واحدة تلو الأخرى، لذا قد ينتظر الطلب في الطابور تحت الضغط. لا يوجد دفق جزئي للصوت أثناء التوليد.

كيف أستخدم مكتبة OpenAI؟

استخدم مكتبات OpenAI الرسمية بتعديل base_url إلى https://api.play5977.com/v1. استخدم مفتاح API الخاص بك للمصادقة. تأكد من إرسال النموذج 'tts-1' أو 'tts-1-hd'. تعمل المكتبة بنفس طريقة واجهة OpenAI Speech، مما يسهل التكامل مع أنظمة التدريب الموجودة لديك دون تغييرات كبيرة في الكود.

ما هو النموذج الافتراضي؟

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

هل يمكنني تحديد سرعة الصوت؟

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

ما هي صيغ الملفات المتاحة؟

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

ماذا أفعل إذا فشل الطلب؟

إذا فشل الطلب، لا يتم خصم الرصيد. يتم إرجاع المبلغ بالكامل تلقائياً. يمكنك إعادة محاولة الطلب بنفس البيانات. تأكد من صحة المفتاح، النص (أقل من 4096 حرف)، والصوت المحدد. إذا استمرت المشكلة، راجع سجل الطلبات في لوحة التحكم أو تواصل معنا عبر البريد الإلكتروني للحصول على الدعم.

الطلب الأول

curl

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

البدء السريع

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

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

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

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

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

لبدء الاستخدام، انتقل إلى صفحة إنشاء المفتاح وقم بإنشاء حساب باستخدام حساب Google أو البريد الإلكتروني. سيظهر لك مفتاح API فريد يبدأ بـ tts-، وهو المسؤول عن المصادقة على طلباتك.

  • يمكن إصدار مفتاح جديد في أي وقت، مما يؤدي إلى إيقاف القديم فوراً.

إعداد المتغيرات

إعداد المتغيرات

يحتاج المطورون إلى تحديد نقطة النهاية الأساسية للنظام وهي https://api.play5977.com/v1. يجب تضمين مفتاح API في رأس الطلب Authorization: Bearer YOUR_API_KEY لكل طلب ترسله.

أول طلب

لإجراء أول تحويل، أرسل طلب POST إلى المسار /v1/audio/speech بجوهر JSON يحتوي على حقل input للنص، وحقل voice لتحديد الصوت، وحقل model (إما tts-1 أو tts-1-hd). سيعود الرد بملف الصوت المطلوب.

  • النص المدخل لا يتجاوز 4096 حرفاً.

نموذج الطلب

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

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

يتعامل النموذج مع النص المدخل كسلسلة أحرف عادية، مع مراعاة حد الـ 4096 حرفاً لكل طلب. لا يدعم النص المنسق (SSML). يتم تحديد الصوت والنموذج المطلوبين عبر حقول نصية واضحة، مما يضمن تناسق المخرجات مع المعايير المؤسسية المطلوبة لتدريب الفرق عن بُعد.

نص الإدخال

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

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

  • الحد الأقصى: 4096 حرفاً لكل طلب
  • يشمل المسافات والعلامات الترقيمية في الحساب
  • دعم 23 لغة مع إمكانية التخمين التلقائي

تحديد الصوت

يحدد حقل voice الشخصية الصوتية المستخدمة في التوليد. تتوفر ثمانية أصوات افتراضية تناسب سياقات التدريب المختلفة، من السرد الواضح إلى الحوار المريح.

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

  • aria: سرد واضح ودافئ
  • nova: نبرة مشرقة ومرحة
  • luna: سرد قصصي هادئ
  • sage: تعليمي هادئ
  • felix: ديناميكي وإعلاني
  • milo: محادثة ودودة

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

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

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

  • tts-1: النموذج القياسي
  • tts-1-hd: نموذج عالي الدقة
  • نفس السعر لكلا النموذجين

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

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

تتيح واجهة برمجة التطبيقات استلام الملفات الصوتية بصيغ متعددة تناسب بيئة التدريب المؤسسي. يمكنك اختيار الصيغة الأنسب لتدفق البيانات أو لتحرير السجلات التدريبية بدقة، مع الحفاظ على جودة الصوت الأصلية.

MP3

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

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

WAV

  • جودة صوت عالية غير مضغوطة
  • سهلة التحرير والمعالجة
  • حجم ملف أكبر من MP3

OPUS و FLAC و PCM

توفر OPUS كفاءة عالية في الضغط مع الحفاظ على الجودة، مما يجعلها خياراً ممتازاً لنقل الصوت عبر شبكات ذات عرض نطاق محدود. يوفر FLAC ضغطاً بدون فقدان البيانات، بينما يقدم PCM بيانات صوتية خام وغير معالجة.

  • OPUS: ضغط عالي الكفاءة للشبكات
  • FLAC: جودة عالية بدون فقدان البيانات
  • PCM: بيانات صوتية خام

إعداد OpenAI SDK

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

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

يتيح هذا النهج للمطورين الاستفادة من البنية المألوفة لـ OpenAI مع الحفاظ على الميزات الفريدة لخدمة Wajh. التوافق لا يعني مجرد محاكاة الواجهة، بل يضمن عمل الطلبات والاستجابات بشكل متسق وموثوق.

تغيير base_url

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

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

استخدام مفتاح API

استخدم مفتاح API الخاص بك كما تفعل مع أي مفتاح آخر، عن طريق إضافته إلى رأس الطلب كرمز مميز (Bearer token). المفتاح هو المعرف الفريد الذي يربط طلباتك بحسابك ويسمح بتتبع الاستخدام والفواتير.

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

التوافق

متوافق مع مكتبات OpenAI الرسمية. يعمل SDK بشكل متسق مع الطلبات والاستجابات، مما يسهل عملية التطوير والاختبار.

يمكنك استخدام نفس هيكل الطلبات الذي تستخدمه مع OpenAI، مع تعديلات بسيطة لمطابقة الإعدادات الخاصة بـ Wajh مثل اختيار الصوت والصيغة المطلوبة.

الحدود

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

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

60 طلب في الدقيقة

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

  • الحد القياسي: 60 طلب/دقيقة
  • الحد التجريبي: 10 طلبات/دقيقة
  • القيود مرتبطة بالمفتاح وليس الحساب

حد الأحرف

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

معالجة متسلسلة

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

الحدود

الأصوات والنماذج

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

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

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

GET /v1/voices

أرسل طلب GET إلى /v1/voices لاسترداد قائمة كاملة بالأصوات الثمانية، اللغات المدعومة، والصيغ الصوتية المتاحة. تُستخدم هذه البيانات لتحديد المعرف الصحيح لكل صوت قبل إرسال طلب التوليد.

GET /v1/models

نقطة النهاية /v1/models تعرض النماذج المتاحة (tts-1 و tts-1-hd). كلا النموذجين يستخدمان نفس محرك الصوت، لذا اختر ما يناسب جودة الصوت المطلوبة دون تغيير في الأصوات.

قائمة الأصوات

تتوفر ثمانية أصوات افتراضية تدعم اللغات الـ 23 المذكورة. يمكن لكل صوت نطق أي لغة، لكن يوصى بتحديد حقل language بدقة للنصوص غير الإنجليزية لضمان النطق الصحيح.

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

  • أرييا: سرد واضح ودافئ
  • نوفيا: نبرة مشرقة وعالية الطاقة
  • لونا: سرد قصصي ناعم
  • سايج: تعليمي وهادئ
  • فيليكس: ترويجي ونشط
  • ميلو: محادثة ودود
  • أتلاس: خبري ومحايد
  • أورايون: وثائقي وعميق

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

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

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

رموز الحالة

تعيد الخوادم رموز الحالة القياسية مثل 200 للنجاح و 4xx للأخطاء في الطلب (مثل مفتاح غير صالح أو حجم نص كبير). تساعدك هذه الرموز في تشخيص سبب الفشل مباشرة من خلال استجابة JSON.

الطلبات الفاشلة

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

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

يمكنك إعادة إرسال الطلب في حال حدوث خطأ مؤقت. تأكد من التحقق من حد الطلبات (60 طلباً في الدقيقة) لتجنب الرفض.

مثال CURL

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

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

الطلب الأساسي

أرسل النص باستخدام النموذج الافتراضي 'tts-1'. سيستقبل الاستجابة ملف صوتي بصيغة mp3 افتراضياً. تأكد من استبدال <YOUR_API_KEY> بالمفتاح الفعلي الخاص بحسابك.

  • curl -X POST https://api.play5977.com/v1/audio/speech \
  • -H "Authorization: Bearer <YOUR_API_KEY>" \
  • -H "Content-Type: application/json" \
  • --data '{"model": "tts-1", "input": "مرحباً، هذا اختبار للواجهة"}'

تحديد الصيغة

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

  • --data '{"model": "tts-1", "input": "نص التدريب", "response_format": "wav"}'

توفير السرعة

يمكنك التحكم في سرعة القراءة بين 0.25 و 4.0. هذه الميزة مفيدة لضبط نطق النصوص التدريبية الطويلة أو المختصرة بما يناسب وقت الاستماع.

  • --data '{"model": "tts-1", "input": "نص تجريبي", "speed": 1.5}'

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

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

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

23 لغة

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

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

  1. Wikipedia
  2. OpenAI API reference: create speech
  3. TRON developer hub: TRC-20
  4. ISO 639 language codes
  5. curl documentation
  6. openai-node on GitHub
  7. LibriTTS-R corpus (OpenSLR 141)
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. LibriVox public-domain audiobooks
  10. Node.js documentation
  11. Tether (USDT)
  12. IETF RFC 7845: Ogg Opus

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