دليل المطوّر: تكامل API لتحويل النص إلى كلام في تطبيقاتك (مع cURL و JS و Python)

كل TTS API تقريبا يتكون من: endpoint واحد (POST)، مصادقة (Bearer key)، وجسم JSON (نص + صوت + لغة/لهجة + صيغة) → بايتات صوت في الاستجابة (أو JSON لخطأ). الفرق بين المزودين: عمق التحكم (مشاعر، SSML، سرعة)، الصيغ المدعومة (MP3/WAV/PCM/OGG)، وحدود الطلب (طول النص، حجم العيّنة، timeout).

في 2026 ظهرت "بوّابات" مثل OpenRouter توحّد كل ذلك خلف مفتاح واحد: نفس Bearer key يعمل مع TTS (Gemini TTS)، وSTT (Whisper)، والاستنساخ — فتدير صوتك كاملاً من مكان واحد، مع fallback بين النماذج.

المثال معakiind (endpoint محلي عبر OpenRouter): POST /api/tts بجسم {text, voice, dialect, emotion, style, speed}. الرد: audio/mpeg (MP3) — تُحفظ مباشرة في ملف، وأخطاء JSON عند الفشل. لاحظ: المفتاح لا يظهر في المتصفح أبداً — الـ frontend يتحدث إلى backend الذي يضيف المفتاح server-side.

نمط التصميم الموصى به: `frontend → /api/tts (backend: يضيف المفتاح + يضيف الـ rate limit + يضيف الكاش) → OpenRouter → Gemini TTS`. أي أن "API الخاص بك" هو طبقة وسيطة رفيعة فوق المزود — وهذا ما يعطيك حرية تبديل المحرك (Gemini ↔ ElevenLabs ↔ Voxtral) دون لمس الواجهة.

في JS (Node/Deno/Edge): fetch مباشر مع بنية Buffer، أو OpenAI-compatible SDK بإشارة base_url إلى OpenRouter. في Python: requests أو openai SDK. النمطان متطابقان جوهرياً: POST + JSON + قراءة البايتات. أضف: (1) timeout (30–60s) و(2) retry واحد مع backoff و(3) فحص Status: إن لم يكن audio → فك JSON واعرض الخطأ.

للتطبيقات ذات الواجهة: لا ترسل المفتاح من المتصفح إطلاقاً — حتى لو "أخفيتَه" في كود مشفر، فهو قابل للاستخراج. الـ backend (Next.js route handler، serverless، أو أي server) هو المكان الوحيد للمفتاح.

الكاش: نفس النص + نفس الصوت + نفس الإعدادات = نفس البايتات 99% من الوقت. كاش (Redis/SQLite/حتى Map في الذاكرة) بمفتاح hash(text+voice+dialect+emotion+style+speed) يخفض التكلفة 40–80% في التطبيقات التكرارية (إشعارات، قوائم). النصوص الطويلة: قسّم عند حدود جملية (كل ~2,000 حرف) وتولّد بالتوازي ثم ادمج (أو اعتمد على تقسيم مزودك). Fallback: إذا فشل النموذج الأساسي (404/400/422)، جرّب نموذج بديل — وفيakiind هذا مفعّل تلقائياً (Gemini 3.1 ← 2.5).

إدارة التكلفة: احسب "التكلفة/دقيقة" لكل نغمة، وضبط rate limit لكل مستخدم، وسجّل usage (أغلب البوّابات تُرجع usage في الاستجابة أو في dashboard). وأضف "وضع معاينة" مجاني (صوت المتصفح أو عينة قصيرة) حتى لا ينفد رصيدك في الإغراءات.

قبل البوّابات: 3 مزودين (TTS + STT + Clone) = 3 مفاتيح، 3 فواتير، 3 بوابات خطأ، 3 حدود. مع OpenRouter: مفتاح واحد، فاتورة واحدة، وخط واحد من الكود يبدّل النموذج (غيّر model فقط). وتبقى ميزة إضافية: الاكتشاف — API واحد يسرد كل النماذج القادرة (output_modalities=speech / transcription) فتجرّب Voxtral وFish-Audio وGemini بنفس البنية.

النصيحة المعمارية: اجعل "اختيار النموذج" تهيئة (بيئة/قاعدة بيانات) لا كوداً — فالنماذج تتغير بسرعة، والفائز اليوم قد لا يكون فائز الغد.

(1) الحفظ بصيغة خاطئة: PCM بدون header لا يُسمع — اطلب دائماً MP3/WAV من البوابة (وليست PCM خاماً) أو أضف header. (2) CORS: إن استدعت مزوداً من المتصفح، فمعظمهم يرفض — مرّر عبر الـ backend. (3) timeout قصير: توليد 200 كلمة قد يأخذ 5–15 ثانية — اجعل 60s الحد. (4) إرسال SSML لمحرك لا يدعمه: بعض محركات 2026 تعتمد الوصف الطبيعي (وakiind يعالج الأوامر الأساسية داخلياً). (5) نسيان الـ X-Title/Referer: رؤوس تعريفية بسيطة تجعل نشاطك قابلاً للتعرف في dashboard المزود (ومفيدة عند فتح tickets).