---
title: وصفات الوكلاء
description: مسارات عمل حتمية لـ Claude وCodex ووكلاء البرمجة الآخرين.
---

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

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

## توليد ملف WAV

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

```bash
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` المؤقتة، اتبع [حدود الطلبات](/ar/docs/limits).

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

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

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/transcriptions" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -F model="arabic asr" \
  -F file=@recording.wav \
  -F response_format=json
```

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

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

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

1. أرسل طلب الأجزاء المتعددة في [استنساخ الصوت](/ar/docs/voice-cloning). يتطلب ملفاً مرجعياً واحداً واسماً و`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](https://api.sawtakarabi.ai/v1/openapi.json). استخدمه بدلاً من استنتاج الحقول أو القيم.