REST API

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

توليد الفيديو، وتركيب الكلام، وتوليد الصور، واستنساخ الصوت. مفتاح واجهة واحد وعنوان أساسي واحد: https://seslab.com.tr/api/v1

احصل على مفتاح الفتح في اللوحة

البداية (3 خطوات)

احصل على مفتاح واجهة البرمجة

افتح حساباً وأنشئ مفتاحاً جديداً من صفحة «مفاتيحي» في اللوحة. يبدأ مفتاحك بـ sk_ (مثل sk_a1b2c3…) ويُعرض مرة واحدة فقط — انسخه واحفظه في مكان آمن.

أرسل طلبك الأول

أضف ترويسة Authorization: Bearer sk_… إلى كل طلب وأرسل البيانات بصيغة JSON. أسهل طلب أول: GET /me — يعيد حسابك ورصيدك.

استلم النتيجة

قد يستغرق توليد الصور والفيديو وقتاً: تحصل أولاً على معرّف id ثم تستعلم عن الحالة به. يُخصم الرصيد عند النجاح ويُعاد تلقائياً عند الفشل.

المصادقة

أضف ترويسة Authorization: Bearer sk_… إلى كل طلب. تُنشئ المفتاح من اللوحة؛ والمفتاح الناقص أو غير الصالح يعيد 401، وكثرة المحاولات الفاشلة تعيد 429. ولا يوجد حدّ للطلبات في الدقيقة مع مفتاح صالح.

curl https://seslab.com.tr/api/v1/me \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

رمز تطبيق سطح المكتب

القاعدة: يُستخدم sk_ للاستبدال فقط؛ ولا يُحفظ بشكل دائم داخل تطبيق سطح المكتب. يستخدم التطبيق مفتاح sk_ في طلب الاستبدال الأول فقط. احفظ رمز dsk_ الوارد في استجابة POST /api/desktop/auth/token بأمان في سلسلة مفاتيح macOS أو مدير بيانات اعتماد Windows. ولا تحتفظ قاعدة بيانات SesLab سوى ببصمة hash لهذا الرمز.

curl -X POST https://seslab.com.tr/api/desktop/auth/token \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_label":"Ufuk Mac M4","app_version":"1.0.0"}'

# الاستجابة: { "desktop_token": "dsk_...", "expires_in": 2592000 }

النقاط الطرفية

POST

/videoبدء توليد فيديو (غير متزامن، 202 + id)حسب المستوى

GET

/video?id=IDالاستعلام عن حالة الفيديو أو نتيجتهمجاني

POST

/ttsتحويل النص إلى كلام (متزامن إن جهز خلال 45 ثانية، وإلا 202 + id)1.0 رصيد/حرف · v3: 1.5 رصيد/حرف

GET

/tts?id=IDالاستعلام عن حالة مهمة تحويل النص إلى كلام أو صوتهامجاني

POST

/api/image-generateبدء توليد صورة (غير متزامن، 202 + id)حسب النموذج

GET

/api/image-generate/status?id=IDالاستعلام عن مهمة صورة طويلةمجاني

GET

/voicesكتالوج الأصوات المتاحةمجاني

POST

/voice-cloneإنشاء نسخة صوتية (multipart/form-data)مجاني

GET

/voice-cloneسرد نسخك الصوتية مع معرّفات voice_idمجاني

DELETE

/voice-clone?voice_id=IDحذف نسخة صوتيةمجاني

GET

/meبيانات الحساب والرصيدمجاني

GET

/creditsرصيد النقاطمجاني

GET

/statusحالة النظام (لا تتطلّب مصادقة)مجاني

POST

/desktop/auth/tokenاستبدال مفتاح sk_ برمز dsk_ قصير الأجل لتطبيق سطح المكتبمجاني

توليد الفيديو

POST /video

يعيد 202 (غير متزامن). استعلم عن النتيجة عبر GET /video?id=. ويُعاد الرصيد تلقائياً في المهام الفاشلة.

الحقل	النوع	الحالة	الوصف
prompt	string (10–1000)	مطلوب	اكتب ما تريد رؤيته في الفيديو. الوصف بالإنجليزية يعطي نتائج أفضل غالباً.
model	string	اخت. · افتراضي standard-video	باقة الفيديو: standard-video (سريع) أو hd-video (بريميوم). إن تركتها فارغة فستُستخدم standard-video. أُزيلت أسماء الباقات القديمة، وإن أرسلت واحدة منها ستحصل على خطأ واضح يخبرك بما ينبغي استخدامه.
resolution	string	اخت. · افتراضي 720p	الدقة: 720p (الافتراضية) أو 1080p. تستهلك 1080p رصيداً أعلى ضمن الباقة نفسها.
aspect_ratio	string	اخت. · افتراضي 16:9	يُدعم الفيديو الأفقي 16:9 فقط.
duration	number	اخت. · افتراضي 8	المدّة ثابتة: كل باقات الفيديو تنتج 8 ثوانٍ، والقيمة التي ترسلها تُتجاهل.

مستويات الجودة والرصيد

المستوى	model =	الرصيد	ملاحظات
سريع افتراضي	`standard-video`	19,500	16:9 · 720p · 8 ث
سريع (1080p)	`standard-video`	29,250	16:9 · 1080p · 8 ث · أرسل resolution=1080p
بريميوم	`hd-video`	25,500	16:9 · 720p · 8 ث
بريميوم (1080p)	`hd-video`	38,250	16:9 · 1080p · 8 ث · أرسل resolution=1080p

ملاحظة: تدعم نقطة الفيديو حالياً الإنتاج الأفقي 16:9 فقط. وإن تركت aspect_ratio فارغاً فستُستخدم 16:9.

تركيب الكلام (TTS)

POST /tts

إن جهز خلال 45 ثانية فستحصل على audio_url متزامن. أما النصوص الطويلة فتعيد 202 + id؛ استعلم عنها عبر GET /tts?id=. ولـ ElevenLabs أرسل إحدى باقات voice-natural، أو voice-economy كخيار اقتصادي.

الحقل	النوع	الحالة	الوصف
text	string (1–31000)	مطلوب	النص المراد تحويله إلى صوت.
voice_id	string	مطلوب	الصوت الذي سيقرأ النص. اجلب قائمة الأصوات عبر GET /voices وضع المعرّف هنا.
voice_package	string	اخت. · افتراضي voice-natural	ElevenLabs: voice-natural أو voice-natural-fast أو voice-natural-live أو voice-natural-latest. والخيار الاقتصادي: voice-economy.
language	string	اختياري	لغة النص، مثل tr (التركية). صالح فقط مع voice-natural وvoice-fast.
voice_settings	object	اختياري	ضبط دقيق (لـ voice-natural فقط): stability 0–100، similarity_boost 0–100، speed 0.7–1.2، style 0–100، use_speaker_boost: true/false.

توليد الصور

POST /api/image-generate

نقطة طرفية متوافقة مع SesLab. المفتوح حالياً هو نموذج الصور النشط المُثبَت فقط. تعيد 202 + id؛ استعلم عن النتيجة عبر نقطة الحالة. ويُعاد الرصيد تلقائياً عند الفشل.

الحقل	النوع	الحالة	الوصف
prompt	string (1–20000)	مطلوب	ماذا تريد في الصورة؟ صِفها بحرّية (يمكنك الكتابة بالتركية أيضاً).
model	string	مطلوب	معرّف النموذج: النموذج النشط حالياً هو nano-banana-2-lite فقط. ويُقبل image-standard كاسم بديل قديم.
aspect_ratio	string	اختياري	اختيار النسبة للنموذج النشط.
resolution	string	مغلق	يعمل النموذج النشط أصلاً بدقة 1K؛ وخيارات الدقة الإضافية مغلقة.
mode	string	مغلق	خدمات الصور غير النشطة مغلقة.
quality	string	مغلق	خدمات الصور غير النشطة مغلقة.
image_input	string[]	اختياري	صور مرجعية: data URI بترميز base64 أو رابط http(s). الاسم البديل: reference_images. أربع صور كحدّ أقصى في النموذج النشط.
negative_prompt	string	اختياري	العناصر المراد تجنّبها.

نماذج الصور

nano-banana-2-liteNano Banana 2 Lite2,000 رصيدنموذج نشط مُثبَت · 1K · 4 مراجع

افتراضي

GET /api/image-generate/status?id=ID

تعيد حقول status وimage_url وimage_urls وerror لمهام الصور الطويلة.

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

POST /voice-clone — multipart/form-data

مجاني. يعيد voice_id — يُستخدم في طلبات تحويل النص إلى كلام.

الحقل	النوع	الحالة	الوصف
file	ملف	مطلوب	عيّنة الصوت المراد استنساخها — MP3/M4A/WAV/OGG/FLAC، بحدّ أقصى 10 ميغابايت (تسجيل نظيف من 10 ثوانٍ إلى 5 دقائق).
voice_name	string (≤100)	مطلوب	الاسم الذي تمنحه للنسخة (يظهر لك أنت).
language_tag	string	اخت. · افتراضي Turkish	لغة الصوت، مثل Turkish.
gender_tag	string	اخت. · افتراضي female	جنس الصوت: female أو male.

GET /voice-clone

يسرد جميع النسخ الصوتية في حسابك من الأحدث إلى الأقدم مع حقول voice_id. ولا يأخذ أي معاملات.

{
  "success": true,
  "voices": [
    {
      "id": "b7c1e0a2-4f10-4a91-9c2e-1d5b7a0e33af",
      "voice_id": "2630054",
      "cloned_voice_id": "2630054",
      "name": "صوتي",
      "created_at": "2026-08-12T09:14:22.000Z"
    }
  ]
}

التعليق بنسخة صوتية: أرسل قيمة voice_id (أو id) التي تحصل عليها هنا ضمن طلب POST /tts في حقل voice_id — ولا حاجة لحقل الباقة/النموذج، فهو يُتجاهل مع الأصوات المستنسخة. وحدّ النص 5000 حرف.

DELETE /voice-clone?voice_id=ID

يحذف النسخة. معامل الاستعلام voice_id مطلوب؛ وإن لم تُوجد النسخة يعيد 404.

أمثلة الشيفرة

# فحص مصادقة أساسي
curl https://seslab.com.tr/api/v1/me \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

# ابدأ فيديو — الباقات: standard-video (سريع) / hd-video (بريميوم)، 16:9، 720p|1080p، 8 ث
curl -X POST https://seslab.com.tr/api/v1/video \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "عرض سينمائي لمنتج، حركة كاميرا ناعمة",
    "aspect_ratio": "16:9",
    "model": "standard-video",
    "resolution": "720p"
  }'

# استعلم عن حالة الفيديو (مجاناً، كرّر الاستعلام)
curl "https://seslab.com.tr/api/v1/video?id=VIDEO_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

# حوّل النص إلى صوت
curl -X POST https://seslab.com.tr/api/v1/tts \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحباً، هذا صوت وُلّد بواسطة Seslab.",
    "voice_id": "VOICE_ID",
    "voice_package": "voice-natural",
    "language": "ar"
  }'

# ولّد صورة — تعيد 202 + id، واستعلم عن النتيجة من نقطة الحالة
curl -X POST https://seslab.com.tr/api/image-generate \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "صورة منتج فاخرة بإضاءة زرقاء على خلفية داكنة",
    "aspect_ratio": "1:1",
    "model": "nano-banana-2-lite"
  }'

رموز الأخطاء

401Unauthorizedترويسة Authorization ناقصة أو المفتاح خاطئ.

402Insufficient Creditsالرصيد غير كافٍ. اشحن من اللوحة.

422Validation Errorجسم الطلب خاطئ أو القيمة غير مدعومة.

429Too Many Attemptsأكثر من 10 محاولات مصادقة فاشلة في الدقيقة.

404Not Foundلم يُعثر على عملية التوليد المطلوبة (id).

503Service Not Readyخدمة التوليد غير نشطة حالياً.

500Server Errorخطأ غير متوقّع — أعد المحاولة، ويُعاد الرصيد في المهام الفاشلة.

هل أنت مستعدّ للبدء؟

افتح حساباً، وأنشئ مفتاح واجهة البرمجة، وأرسل طلبك الأول خلال دقائق.

ابدأ مجاناً الأسعار