وصفات الوكلاء

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

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

توليد ملف WAV

الهدف: إنشاء ملف WAV عربي قابل للتشغيل من نص.

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

file speech.wav

تكتمل المهمة عندما: ينجح الطلب ويعرّف file speech.wav الملف على أنه صوت WAV. لا تُعد 400 أو 401 أو 402 أو 403 من دون تغيير. للاستجابات 429 و5xx المؤقتة، اتبع حدود الطلبات.

تفريغ ملف صوتي

الهدف: طباعة تفريغ عربي من ملف صوتي محلي.

curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -F model="arabic asr" \
  -F [email protected] \
  -F response_format=json

تكتمل المهمة عندما: تحتوي استجابة JSON على text. احتفظ بالملف الأصلي دون تغيير حتى يمكن تشخيص الرفع الفاشل أو إعادة محاولته بأمان.

استنساخ صوت وانتظار جاهزيته

الهدف: الحصول على معرّف صوت خاص جاهز لاستخدامه لاحقاً في التوليد.

1. أرسل طلب الأجزاء المتعددة في استنساخ الصوت. يتطلب ملفاً مرجعياً واحداً واسماً وlabels بصيغة JSON يتضمن dialect.
2. احفظ id المُعاد.
3. استطلع GET /v1/voices/{id} بمفتاح Bearer نفسه حتى تصبح status هي ready.
4. استخدم المعرّف في voice ضمن طلب تحويل النص إلى كلام.

تكتمل المهمة عندما: تعرض استجابة الصوت status: "ready". لا تستبدل الصوت بصوت مختلف عند بقاء الاستنساخ قيد المعالجة أو فشله.

تشخيص طلب فاشل

الهدف: اختيار الإجراء الآمن التالي من فشل الواجهة.

1. اقرأ حالة HTTP وerror.code.
2. احفظ request_id عند وجوده.
3. صحّح الإدخال عند 400، واستبدل بيانات الاعتماد عند 401، وأضف رصيداً عند 402، واستخدم مفتاحاً بالنطاق المطلوب عند 403.
4. عند 429، انتظر Retry-After واستخدم تراجعاً أسياً محدوداً مع قدر عشوائي صغير.
5. أعد فقط العمل القابل للإعادة بعد 5xx مؤقت؛ وتجنب تكرار طلب إنشاء صوت.

العقد الآلي المرجعي هو OpenAPI v1. استخدمه بدلاً من استنتاج الحقول أو القيم.