المرجع

ما تحتاجه أثناء البناء: شكل الأخطاء ورموزها، ونطاقات المفاتيح، والحدود، وصيغ الصوت، وروابط العقد الكامل.

الأخطاء

كل خطأ بالشكل نفسه. الرسالة في مسارات الجلسات عربية قابلة للعرض للمستخدم مباشرة، وrequest_id يربط الطلب بسجلاتنا (ويعود أيضاً في ترويسة X-Request-ID).

JSON

{
  "error": {
    "code": "ORIGIN_DENIED",
    "message": "هذا الموقع غير مصرّح له باستخدام المساعد.",
    "request_id": "7ef58a6c4817476f88141957853400a7"
  }
}

الرمز	HTTP	يُعاد؟	المعنى وما تفعله
AUTH_FAILED	401	لا	الرمز مفقود أو غير صالح، أو معرّف التضمين غير صحيح.
TOKEN_EXPIRED	401	لا	انتهت مدة رمز الجلسة. اطلب رمزاً جديداً وافتح جلسة بنفس conversation_id.
ORIGIN_DENIED	403	لا	النطاق غير مسجل، أو لا يطابق النطاق الذي صدر له الرمز.
TENANT_MISMATCH	403	لا	الجلسة لا تتبع هذه المساحة.
TOKEN_REPLAYED	409	لا	الرمز فتح جلسة من قبل. كل رمز يفتح جلسة واحدة.
IDEMPOTENCY_CONFLICT	409	لا	المفتاح نفسه وصل بمحتوى مختلف.
STALE_GENERATION	409	لا	رد قديم تُجوهل بعد مقاطعة أو إيقاف.
CONVERSATION_NOT_FOUND	404	لا	المحادثة غير موجودة أو انتهت. افتح جلسة جديدة.
NO_PUBLISHED_AGENT	404	لا	الوكيل غير منشور، أو التضمين غير مفعّل في المراجعة المنشورة.
VALIDATION_FAILED	422	لا	الطلب ناقص أو غير صالح.
AUDIO_EMPTY	400	لا	ملف الصوت فارغ أو غير صالح.
RATE_LIMITED	429	نعم	تجاوزت حد الاستخدام. أعد المحاولة بعد لحظات.
BUDGET_EXHAUSTED	429	لا	انتهت الحصة المخصصة.
AUDIO_PRODUCTION_FAILURE	502	نعم	تعذّر إنتاج الصوت (ومنه تعذّر تحميل صوت الوكيل). أعد مرة، ثم اكتفِ بالنص.
INTERNAL	500	لا	خطأ غير متوقع. أرسل request_id إلى الدعم.

نطاقات مفاتيح API

تختار النطاقات عند إنشاء المفتاح. امنح المفتاح أقل ما يحتاجه.

الحقل	النوع	الوصف
`sessions.create`	scope	إصدار رموز الجلسات (الاستخدام الأساسي لخادم موقعك).
`sessions.stream`	scope	قنوات البث للجلسات.
`speech.transcribe`	scope	تحويل الكلام إلى نص.
`speech.synthesize`	scope	نطق النصوص.
`agents.read`	scope	قراءة الوكلاء وسجل المحادثات.
`agents.manage`	scope	إدارة الوكلاء وتشغيلهم.
`tools.ack`	scope	تأكيد نتائج الأدوات.
`usage.read`	scope	قراءة الاستخدام.

الحدود

الحقل	النوع	الوصف
`رمز الجلسة`	60–3600 s	الافتراضي 900 ثانية. رمز التضمين العام 600 ثانية.
`جلسات التضمين العام`	rate	20 لكل زائر كل 10 دقائق، و600 لكل وكيل في الساعة.
`مفتاح API`	rpm	الافتراضي 120 طلباً في الدقيقة، ويُضبط لكل مفتاح.
`رفع الصوت`	4 MB	حد ملف الرسالة الصوتية.
`تسجيل الويدجت`	30 s	أقصى مدة للرسالة الصوتية من الويدجت.
`سجل المحادثات`	≤ 100	محادثات في الصفحة الواحدة.

صيغ الصوت

الحقل	النوع	الوصف
`إلى صُرَد`	WAV	الأنسب: أحادي، 16kHz، PCM16.
`من صُرَد (كامل)`	WAV	في audio.content_base64.
`من صُرَد (بث)`	PCM16	أجزاء خام في audio.chunk: LINEAR16، 24kHz، أحادي، بترتيب seq.

كل دور منطوق يعيد ما نُفّذ فعلاً، لتتحقق من ثبات صوت وكيلك: identity.voice_profile_id أو identity.executed_profile_id، وaudio.voice، وidentity.transport. وإن طلبت صوتاً لا يمكن تحميله يعود خطأ صريح، ولا يُنطق الرد بصوت آخر.

منع التكرار

أرسل idempotency_key فريداً لكل دور. إن أعدت الطلب بعد انقطاع الشبكة بالمفتاح نفسه يعود الرد نفسه دون تنفيذ ثانٍ أو دفع صوت مرتين. وبعد إيقاف الرد لا يُعاد صوته القديم.

العقد الكامل والأدوات

OpenAPI (حي، يطابق الإنتاج دائماً): https://app.surad-ai.com/api/v1/developer-kit/v1/openapi.json
حزمة المطور (أمثلة curl وNode وPython وLaravel وWordPress، ومجموعة Postman، وحزم SDK): https://app.surad-ai.com/api/v1/developer-kit/v1
لوكلاء البرمجة بالذكاء الاصطناعي: /llms.txt و/llms-full.txt