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

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

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

تجد هنا أمثلة عملية للطلبات باستخدام Curl أو OpenAI SDK، مع توضيح دقيق للنماذج المدعومة، حدود الاستخدام، والممارسات لضمان الأداء. هذا المستند موجه للمطورين الذين يبحثون عن حل تقني موثوق وسريع لتوليد الصوت من النص دون تعقيدات غير ضرورية.

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

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

ما هو هيكل طلب POST؟

يتم إرسال الطلب إلى https://api.playtk9.com/v1/audio/speech بصيغة JSON. يجب تضمين حقول: model (tts-1 أو tts-1-hd)، input للنص، voice للصوت، response_format للصيغة، وspeed للسرعة. يمكن تحديد language اختياريًا. يعتمد المصادقة على مفتاح API في رأس الطلب Authorization.

هل يعمل SDK الرسمي لـ OpenAI؟

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

ما هو الحد الأقصى للأحرف في الطلب؟

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

هل يمكنني تحديد اللغة صراحة؟

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

ما هي القيم المسموحة للسرعة؟

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

هل الملفات الصوتية يتم تخزينها؟

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

كيف أعرف سبب فشل الطلب؟

إذا فشل الطلب، يتم إرجاع الرصيد بالكامل. يمكنك الاطلاع على حالة الطلب من خلال لوحة التحكم في صفحة /get-api-key/، حيث تظهر تفاصيل الاستخدام والحالة. لا توجد ضمانات توفر (SLA)، لذا يُنصح بالتحقق من الحدود ومعدل الطلبات لضمان نجاح المعالجة.

هل هناك تأخير في المعالجة؟

نعم، قد يحدث تأخير لأن الطلبات تُعالج بالتتابع. تحت الضغط، قد ينتظر الطلب في طابور. السرعة التقريبية تساوي الوقت الحقيقي للنص، حيث يستغرق توليد بضع ثوانٍ للجمل القصيرة. يُنصح بتقسيم النصوص الطويلة لضمان كفاءة المعالجة وتقليل وقت الانتظار.

الطلب الأول

curl

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

رسم توضيحي لموجة الصوت لـ: الحصول على مفتاح API

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

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

إنشاء حساب جديد

إنشاء حساب جديد

يمكنك إنشاء حساب عبر صفحة /get-api-key/ باستخدام Google أو البريد الإلكتروني. الحسابات المسجلة بـ Google تحصل تلقائياً على رصيد تجريبى بقيمة $0.50 صالح لمدة 7 أيام. الحسابات المسجلة بالبريد الإلكتروني تبدأ بدون رصيد تجريبي.

يتم إنشاء الحسابات بشكل مستقل لكل موقع، لذا يجب التأكد من أنك تسجل في الموقع الصحيح (playtk9.com) للحصول على المفتاح المناسب.

  • التسجيل عبر Google يمنح رصيداً تجريبياً أولياً.
  • التسجيل بالبريد الإلكتروني لا يمنح رصيداً تجريبياً.
  • الحسابات خاصة بكل موقع مستقلاً.

نسخ المفتاح من لوحة التحكم

نسخ المفتاح من لوحة التحكم

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

يمكنك نسخ المفتاح مباشرة من هذه الصفحة لاستخدامه في طلباتك. تأكد من الحفاظ على سريته، حيث يتم استخدامه في رأس الطلب (Header) للمصادقة.

  • المفتاح يظهر في لوحة التحكم الرئيسية.
  • يتم استخدام المفتاح في رأس الطلب (Authorization: Bearer ...).
  • يمكن نسخ المفتاح بنقرة واحدة.

إصدار مفتاح جديد

يمكنك إصدار مفتاح API جديد في أي وقت من خلال لوحة التحكم. عند إصدار مفتاح جديد، يتوقف المفتاح القديم فوراً عن العمل.

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

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

طلب أول صوت باستخدام Curl

رسم توضيحي لموجة الصوت لـ: طلب أول صوت باستخدام Curl

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

هيكل الطلب JSON

يتم إرسال الطلب عبر طريقة POST إلى المسار https://api.playtk9.com/v1/audio/speech. يتعين تضمين حقول "model" (tts-1 أو tts-1-hd)، و"input" (النص المراد تحويله)، و"voice" (أحد الأصوات الثمانية)، و"response_format" (mp3, wav, opus, flac, pcm). يجب ألا يتجاوز النص 4096 حرفاً، بما في ذلك المسافات وعلامات الترقيم.

إدراج مفتاح المصادقة

يجب تضمين المفتاح الفريد في رأس الطلب (Header) بالصيغة: Authorization: Bearer tts-...، حيث يتم استبدال "tts-..." بالمفتاح الناتج عن إنشاء الحساب. يضمن هذا الإجراء صلاحية الطلب وربطه بحسابك لتتبع الاستهلاك والفوترة.

استلام ملف الصوت

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

الاستخدام مع OpenAI SDK

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

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

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

تغيير base_url

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

يمكنك استخدام مفتاح API الخاص بك الذي يبدأ بـ tts- مباشرةً. يتم التحقق من الصلاحية والحدود (60 طلب/دقيقة) عبر حسابك في AwazCraft.

استخدام نفس شكل الطلب

يستخدم الطلب نفس الهيكل JSON المعتمد في POST /v1/audio/speech. الحقول المطلوبة هي model، input، وvoice. يتم تحديد النموذج إما بـ tts-1 أو tts-1-hd، بينما يتحدد الصوت عبر المعرفات المحددة (مثل aria أو nova).

يدعم الطلب حقول اختيارية مثل speed (بين 0.25 و4.0) وlanguage. يتم إرجاع ملف الصوت مباشرة في استجابة الـ HTTP، مما يسمح بالتخزين أو المعالجة الفورية دون خطوات إضافية.

مثال كود بايثون

يوضح الكود التالي كيفية تهيئة العميل وتوليد ملف صوتي باستخدام مكتبة openai القياسية. استبدل YOUR_API_KEY بالمفتاح الخاص بك.

تأكد من تثبيت الحزمة عبر pip install openai. يعمل الكود بنفس طريقة إرسال النص واستقبال ملف الصوت عبر واجهة REST.

  • import openai
  • client = openai.OpenAI(api_key="tts-...", base_url="https://api.playtk9.com/v1")
  • with client.audio.speech.create(model="tts-1", voice="nova", input="مرحباً، هذا اختبار للتكامل.") as response:
  • with open("output.mp3", "wb") as f:
  • f.write(response.content)

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

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

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

اختيار النموذج tts-1 أو tts-1-hd

بما أن النموذجين متطابقين في المحرك الأساسي، يمكنك استخدام أي منهما حسب تفضيل التسمية في كودك. السعر ثابت عند $0.01 لكل 1000 حرف بغض النظر عن النموذج المختار.

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

يتوفر 8 أصوات افتراضية مخصصة لاحتياجات المحتوى المرئي. تشمل الأصوات نسائية مثل Aria و Nova، وذكورية مثل Felix و Milo. جميع الأصوات تدعم التوليد السريع والموثوق للنصوص.

  • Aria: راوية واضحة ودافئة
  • Nova: مشرقة وعالية الطاقة
  • Felix: مليء بالحيوية للمحتوى الترويجي
  • Milo: ودود ومحاور

تحديد اللغة الاختيارية

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

  • اللغات المدعومة تشمل العربية، الإنجليزية، الفرنسية، والألمانية.
  • اللغات غير المدعومة: الفيتنامية، الإندونيسية، التايلاندية، الأوكرانية، الرومانية، التشيكية، البنغالية.
  • إدخال لغة غير مدعومة قد يؤدي إلى نطق غير دقيق.

تنسيقات الصوت المدعومة

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

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

MP3 و WAV

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

OPUS و FLAC

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

PCM الخام

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

تنسيقات الصوت المدعومة

محددات السرعة والحدود

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

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

نطاق السرعة من 0.25 إلى 4.0

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

حد 4096 حرف لكل طلب

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

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

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

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

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

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

أخطاء المصادقة

عند استخدام مفتاح غير صالح أو منتهي الصلاحية، تُعاد استجابة HTTP 401. تأكد من أن المفتاح يبدأ بـ tts- وموجود في رأس الطلب Authorization: Bearer <key>.

أخطاء الحدود

يتم رفض الطلبات عند تجاوز حد 60 طلباً في الدقيقة. تُعاد استجابة HTTP 429 مع رأس Retry-After يحدد الوقت المطلوب للعودة. النص الذي يتجاوز 4096 حرفاً يُرفض مباشرة.

  • تجنب إعادة إرسال الطلب فوراً عند استقبال 429.
  • تأكد من تقسيم النصوص الطويلة قبل الإرسال.

إرجاع الرصيد في الفشل

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

نصائح للأداء

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

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

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

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

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

تُعالج الطلبات بالتتابع، مما يعني أن الطلبات الإضافية قد تنتظر دورها في الطابور عند الازدحام. الحد المسموح به هو 60 طلبًا في الدقيقة لكل مفتاح API (أو 10 طلبات في الدقيقة قبل أول إيداع). عند الطلبات المتعددة، قد يزداد وقت الاستجابة بشكل ملحوظ مقارنة بالنصوص القصيرة.

استخدام المسارات المتوازية

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

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

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

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

23 لغة

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

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

  1. Wikipedia
  2. Python documentation
  3. Node.js documentation
  4. TRON developer hub: TRC-20
  5. openai-node on GitHub
  6. IETF RFC 7845: Ogg Opus
  7. Tether (USDT)
  8. OpenAI API reference: create speech
  9. W3C WAI: making audio and video accessible
  10. Creative Commons Attribution 4.0
  11. LibriVox public-domain audiobooks
  12. ISO 639 language codes

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