تجريبي

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

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

الرابط الأساسي والمصادقة

أرسل مفتاح الواجهة مع كل طلب في ترويسة Authorization بصيغة Bearer. أنشئ حسابًا للحصول على واحد؛ يأتي مع ⁦$5⁩ من الرصيد ولا يتطلب بطاقة. تتطلب واجهتا الكلام والتفريغ مفتاح واجهة صالحًا.

https://api.sawtakarabi.ai/v1

Authorization: Bearer sk_ar_live_...

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

تحويل النص إلى كلام

POST /v1/audio/speech

modelstring

استخدم arabic tts مع حزم OpenAI.

inputstring

النص المراد نطقه. محسوب حسب الحرف.

voicestring

معرّف من صفحة الأصوات. اتركه فارغًا لاستخدام الصوت الافتراضي دون عينة مرجعية.

response_formatstring

يجب أن يكون "pcm"، PCM أحادي 16-بت خام هو الصيغة الوحيدة التي ننتجها.

sample_ratenumber

معدل إخراج اختياري بين 8000 و48000 هرتز. الافتراضي 24000 هرتز.

الحقل	النوع	ملاحظات
model	string	استخدم arabic tts مع حزم OpenAI.
input	string	النص المراد نطقه. محسوب حسب الحرف.
voice	string	معرّف من صفحة الأصوات. اتركه فارغًا لاستخدام الصوت الافتراضي دون عينة مرجعية.
response_format	string	يجب أن يكون "pcm"، PCM أحادي 16-بت خام هو الصيغة الوحيدة التي ننتجها.
sample_rate	number	معدل إخراج اختياري بين 8000 و48000 هرتز. الافتراضي 24000 هرتز.

curl --fail --show-error https://api.sawtakarabi.ai/v1/audio/speech \
  -H "Authorization: Bearer sk_ar_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"arabic tts","input":"مرحبا بك","voice":"9287b630-bc5f-574d-8c38-5f525c2b4ca3","response_format":"pcm"}' \
  --output speech.pcm

جسم الاستجابة هو صوت PCM خام أحادي القناة بدقة 16 بت وبترتيب Little-Endian، من دون ترويسة WAV. يعاد معدل الإخراج الفعلي في X-Sample-Rate؛ استخدم هذه القيمة لتشغيل الصوت بالسرعة الصحيحة.

تحويل الكلام إلى نص

POST /v1/audio/transcriptions

modelstring

استخدم arabic asr. هذا الحقل مطلوب في حزم OpenAI.

filemultipart

ملف صوتي أو فيديو. يجب أن يبقى طلب الرفع كاملًا ضمن 25 ميجابايت.

response_formatstring

اختياري: json (الافتراضي والمفضل) أو text. تُقبل verbose_json أيضًا، لكنها لا تضيف توقيت الكلمات أو المقاطع.

languagestring

رمز لغة BCP-47 اختياري. الافتراضي ar.

temperaturenumber

درجة عشوائية اختيارية. الافتراضي 0.

الحقل	النوع	ملاحظات
model	string	استخدم arabic asr. هذا الحقل مطلوب في حزم OpenAI.
file	multipart	ملف صوتي أو فيديو. يجب أن يبقى طلب الرفع كاملًا ضمن 25 ميجابايت.
response_format	string	اختياري: json (الافتراضي والمفضل) أو text. تُقبل verbose_json أيضًا، لكنها لا تضيف توقيت الكلمات أو المقاطع.
language	string	رمز لغة BCP-47 اختياري. الافتراضي ar.
temperature	number	درجة عشوائية اختيارية. الافتراضي 0.

جهّز تسجيلًا يحتوي على كلام عربي واضح، واستبدل meeting.wav في المثال بمسار ملفك. يُرفع الملف بصيغة multipart؛ لا ترسله داخل JSON ولا تضبط فاصل multipart يدويًا.

curl --fail --show-error https://api.sawtakarabi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk_ar_live_..." \
  -F model="arabic asr" \
  -F [email protected] \
  -F response_format=json

مثال على استجابة JSON

{
  "text": "النص المكتوب",
  "usage": { "type": "duration", "seconds": 42 }
}

تُحتسب التكلفة بعد معالجة الصوت وفق المدة في usage.seconds. يجب أن يكفي الرصيد لمعالجة الملف قبل بدء الطلب.

تتضمن استجابة json التفريغ في الحقل text، وبيانات الاستخدام عندما تعيدها خدمة التفريغ. أما response_format=text فيعيد نصًا مباشرًا دون كائن usage. لا تتضمن الصيغتان أسماء المتحدثين أو توقيت الكلمات.

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

الأصوات

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

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

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

الحدود

requests600 / min

الحد الافتراضي لكل حساب، مشترك بين مفاتيحه.

concurrency5

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

upload25 MB

الحد الأقصى لجسم طلب التفريغ، بما يشمل بيانات رفع الملف.

الحقل	النوع	ملاحظات
requests	600 / min	الحد الافتراضي لكل حساب، مشترك بين مفاتيحه.
concurrency	5	الحد الافتراضي للطلبات الجارية بالتزامن لكل حساب.
upload	25 MB	الحد الأقصى لجسم طلب التفريغ، بما يشمل بيانات رفع الملف.

الأخطاء

ابدأ برمز حالة HTTP. تتضمن أخطاء البوابة عادةً رسالة detail داخل JSON، وترويسة X-Error-Code لسبب الخطأ البرمجي، وترويسة X-Request-Id لتحديد الطلب. قد لا تتوفر هذه البيانات عند انقطاع الاتصال أو صدور الخطأ من خادم وسيط.

الحالة	المعنى
400	بيانات طلب غير صالحة، أو صيغة استجابة غير مدعومة، أو قيمة صوت غير مقبولة.
401	مفتاح واجهة برمجية مفقود أو مُلغي أو غير معروف.
402	رصيد مدفوع مقدمًا غير كافٍ للطلب.
404	معرّف الصوت غير موجود أو غير متاح لحسابك.
413	حجم الطلب يتجاوز حد الواجهة. قلّل حجم الملف أو النص قبل إعادة المحاولة.
429	تجاوزت حد معدل الطلبات أو عدد الطلبات المتزامنة. انتظر وأعد المحاولة، مع زيادة مدة الانتظار تدريجيًا.
502	تعذّر على البوابة إكمال الطلب مع خدمة الصوت. انتظر قبل إعادة المحاولة.
503	لا تتوفر سعة حاليًا. أعد المحاولة بعد قليل.

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

عالج مشكلة البيانات أو المفتاح أو الرصيد أولًا عند ظهور 400 أو 401 أو 402 أو 404 أو 413. عند 429 أو 502 أو 503، أعد المحاولة عددًا محدودًا من المرات مع زيادة الانتظار تدريجيًا، وتجنب تشغيل محاولات متوازية. إذا انقطع الاتصال بعد الإرسال، فقد تكون نتيجة الطلب غير معروفة؛ وقد يؤدي إرساله مجددًا إلى توليد جديد وتكلفة جديدة.

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

التكلفة

تحويل النص إلى كلام: ⁦$50⁩ لكل مليون حرف
تحويل الكلام إلى نص: ⁦$0.50⁩ لكل ساعة صوت

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