البدء السريع

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

اضبط هذين المتغيرين مرة واحدة قبل تشغيل الأمثلة:

export SAWTAK_API_BASE_URL="https://api.sawtakarabi.ai/v1"
export SAWTAK_API_KEY="<API_KEY>"

1. إنشاء مفتاح API

تتطلب الطلبات رمز حامل (Bearer token) يُمرر في ترويسة Authorization.

• لتحويل النص إلى كلام، يجب أن يتضمن مفتاح API نطاق tts.
• لاستعراض دليل الأصوات، يجب أن يتضمن مفتاح API نطاق voices.

مرر المفتاح عبر متغير البيئة SAWTAK_API_KEY في ترويسة الطلب:

-H "Authorization: Bearer $SAWTAK_API_KEY"

2. اختيار الصوت

استعرض دليل الأصوات المتاحة بإرسال طلب GET $SAWTAK_API_BASE_URL/voices:

curl --fail --show-error "$SAWTAK_API_BASE_URL/voices" \
  -H "Authorization: Bearer $SAWTAK_API_KEY"

تُعيد الواجهة غلاف قائمة (object: "list") يضم كائنات الأصوات في مصفوفة data. يتضمن كل عنصر معرّف الصوت (id) والاسم (name) والحالة (status) والتصنيفات (labels) مثل اللهجة (dialect) والنوع (gender).

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

3. إرسال طلب تحويل النص إلى كلام

أرسل طلب POST إلى $SAWTAK_API_BASE_URL/audio/speech محددًا النموذج والنص وتنسيق الاستجابة المطلوب:

curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/speech" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arabic-tts-1",
    "input": "مرحبا بك",
    "response_format": "wav"
  }' \
  --output speech.wav

لتحديد صوت معين من الدليل، أضف خاصية voice مع قيمة id الخاصة بذلك الصوت.

4. تشغيل الصوت أو حفظه

تبث نقطة النهاية البيانات الصوتية مباشرة في الملف المحدد عبر الخيار --output:

• صيغة WAV (response_format: "wav"): تُرفق البوابة ترويسة RIFF/WAV قياسية مع الدفق الصوتي (audio/wav). يمكنك تشغيل الملف فورًا عبر سطر الأوامر:

  afplay speech.wav

  أو على أنظمة Linux:

  aplay speech.wav

• صيغة PCM (response_format: "pcm"): تبث البوابة دفق PCM خام بعمق 16 بت (audio/pcm). احفظ الدفق في speech.pcm عند التكامل مع أنظمة معالجة تقبل PCM المباشر الخالي من الترويسات.

5. استجابات الفشل المدعومة

تتبع استجابات الأخطاء غلاف أخطاء متوافق مع مواصفات OpenAI يحتوي على message وtype وcode وparam وrequest_id.

صوت غير معروف (400 Bad Request)

تؤدي كتابة معرّف صوت غير موجود إلى إرجاع خطأ من نوع invalid_request_error مع الرمز bad_voice:

{
  "error": {
    "message": "Unknown voice 'unknown-voice-id'. `voice` must be one of your voice ids from /v1/voices; omit it for the default voice.",
    "type": "invalid_request_error",
    "code": "bad_voice",
    "param": null,
    "request_id": null
  }
}

نطاق الصلاحيات غير كافٍ (403 Forbidden)

يؤدي استخدام مفتاح يفتقر إلى نطاق tts المطلوب إلى إرجاع خطأ من نوع permission_error:

{
  "error": {
    "message": "Insufficient scope",
    "type": "permission_error",
    "code": "insufficient_scope",
    "param": null,
    "request_id": null
  }
}

فشل المصادقة (401 Unauthorized)

يؤدي حذف رمز التفويض أو إرسال مفتاح غير صالح إلى إرجاع خطأ من نوع authentication_error:

{
  "error": {
    "message": "Authentication failed",
    "type": "authentication_error",
    "code": "auth_failed",
    "param": null,
    "request_id": null
  }
}