توثيق واجهة برمجة التطبيقات لتحويل النص إلى صوت

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

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

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

توثيق واجهة برمجة التطبيقات لتحويل النص إلى صوت

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

ما هو رابط واجهة برمجة التطبيقات؟

الرابط الأساسي هو https://api.td555.info/v1. يتم إرسال طلبات توليد الصوت عبر POST إلى https://api.td555.info/v1/audio/speech. يمكنك استخدام هذا الرابط مع مكتبات OpenAI أو عبر HTTP مباشرة، مع تعديل base_url ليتوافق مع هذا النطاق.

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

سجّل حسابك عبر صفحة /get-api-key/ باستخدام حساب Google أو البريد الإلكتروني وكلمة المرور. بعد التسجيل، ستظهر لك صفحة تحتوي على مفتاح API الخاص بك، رصيدك، وعدد الأحرف المتاحة، بالإضافة إلى مثال curl جاهز للاستخدام.

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

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

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

نعم، يمكنك استخدام مكتبات OpenAI الرسمية. فقط قم بتغيير base_url إلى https://api.td555.info/v1 واستخدم مفتاح API الخاص بنا. الواجهة تتوافق مع شكل طلبات endpoint الصوت في OpenAI، مما يسهل التكامل مع أنظمتك الحالية.

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

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

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

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

كيف أعالج النصوص الطويلة جدًا؟

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

ما هو رمز المصادقة المطلوب؟

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

هل يمكنني تغيير مفتاح API الخاص بي؟

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

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

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

هل يتم دعم اللغة العربية في الطلب؟

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

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

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

هل هناك فرق بين النموذجين tts-1 و tts-1-hd؟

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

ما هي الصيغة المفضلة للمشاريع السياحية؟

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

الطلب الأول

curl

curl https://api.td555.info/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.td555.info/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.td555.info/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 خاص لحسابك في td555.info لإرسال الطلبات.

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

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

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

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

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

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

يمكنك التسجيل باستخدام Google للحصول على تجربة مجانية بقيمة 0.50 دولار (حوالي 50,000 حرف) سارية لمدة 7 أيام. الحسابات المسجلة بالبريد الإلكتروني تبدأ بدون رصيد تجريبي.

تجربة أول طلب

أرسل طلب POST إلى الرابط https://api.td555.info/v1/audio/speech مع نصك ومفتاحك. ستتلقى ملف صوتي فورًا. النصوص الطويلة تقسم تلقائيًا وتدمج.

هيكلية الطلب

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

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

يتم استخدام طريقة HTTP POST فقط لإرسال البيانات، مما يضمن إرسال الطلبات بشكل آمن ومنظم. كل طلب يتكون من جسم JSON يحتوي على المعلمات الضرورية لتوليد الصوت المطلوب بدقة.

رابط الواجهة الرئيسي

القاعدة الأساسية للواجهة هي https://api.td555.info/v1. يتم استخدام هذا الرابط مع نقطة النهاية /audio/speech لإنشاء الملفات الصوتية.

طريقة HTTP المطلوبة

يجب استخدام طريقة POST في الطلبات HTTP. هذا يضمن إرسال حجم البيانات المطلوب (النصوص) إلى الخادم بشكل صحيح دون قيود طول URL.

هيكلية JSON للبيانات

يتطلب الجسم JSON الحقول التالية: model (tts-1 أو tts-1-hd)، input (النص، حتى 4096 حرفًا)، voice (أحد الأصوات الثمانية)، response_format (mp3، wav، opus، flac، pcm)، وspeed (0.25–4.0). حقل language اختياري لتحديد اللغة بدقة.

المعلمات الأساسية

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

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

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

تحديد النموذج الصوتي

يحدد حقل model محرك التوليد المستخدم، حيث يدعم النظام خيارين: tts-1 وtts-1-hd. كلا النموذجين يستخدمان نفس المحرك الأساسي ونفس التسعرة ($0.01 لكل 1000 حرف)، مما يعني أن الاختيار بينهما يعتمد فقط على تفضيل الجودة الصوتية دون تأثير على التكلفة.

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

إدخال النص المطلوب

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

  • الحد الأقصى: 4096 حرفًا.

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

يتم تحديد صوت المتكلم عبر حقل voice الذي يقبل أحد الثمانية أ presets المحددة (مثل aria، nova، atlas). يدعم النظام 23 لغة، ويمكن تحديد لغة النص صراحةً عبر حقل language باستخدام رمز ISO لمنع التخمين التلقائي الخاطئ، خاصة للنصوص غير الإنجليزية.

  • 8 أصوات متاحة.

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

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

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

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

صيغة MP3 الشائعة

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

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

  • حجم ملف صغير نسبيًا
  • توافق واسع مع جميع المتصفحات

صيغة WAV عالية الجودة

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

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

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

الصيغ الأخرى المتاحة

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

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

ملاحظة: لا توجد ميزات إضافية مثل تعديل السرعة داخل الملف نفسه، بل يتم ضبطها أثناء الطلب.

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

استخدام مكتبات OpenAI

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

تتطلب واجهة برمجة التطبيقات تعديل الرابط الأساسي في إعدادات مكتبة OpenAI إلى https://api.td555.info/v1. بعد هذا التعديل، تعمل المكتبات الرسمية بتوافق كامل مع الواجهة، مما يسمح باستخدام نفس أسلوب الاتصال المعتمد في خدمات OpenAI.

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

تعديل رابط الواجهة الأساسي

قم بتعيين متغير البيئة OPENAI_BASE_URL أو معلمة base_url في كائن العميل إلى https://api.td555.info/v1. هذا يوجه جميع الطلبات إلى خادمنا بدلاً من خوادم OpenAI.

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

استخدام SDK الرسمي

استخدم الحزمة openai القياسية بلغة Python أو أي لغة تدعم SDK. حدد المسار /v1/audio/speech لإرسال النص وتلقي ملف الصوت.

يتم التعامل مع المصادقة عبر إرسال مفتاح API في رأس الطلب Authorization. لا حاجة لتثبيت حزم إضافية غير المكتبة الرسمية.

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

توافق المكتبات

مكتبات OpenAI متوافقة مع واجهتنا. يدعم هذا التوافق النماذج tts-1 وtts-1-hd بنفس صيغة البيانات المتوقعة.

يمكنك استخدام نفس كود الاختبار الذي يعمل مع OpenAI، مع ضمان عمل جميع الصيغ الصوتية المدعومة (mp3, wav, opus, flac, pcm).

استخدام مكتبات OpenAI

معالجة الأخطاء والحدود

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

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

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

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

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

  • 60 طلب/دقيقة (مفاتيح نشطة)
  • 10 طلبات/دقيقة (قبل الإيداع)
  • تأخير طفيف تحت الضغط

معالجة النصوص الطويلة

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

  • حد 4096 حرف/طلب
  • الفاصل والشرطتان يحسبان كحرف
  • الدمج اليدوي مطلوب

رموز الحالة الشائعة

تعود الأخطاء الشائعة بـ 401 (مفتاح غير صالح أو منتهي الصلاحية)، 429 (تجاوز الحدود)، أو 422 (خطأ في التنسيق أو الحرف الزائد) أو أخطاء أخرى.

  • 401: خطأ المصادقة
  • 429: تجاوز الحد
  • 422: خطأ في الإدخال

الأمان والمصادقة

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

يستخدم مفتاح API الخاص بك للمصادقة مع الخادم عبر رأس Authorization: Bearer tts-.... يوجد مفتاح نشط واحد فقط لكل حساب، وهو المسؤول عن جميع الطلبات وإصدار الفواتير.

يتم إصدار المفتاح عند إنشاء الحساب في صفحة /get-api-key/. يُستخدم هذا المفتاح لتأمين الاتصال بين واجهة برمجة التطبيقات الخاصة بنا وتطبيقاتك.

هوية مفتاح API

يتم تحديد هوية كل حساب عبر مفتاح فريد يبدأ بـ tts-. يجب إرسال هذا المفتاح في رأس الطلب كجزء من قيمة Bearer.

  • يوجد مفتاح واحد نشط لكل حساب.
  • يظهر المفتاح في لوحة التحكم الخاصة بك.

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

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

إلغاء المفتاح القديم

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

أمثلة على الأكواد

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

تتضمن هذه الأمثلة كيفية إرسال النصوص واستقبال الملفات الصوتية عبر البروتوكول القياسي. يمكنك استخدام أي بيئة تدعم HTTP/HTTPS مع مفتاح API الخاص بك.

الأمثلة تغطي السيناريوهات الأساسية: توليد صوت فوري، وتعديل الرابط الأساسي للعمل مع مكتبات OpenAI المعروفة.

مثال cURL مباشر

إرسال طلب POST مباشر إلى نقطة النهاية باستخدام curl مع تحديد النموذج والصوت والصيغة:

curl -X POST "https://api.td555.info/v1/audio/speech" \ -H "Authorization: Bearer tts-your-key" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "مرحباً بكم في المتحف", "voice": "sage", "response_format": "mp3"}' \ -o output.mp3

مثال Python باستخدام OpenAI

استخدام مكتبة openai مع تعديل الرابط الأساسي للعمل مع الواجهة:

import openai client = openai.OpenAI(api_key="tts-your-key", base_url="https://api.td555.info/v1") with client.audio.speech.create( model="tts-1", voice="nova", input="مرحباً بكم في المعرض السياحي", response_format="mp3" ) as response: response.stream_to_file("audio.mp3")

مثال JavaScript بسيط

إرسال الطلب باستخدام fetch في بيئة المتصفح أو الخادم:

fetch("https://api.td555.info/v1/audio/speech", { method: "POST", headers: { "Authorization": "Bearer tts-your-key", "Content-Type": "application/json" }, body: JSON.stringify({ model: "tts-1-hd", voice: "felix", input: "تاريخ المدينة يعود للقرن الثامن" }) }) .then(res => res.blob().then(b => { const u = URL.createObjectURL(b); console.log(u); }));

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

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

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

23 لغة

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

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

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

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