انتقل إلى المحتوى
Englishابدأ مجانًا
فتح القائمة

المطورون

أضف الصوت العربي إلى منتجك

المحرك نفسه الذي يشغّل تطبيق فوكلا، عبر واجهة REST: تحويل النص إلى صوت بجميع اللهجات العربية، وتغيير الصوت، والموسيقى، ومتابعة حالة التوليد لحظة بلحظة.

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

مفاتيح الواجهة البرمجية جزء من خطة المؤسسات.

البدء السريع

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

quickstart.sh
export VOCLA_API_KEY="vk_..."   # Enterprise workspace → Settings → API keys
export VOCLA_API="https://api.vocla.ai"

# 1. Pick a model and a voice
curl -s "$VOCLA_API/v1/catalog"
curl -s "$VOCLA_API/v1/voices?lang=ar&dialect=ar-SA&limit=5" \
  -H "Authorization: Bearer $VOCLA_API_KEY"

# 2. Create a text-to-speech generation (202 Accepted)
curl -s -X POST "$VOCLA_API/v1/generations/tts" \
  -H "Authorization: Bearer $VOCLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "productModelId": "MODEL_ID",
    "voiceId": "VOICE_ID",
    "text": "مرحباً بك في فوكلا، صوتك يصل أبعد.",
    "locale": "ar-SA"
  }'

# 3. Follow progress as server-sent events
curl -N "$VOCLA_API/v1/generations/GENERATION_ID/events" \
  -H "Authorization: Bearer $VOCLA_API_KEY"

# 4. Fetch fresh download links (signed, short-lived)
curl -s "$VOCLA_API/v1/generations/GENERATION_ID" \
  -H "Authorization: Bearer $VOCLA_API_KEY"

كيف تعمل الواجهة البرمجية

  • المصادقة

    ينشئ مسؤولو مساحات العمل في خطة المؤسسات مفاتيح الواجهة البرمجية من الإعدادات، وتُرسل في الترويسة Authorization: Bearer vk_… . لكل مفتاح صلاحيات محددة (generations:read وgenerations:write وvoices:read وuploads:write)، ويظهر مرة واحدة، ويمكن إلغاؤه في أي وقت.

  • طلبات آمنة التكرار

    يحتاج كل طلب يستهلك رصيدًا إلى الترويسة Idempotency-Key. وإعادة الطلب بالمفتاح والمحتوى نفسيهما تُرجع عملية التوليد الأصلية دون خصم مرتين، أما إعادة استخدام المفتاح بمحتوى مختلف فتُرجع 409.

  • دورة حياة عملية التوليد

    يُرجع إنشاء عملية التوليد الرمز 202 ويحجز الرصيد، ثم تنتقل العملية من queued إلى running ثم إلى succeeded أو failed أو cancelled. يُخصم الرصيد عند النجاح، ويُحرَّر عند الفشل أو الإلغاء.

  • الأحداث المرسلة من الخادم

    تابع GET /v1/generations/{id}/events لتصلك أحداث queued وprogress وsucceeded وfailed وcancelled، ويحمل كل منها بيانات عملية التوليد. يُغلق البث بعد الحالة النهائية، وإعادة الاتصال تُرجع الحالة الحالية.

  • الأخطاء

    تستخدم الأخطاء الصيغة application/problem+json مع رمز ثابت (مثل INSUFFICIENT_CREDITS أو VALIDATION_ERROR)، ورسالة مترجمة (أرسل Accept-Language: ar أو en)، ومعرّف traceId تذكره حين تتواصل معنا.

  • التنزيلات

    تتضمن عمليات التوليد الناجحة روابط موقّعة بصيغتي MP3 وOGG (وWAV في الخطط التي تشملها). تنتهي صلاحية الروابط بعد نحو 15 دقيقة، فاطلب عملية التوليد مجددًا للحصول على روابط جديدة.

أهم نقاط الوصول

القائمة الكاملة، مع مخططات الطلبات والاستجابات، في مرجع الواجهة البرمجية.

الطريقةنقطة الوصولالوظيفةالصلاحية
GET/v1/catalogالنماذج وفئات الأصوات وحدود الرفععامة
GET/v1/voicesالبحث في مكتبة الأصوات حسب اللغة واللهجة والجنس والعمر والفئةvoices:read
POST/v1/generations/ttsتحويل النص إلى صوت باللهجات العربيةgenerations:write
POST/v1/uploadsبدء رفع متعدد الأجزاء للصوت الذي تريد تحويلهuploads:write
POST/v1/generations/voice-changeإعادة نطق تسجيل بصوت آخرgenerations:write
POST/v1/generations/musicتوليد موسيقى انطلاقًا من وصفgenerations:write
GET/v1/generations/{id}الحالة والرصيد وروابط التنزيل لعملية توليدgenerations:read
GET/v1/generations/{id}/eventsالتقدّم المباشر عبر الأحداث المرسلة من الخادمgenerations:read
POST/v1/generations/{id}/cancelإلغاء عملية توليد في الانتظار أو قيد التنفيذgenerations:write

أنواع توليد أخرى

endpoints.txt
# Voice changer: upload the source audio first (multipart upload, 8 MiB parts)
POST /v1/uploads                      {"filename","contentType","size"}
POST /v1/uploads/{id}/complete        {"parts":[{"partNumber","etag"}]}
POST /v1/generations/voice-change     {"productModelId","uploadId","voiceId"}

# Music from a prompt (lyrics only on vocal-capable routes)
POST /v1/generations/music            {"productModelId","prompt","duration"}

# Estimate the credit cost without reserving credits
POST /v1/generations/quote            {"type":"tts", ...same body as the generation}

شكل بث الأحداث

text/event-stream
id: 2026-09-19T12:00:01.000Z
event: progress
data: {"id":"0199…","type":"tts","status":"running","progress":50,"creditsReserved":120,"creditsCharged":0}

event: succeeded
data: {"id":"0199…","type":"tts","status":"succeeded","progress":100,"creditsCharged":120,"downloads":{"mp3":"https://…","ogg":"https://…"}}

حدود معدّل الطلبات

تُطبَّق الحدود على دقيقة متحركة لكل مستخدم أو مفتاح وعنوان IP: ‏300 طلب للواجهة البرمجية و30 لنقاط المصادقة. تحمل كل استجابة الترويسات RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset (بالثواني). وعند تجاوز الحد تصلك الاستجابة 429 RATE_LIMITED، فانتظر حتى إعادة الضبط قبل المحاولة مجددًا. ويمكن مناقشة حدود أعلى لأحمال المؤسسات.

إشعارات الويب (Webhooks)

غير متاحة بعد

إشعارات الويب الصادرة لأحداث التوليد غير متاحة بعد. استخدم الأحداث المرسلة من الخادم أو استعلم دوريًا عبر GET /v1/generations/{id}. وإن كانت مهمة لتكاملك فأخبرنا، فذلك يساعدنا على ترتيب الأولويات.

مرجع الواجهة البرمجية الكامل

كل نقطة وصول ومعامل ومخطط استجابة، مولَّدة من مستند OpenAPI نفسه الذي بُنيت عليه الواجهة البرمجية.

https://api.vocla.ai/docs
افتح مرجع الواجهة البرمجيةتنزيل openapi.json

مستعد للتكامل؟

أخبرنا عن حالة استخدامك والحجم المتوقع، وسنجهّز لك مساحة عمل للمؤسسات مع وصول إلى الواجهة البرمجية.

خطة المؤسساتتحدّث مع المبيعات