رفتن به محتوا
فارسی
شروع رایگان
باز کردن منو

توسعه‌دهندگان

صدای عربی را به محصول خود بیاورید

همان موتوری که اپلیکیشن Vocla را به کار می‌اندازد، از طریق REST API: تبدیل متن به گفتار در همه لهجه‌های عربی، تغییر صدا، موسیقی و وضعیت تولید به‌صورت زنده.

باز کردن مرجع APIدریافت دسترسی API

کلیدهای API بخشی از طرح‌های Business و سازمانی هستند.

شروع سریع

نخستین تولید عربی خود را با چهار درخواست بسازید: مدل و صدا را انتخاب کنید، تولید را ایجاد کنید، پیشرفت آن را دنبال کنید و نتیجه را دانلود کنید.

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

# 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"

API چگونه کار می‌کند

  • احراز هویت

    مدیران فضای کاری در طرح Business یا سازمانی، کلیدهای API را در تنظیمات می‌سازند. آن‌ها را به شکل Authorization: Bearer vk_… بفرستید. هر کلید دامنه‌های دسترسی مشخصی دارد (generations:read، ‏generations:write، ‏voices:read، ‏uploads:write)، فقط یک بار نمایش داده می‌شود و هر زمان می‌توان آن را باطل کرد.

  • درخواست‌های idempotent

    هر درخواستی که اعتبار مصرف می‌کند به سرآیند Idempotency-Key نیاز دارد. تکرار درخواست با همان کلید و همان بدنه، به‌جای کسر دوباره هزینه، همان تولید اولیه را برمی‌گرداند؛ استفاده دوباره از یک کلید با بدنه متفاوت، خطای 409 می‌دهد.

  • چرخه عمر تولید

    ایجاد یک تولید پاسخ 202 برمی‌گرداند و اعتبار را رزرو می‌کند. وضعیت آن از queued به running و سپس به succeeded، ‏failed یا cancelled می‌رسد. در صورت موفقیت اعتبار کسر می‌شود و در صورت شکست یا لغو آزاد می‌شود.

  • رویدادهای ارسالی از سرور (SSE)

    جریان 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 دقیقه منقضی می‌شوند؛ برای پیوند تازه، تولید را دوباره درخواست کنید.

نقاط پایانی اصلی

فهرست کامل، همراه با طرح‌واره درخواست و پاسخ، در مرجع API آمده است.

متدنقطه پایانیکارکرددامنه دسترسی
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 درخواست برای API و 30 درخواست برای نقاط پایانی احراز هویت. هر پاسخ سرآیندهای RateLimit-Limit، ‏RateLimit-Remaining و RateLimit-Reset (برحسب ثانیه) را دارد. اگر از حد عبور کنید، پاسخ 429 RATE_LIMITED دریافت می‌کنید؛ پیش از تلاش دوباره تا زمان بازنشانی صبر کنید. برای بارهای کاری سازمانی می‌توان درباره محدودیت‌های بالاتر گفت‌وگو کرد.

وب‌هوک‌ها

هنوز در دسترس نیست

وب‌هوک‌های خروجی برای رویدادهای تولید هنوز در دسترس نیستند. از رویدادهای ارسالی از سرور استفاده کنید یا GET /v1/generations/{id} را به‌صورت دوره‌ای فراخوانی کنید. اگر وب‌هوک برای یکپارچه‌سازی شما مهم است، به ما بگویید؛ این به اولویت‌بندی ما کمک می‌کند.

مرجع کامل API

همه نقاط پایانی، پارامترها و طرح‌واره‌های پاسخ، تولیدشده از همان سند OpenAPI که API بر پایه آن ساخته شده است.

https://api.voclalabs.com/docs
باز کردن مرجع APIدانلود openapi.json

آماده یکپارچه‌سازی هستید؟

درباره کاربرد و حجم مورد انتظارتان بگویید تا یک فضای کاری سازمانی با دسترسی API برایتان راه‌اندازی کنیم.

طرح سازمانیگفت‌وگو با تیم فروش