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

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

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

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خالدحجازيطلبك بيكون عندك إن شاء الله خلال نص ساعة.

mutlaqمطلقبدويهلا وغلا، حيّاك الله يا طويل العمر.

moudiموضيبدويحيّاك الله يا ولدي، قل وش تبي وأنا بخدمتك.

GET/v1/usage

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

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

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

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

WS/v1/listen

التفريغ المباشر (WebSocket)

افتح قناة WebSocket وأرسل صوت PCM 16-bit مباشرة، وتستقبل نتائج مبدئية أثناء الكلام ونتيجة نهائية عند سكوت المتحدث — مع توقيت الكلمات ودرجة الثقة. الخصم لكل ثانية صوت، وإذا خلص الرصيد يُغلق الاتصال برسالة واضحة.

المعاملات

tokenqueryمطلوب

مفتاح الواجهة (بدل ترويسة Authorization لأن المتصفح ما يرسل ترويسات مع WebSocket).

sample_ratequeryاختياري

تردد العينة المرسل. الافتراضي 16000.

accentqueryاختياري

ملف اللهجة: aam | najdi | hijazi | sharqawi.

hintsqueryاختياري

كلمات مساعدة مفصولة بفاصلة (أسماء منتجات، مدن، مصطلحات).

interimqueryاختياري

false يوقف النتائج المبدئية ويرسل النهائية فقط.

endpoint_msqueryاختياري

مدة السكوت التي تنهي الجملة بالمللي ثانية. الافتراضي 700.

أكواد الإغلاق: 4001 مفتاح غير صالح · 4002 صيغة صوت غير مدعومة · 4003 خلص الرصيد · 4029 تجاوزت حد التزامن · 4500 خطأ داخلي.

# WebSocket — استخدم أي عميل ws
websocat "wss://speak-saudi-ai.lovable.app/api/public/v1/listen?token=$KHABEER_KEY&sample_rate=16000&accent=najdi"

POST/v1/tts-stream

النطق المباشر (Streaming)

نفس محرك النطق لكن عينات PCM توصلك فور توليدها عبر SSE. شغّل كل audio_delta عند وصوله ولا تنتظر حدث chunk أو done.

المعاملات

textstringمطلوب

النص المطلوب نطقه (حتى ٨٠٠٠ حرف).

voicestringاختياري

معرّف الصوت أو صوت مستنسخ clone_xxx. الافتراضي noura.

accentstringاختياري

ملف اللهجة.

speednumberاختياري

من 0.7 إلى 1.6.

curl -N https://speak-saudi-ai.lovable.app/api/public/v1/tts-stream \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"هلا والله، معك خبير.","voice":"noura"}'

POST/v1/analyze

تحليل المحادثة

أرسل مقطعًا صوتيًا أو نصًا، واطلب ما تحتاجه: فصل المتحدثين، نبرة العميل، الكلمات المفتاحية، ملخص، محضر اجتماع بقرارات ومهام، أو ترجمة.

المعاملات

audio | audio_url | file | textmixedمطلوب

المصدر: ملف multipart، أو base64، أو رابط، أو نص جاهز.

featuresstring[]اختياري

diarization · sentiment · keywords · summary · minutes · translation. الافتراضي summary.

target_languagestringاختياري

لغة الترجمة عند طلب translation (مثال: en).

curl https://speak-saudi-ai.lovable.app/api/public/v1/analyze \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -F file=@call.wav \
  -F "features=diarization,sentiment,summary"

POST/v1/transcribe-async

تفريغ الملفات الطويلة

للتسجيلات الطويلة (اجتماع أو مكالمة كاملة حتى ١٠٠ ميجابايت): ترسل الملف وترجع لك مهمة فورًا، وتتابعها بالاستعلام أو نخبرك عبر callback موقّع.

المعاملات

file | audio | audio_urlmixedمطلوب

التسجيل المراد تفريغه.

featuresstring[]اختياري

نفس ميزات /analyze تُنفَّذ على التفريغ مباشرة.

hintsstring[]اختياري

كلمات مساعدة لرفع الدقة.

callback_urlstringاختياري

نرسل النتيجة إليه مع توقيع X-Khabeer-Signature.

curl https://speak-saudi-ai.lovable.app/api/public/v1/transcribe-async \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -F file=@meeting.wav \
  -F "features=summary,minutes" \
  -F "callback_url=https://your-app.com/hooks/khabeer"

POST/v1/denoise

تنقية الصوت

ينقّي التسجيل من ضجيج الخلفية وهسهسة الخط ويوازن مستوى الصوت، فترتفع دقة التفريغ في تسجيلات مراكز الاتصال. مهمة غير متزامنة ترجع رابط تحميل صالح لمدة ساعة.

المعاملات

file | audio | audio_urlmixedمطلوب

الصوت المراد تنقيته (WAV 16-bit).

callback_urlstringاختياري

إشعار عند الانتهاء.

curl https://speak-saudi-ai.lovable.app/api/public/v1/denoise \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -F file=@noisy.wav

POST/v1/tashkil

التشكيل

يضيف التشكيل للنص العربي قبل نطقه، فتضبط الأسماء والكلمات المتشابهة وينطقها الصوت صح من أول مرة.

المعاملات

textstringمطلوب

النص العربي (حتى ٤٠٠٠ حرف).

curl https://speak-saudi-ai.lovable.app/api/public/v1/tashkil \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"مرحبا بك في خبير"}'

GET/v1/jobs/{id}

متابعة المهام

كل مهمة طويلة (تفريغ أو تنقية) لها حالة ونسبة تقدم ونتيجة. استعلم عن مهمة واحدة أو اسرد آخر المهام، أو استقبل النتيجة على callback_url موقّعًا بـ HMAC.

المعاملات

idpathمطلوب

معرّف المهمة.

statusqueryاختياري

للسرد: queued | running | completed | failed.

limitqueryاختياري

عدد المهام في السرد (حتى ١٠٠).

توقيع الـ callback: نرسل ترويسة X-Khabeer-Signature = HMAC-SHA256 لجسم الطلب بمفتاحك. تحقق منها قبل قبول النتيجة.

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

curl "https://speak-saudi-ai.lovable.app/api/public/v1/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer $KHABEER_KEY"

POST/v1/voice-clones

استنساخ الصوت

ارفع عيّنة صوت سعودي (١٠ ثوانٍ فأكثر) ونبني منها صوتًا خاصًا لعلامتك. بعدها استخدم المعرّف clone_xxx في أي نداء نطق تمامًا مثل الأصوات الجاهزة.

المعاملات

file | audio | audio_urlmixedمطلوب

عيّنة الصوت.

namestringمطلوب

اسم الصوت داخل حسابك.

accentstringاختياري

اللهجة الأقرب للعيّنة.

المعاينة: GET /v1/voice-preview?voice=noura&accent=najdi يرجع مقطعًا قصيرًا مجانيًا لعرض الصوت داخل لوحتك.

curl https://speak-saudi-ai.lovable.app/api/public/v1/voice-clones \
  -H "Authorization: Bearer $KHABEER_KEY" \
  -F file=@sample.wav -F "name=صوت العلامة" -F "accent=najdi"

GET/v1/models

النماذج المتاحة

قائمة المحركات المتاحة لحسابك: التفريغ، النطق، المحادثة، وتنقية الصوت — مع اللهجات المدعومة والمزايا وتكلفة كل واحد.

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

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

مكتبات الربط

مكتبة JavaScript جاهزة تغطي كل النقاط بما فيها التفريغ المباشر والنطق المتدفق، ونماذج بايثون للمنصات الصوتية. لا تحتاج تثبيت — استوردها من الرابط مباشرة.

app.js

import { Khabeer } from "https://speak-saudi-ai.lovable.app/sdk/khabeer.js";

const kb = new Khabeer({ apiKey: process.env.KHABEER_API_KEY });

const { audio } = await kb.tts({ text: "هلا والله", voice: "noura" });
const { text } = await kb.stt({ audio: recordingBlob });
const { models } = await kb.models();

khabeer.js khabeer_pipecat.py khabeer_vapi_server.py

الربط مع LiveKit Agents

شغّل خبير كمحرك تفريغ (STT) ومحرك نطق (TTS) داخل وكيل LiveKit الصوتي. نزّل ملف الإضافة، حطه جنب وكيلك، وحدد مفتاحك — وبيصير الوكيل يسمع ويتكلم سعودي.

نزّل khabeer_livekit.py وثائق LiveKit Agents

terminal

pip install "livekit-agents[openai]" aiohttp
curl -O https://speak-saudi-ai.lovable.app/livekit/khabeer_livekit.py
export KHABEER_API_KEY=kb_live_xxx

agent.py

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import openai

from khabeer_livekit import KhabeerSTT, KhabeerTTS


async def entrypoint(ctx: JobContext):
    await ctx.connect()

    session = AgentSession(
        # Saudi speech recognition
        stt=KhabeerSTT(hints=["الرياض", "جدة", "شاورما"]),
        llm=openai.LLM(model="gpt-4o-mini"),
        # Saudi voice: noura | sara | dana | fahad | abdullah | khaled
        tts=KhabeerTTS(voice="noura", accent="najdi", speed=1.05),
    )

    await session.start(
        room=ctx.room,
        agent=Agent(instructions="تكلم سعودي طبيعي وباختصار."),
    )
    await session.generate_reply(instructions="سلّم على العميل ورحّب فيه.")


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

KhabeerSTT

يمرّر صوت الغرفة على /v1/stt ويرجّع نصًا سعوديًا. الخيارات: hints، api_key، base_url.

KhabeerTTS

ينطق رد الوكيل بصوت سعودي عبر /v1/tts. الخيارات: voice، accent، speed.

الكريدت

كل نداء ينخصم من رصيد مؤسستك نفسه، وتشوفه في صفحة الفوترة أو عبر /v1/usage.

الربط مع Pipecat

خدمتان جاهزتان داخل خط أنابيب Pipecat: KhabeerSTTService للسمع و KhabeerTTSService للنطق بالبث المباشر، فيتكلم وكيلك سعودي مع مقاطعة طبيعية.

نزّل khabeer_pipecat.py وثائق Pipecat

terminal

pip install pipecat-ai aiohttp
curl -O https://speak-saudi-ai.lovable.app/integrations/khabeer_pipecat.py
export KHABEER_API_KEY=5abear_sk_xxx

bot.py

from pipecat.pipeline.pipeline import Pipeline
from khabeer_pipecat import KhabeerSTTService, KhabeerTTSService

pipeline = Pipeline([
    transport.input(),
    KhabeerSTTService(accent="najdi", hints=["الرياض", "شاورما"]),
    llm,
    KhabeerTTSService(voice="noura", accent="najdi", speed=1.05),
    transport.output(),
])

الربط مع Vapi و Ultravox

Vapi يسمح بصوت ومفرّغ مخصصين عبر رابط تستضيفه أنت. جسر جاهز بـ FastAPI يوصّل خبير بالاثنين، ونفس الملف يخدم Ultravox أو أي منصة تطلب TTS/STT عبر HTTP.

نزّل khabeer_vapi_server.py

terminal

pip install fastapi uvicorn httpx
curl -O https://speak-saudi-ai.lovable.app/integrations/khabeer_vapi_server.py
export KHABEER_API_KEY=5abear_sk_xxx VAPI_SECRET=shared-secret
uvicorn khabeer_vapi_server:app --host 0.0.0.0 --port 8000

assistant.json

{
  "voice": {
    "provider": "custom-voice",
    "server": { "url": "https://your-host/vapi/voice",
                "secret": "shared-secret" }
  },
  "transcriber": {
    "provider": "custom-transcriber",
    "server": { "url": "https://your-host/vapi/transcriber",
                "secret": "shared-secret" }
  }
}

ultravox

# Ultravox / أي منصة أخرى
POST https://your-host/ultravox/tts   -> audio/wav
POST https://your-host/ultravox/stt   -> { "text": "..." }

الأخطاء

كل خطأ يرجع بنفس الشكل: رمز رقمي ثابت تبني عليه منطقك، ومعرّف نصي، ورسالة عربية جاهزة للعرض على المستخدم.

40001

HTTP 400 · invalid_request

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

40101

HTTP 401 · unauthorized

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

40201

HTTP 402 · insufficient_credits

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

40301

HTTP 403 · forbidden_scope

المفتاح ما يملك صلاحية هذه النقطة.

40401

HTTP 404 · not_found

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

41301

HTTP 413 · payload_too_large

حجم الملف تجاوز ١٠٠ ميجابايت.

42901

HTTP 429 · concurrency_limit

تجاوزت عدد الطلبات المتزامنة لباقتك.

42902

HTTP 429 · rate_limited

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

50001

HTTP 500 · server_error

خطأ داخلي عندنا — أعد المحاولة.

50201

HTTP 502 · upstream_error

محرك الصوت غير متاح مؤقتًا.

402 Payment Required

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

الحدود والصلاحيات

كل مفتاح تحدد له صلاحيات وسقف شهري، وكل باقة لها عدد طلبات متزامنة. تجاوز التزامن يرجع 42901 بدل ما يعلّق الطلب.

صلاحيات المفتاح

ttsتوليد الصوت والتشكيل
sttالتفريغ والتفريغ المباشر
chatمحادثة المساعد
jobsالمهام الطويلة والتنقية
voicesالأصوات والاستنساخ
readالنماذج والرصيد والاستهلاك

الطلبات المتزامنة لكل باقة

تجريبي3
احترافي6
أعمال15
نمو30
مؤسسات60

تحتاج أكثر؟ باقة المؤسسات ترفع الحد حسب اتفاقك.

usage breakdown

curl "https://speak-saudi-ai.lovable.app/api/public/v1/usage?breakdown=endpoint&days=30" \
  -H "Authorization: Bearer $KHABEER_KEY"

curl "https://speak-saudi-ai.lovable.app/api/public/v1/usage?breakdown=day&days=30&format=csv" \
  -H "Authorization: Bearer $KHABEER_KEY" -o usage.csv

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

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

توليد صوت

كريدت لكل حرف

تفريغ كلام

١٬٠٠٠

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

دور محادثة

٥٬٠٠٠

كريدت لكل رد

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

جاهز تبدأ؟

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

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