الصوت لعقلك الخاص

الإعداد

• أنشئ وكيلاً في Studio واختر صوته وقواعد نطقه، ثم من صفحته ← «شكل الرد» ← «من يكتب الردود؟» اختر «عقلك الخاص» (EXTERNAL_AGENT) وانشر. عندها لا يكتب صُرَد الردود، بل ينطق ما ترسله.
• الرموز والجلسات كما في صفحة الخادم: رمز جلسة من خادمك، ثم جلسة، ثم الطلبات أدناه.

نطق الرد

POST/api/v1/widget/conversations/{conversation_id}/turns

يعود الصوت كاملاً في audio.content_base64 (WAV)، ومعه هوية التنفيذ: identity.executed_profile_id وidentity.voice وidentity.transport. سجّلها مع قياساتك لتتأكد أن صوت وكيلك ثابت في كل طلب.

curl -X POST https://app.surad-ai.com/api/v1/widget/conversations/$CONVERSATION_ID/turns \
  -H "Authorization: Bearer $TOKEN" -H "Origin: https://app.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "tts_only",
    "ready_text": "أهلاً بك، طلبك وصلنا وراح نتواصل معك خلال ساعتين.",
    "idempotency_key": "turn-8f2c1"
  }'

البث: أول صوت خلال أقل من ثانية

بالبث يصل أول جزء من الصوت قرابة 0.6–0.7 ثانية على خوادمنا، بدل انتظار الرد كاملاً (3–4 ثوانٍ لرد من بضع جمل). يظل الطلب يعيد الصوت كاملاً عند انتهائه، فلا تشغّل النسختين معاً.

// 1) افتح قناة الأحداث مرة واحدة لكل محادثة (انظر صفحة الخادم لطريقة القراءة)
// 2) اطلب النطق مع البث
await fetch(API + '/api/v1/widget/conversations/' + conversationId + '/turns', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + token, Origin: ORIGIN, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    capability: 'tts_only',
    ready_text: reply,          // الرد كاملاً في طلب واحد
    idempotency_key: turnId,
    synthesis_transport: 'grpc_stream',
  }),
})
// 3) من قناة الأحداث:
//   audio.first   → payload: encoding LINEAR16, sample_rate_hz 24000, channels 1
//   audio.chunk   → payload.seq + payload.content_base64 (PCM16 خام) — شغّل فور الوصول بترتيب seq
//   audio.completed → انتهى صوت الدور

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

POST/api/v1/widget/conversations/{conversation_id}/voice/utterance

ترسل الصوت ملفاً في الحقل file، ويعود transcript.text لتمرره إلى عقلك. الأنسب: WAV أحادي 16kHz بترميز PCM16، حتى 4MB.

curl -X POST https://app.surad-ai.com/api/v1/widget/conversations/$CONVERSATION_ID/voice/utterance \
  -H "Authorization: Bearer $TOKEN" -H "Origin: https://app.example.com" \
  -F "file=@user.wav;type=audio/wav"
# الرد: { "transcript": { "text": "...", "provider": "...", "model": "..." }, ... }

لتجربة أسرع

• أرسل الرد كاملاً في طلب نطق واحد بدل جملة في كل طلب: البث يعطي أول صوت بسرعة، والطلب الواحد يحافظ على نبرة متصلة.
• افتح الجلسة عند تحميل الصفحة أو بداية المكالمة، لا عند أول جملة.
• إن كان بين المتصفح وصُرَد خادم وسيط، فمرّر أجزاء الصوت فور وصولها، دون تجميع أو إعادة ترميز.
• قِس من جهتك: لحظة الطلب، ووصول audio.first، وبدء التشغيل في المتصفح، ووصول audio.completed. وأرسل إلينا idempotency_key لكل دور لنطابقها مع توقيتاتنا.

إن تعذّر الصوت

إن تعذّر على صُرَد تحميل صوت وكيلك، يعود AUDIO_PRODUCTION_FAILURE (HTTP 502، قابل للإعادة) بدل النطق بصوت آخر. أعد المحاولة مرة واحدة، ثم اكتفِ بالنص.