توثيق الواجهة البرمجية

البداية السريعة

ثلاث خطوات وتسمع أول رد سعودي من خبير.

1.أنشئ مفتاحًا
من لوحة التحكم ← الواجهة البرمجية. المفتاح يظهر مرة واحدة فقط.
2.ارسل طلبك الأول
نقطة توليد الصوت ترجّع WAV بترميز base64 جاهز للتشغيل.
3.راقب استهلاكك
كل رد يحمل credits_used، ونقطة الرصيد تعطيك المتبقي لحظيًا.

export KHABEER_KEY="5abear_sk_..."

curl -X POST https://speak-saudi-ai.lovable.app/api/public/v1/tts \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"هلا والله، حياك الله في متجرنا","voice":"noura"}' \
  | jq -r .audio | base64 -d > reply.wav

الأمان

المصادقة

كل طلب يحمل مفتاحك في ترويسة Authorization. نخزّن بصمة المفتاح فقط (SHA-256) — لو ضاع، ألغه وأنشئ غيره فورًا.

نادِ الواجهة من خادمك، لا تضع المفتاح في كود المتصفح أو التطبيق.
استخدم مفتاحًا مستقلًا لكل نظام حتى تلغيه وحده عند الحاجة.
المفاتيح مربوطة بحسابك، والاستهلاك يُخصم من رصيد الحساب نفسه.

header

Authorization: Bearer 5abear_sk_xxxxxxxxxxxxxxxx
Content-Type: application/json

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "مفتاح غير صالح أو ملغى."
  }
}

POST/v1/tts

توليد صوت سعودي

نص عربي ← صوت سعودي طبيعي بصيغة WAV 24kHz، مع اختيار الصوت واللهجة والسرعة.

المعاملات

textstringمطلوب

النص المطلوب نطقه (١–٤٠٠٠ حرف).

voicestringاختياري

معرّف الصوت: noura، sara، dana، fahad، abdullah، khalid. الافتراضي "noura".

accentstringاختياري

ملف اللهجة: aam (عام)، najdi، hijazi، sharqawi.

speednumberاختياري

سرعة الإلقاء بين 0.7 و 1.6.

format"json" | "wav"اختياري

json يرجّع base64، وwav يرجّع بايتات الصوت مباشرة.

استخدم format: "wav" إذا كنت تبثّ الصوت مباشرة للعميل — يوفّر خطوة فك الترميز.

curl -X POST https://speak-saudi-ai.lovable.app/api/public/v1/tts \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "طلبك جاهز، يوصلك خلال نص ساعة",
    "voice": "fahad",
    "accent": "najdi",
    "speed": 1.05,
    "format": "wav"
  }' --output reply.wav

POST/v1/stt

تفريغ الكلام السعودي

ملف صوت ← نص عربي. يقبل multipart أو JSON بترميز base64، والحد ٢٥ ميجابايت.

المعاملات

filebinaryمطلوب

ملف الصوت عند استخدام multipart/form-data.

audiostringاختياري

بديل: الصوت بترميز base64 داخل JSON.

mime_typestringاختياري

نوع الصوت مع audio، الافتراضي "audio/wav".

hintsstring[]اختياري

كلمات سعودية ترفع الدقة: أسماء أحياء، أصناف، علامات تجارية.

curl -X POST https://speak-saudi-ai.lovable.app/api/public/v1/stt \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -F "file=@call.wav" \
  -F "hints=البيك,العليا,هنقرستيشن"

POST/v1/chat

محادثة مع مساعدك

رسالة نصية ← رد سعودي بالنص والصوت، بمعرفة نشاطك وقاموس نطقك وكشف طلب التحويل للموظف.

المعاملات

agent_iduuidمطلوب

معرّف المساعد من لوحة التحكم.

messagestringمطلوب

رسالة العميل (١–٢٠٠٠ حرف).

historymessage[]اختياري

آخر ٣٠ رسالة بصيغة { role, content } لحفظ السياق.

audiobooleanاختياري

توليد صوت للرد، الافتراضي true.

handoff: true معناها العميل يطلب موظفًا بشريًا — حوّل المكالمة عندك مباشرة.

curl -X POST https://speak-saudi-ai.lovable.app/api/public/v1/chat \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "0f2c1f8e-...",
    "message": "وش أوقات الدوام عندكم؟",
    "history": [{"role":"user","content":"السلام عليكم"}],
    "audio": true
  }'

GET/v1/voices

قائمة الأصوات واللهجات

الأصوات السعودية المتاحة وملفات اللهجة (عام، نجدي، حجازي، شرقاوي).

ما يحتاج أي معاملات — فقط ترويسة المفتاح.

curl https://speak-saudi-ai.lovable.app/api/public/v1/voices \
  -H "Authorization: Bearer $KHABEER_KEY"

الأصوات المتاحة

nouraنورةسعودي عامهلا والله، حياك الله. كيف أقدر أخدمك؟

saraسارةحجازيأهلين فيك! وش حاب تطلب اليوم؟

danaدانةسعودي عامتمام، أكدنا لك الحجز. يعطيك العافية.

fahadفهدنجديأبشر، خلني أتأكد لك من طلبك.

abdullahعبداللهشرقاويما عليك، أنا معك خطوة بخطوة.

khalidخالدحجازيطلبك بيكون عندك إن شاء الله خلال نص ساعة.

GET/v1/usage

الرصيد والاستهلاك

رصيد الباقة والرصيد المشترى وآخر ٢٠ عملية استهلاك على حسابك.

ما يحتاج أي معاملات — فقط ترويسة المفتاح.

curl https://speak-saudi-ai.lovable.app/api/public/v1/usage \
  -H "Authorization: Bearer $KHABEER_KEY"

الأخطاء

كل خطأ يرجع بنفس الشكل مع رمز HTTP مناسب، وبرسالة عربية جاهزة للعرض.

401

unauthorized

مفتاح ناقص أو ملغى — تحقق من الترويسة.

400

invalid_request

حقول ناقصة أو خارج الحدود المسموحة.

402

insufficient_credits

خلص الرصيد — رقِّ الباقة أو اشترِ رصيدًا.

404

not_found

المساعد مو تابع لحسابك.

413

invalid_request

حجم الملف تجاوز ٢٥ ميجابايت.

429

rate_limited

ضغط عالي — أعد المحاولة بعد قليل.

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "خلص رصيد الكريدت."
  }
}

استهلاك الكريدت

كل رد من الواجهة يحمل credits_used حتى تراقب الاستهلاك لحظيًا.

توليد صوت

كريدت لكل حرف

تفريغ كلام

١٬٠٠٠

كريدت للدقيقة

دور محادثة

٥٬٠٠٠

كريدت لكل رد

شوف الباقات وأسعار الرصيد

جاهز تبدأ؟

أنشئ مفتاحك الآن وابدأ تخلي أنظمتك تتكلم سعودي — نفس الصوت اللي يسمعه عميلك في المكالمة.

أنشئ مفتاحك الأسعار