Skip to content
العربيةStart free
Open menu

Developers

Build Arabic voice into your product

The same engine that powers the Vocla app, over a REST API: text to speech in every Arabic dialect, voice changing, music and generation status in real time.

Open the API referenceGet API access

API keys are part of the Enterprise plan.

Quickstart

Create your first Arabic generation in four requests: pick a model and a voice, create the generation, follow its progress and download the result.

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"

How the API works

  • Authentication

    Workspace admins on the Enterprise plan create API keys in settings. Send them as Authorization: Bearer vk_… . Each key has scopes (generations:read, generations:write, voices:read, uploads:write), is shown once and can be revoked at any time.

  • Idempotent requests

    Every request that spends credits needs an Idempotency-Key header. Retrying with the same key and body returns the original generation instead of charging twice; reusing a key with a different body returns 409.

  • Generation lifecycle

    Creating a generation returns 202 and reserves credits. It moves from queued to running to succeeded, failed or cancelled. Success captures the credits; failure or cancellation releases them.

  • Server-sent events

    Stream GET /v1/generations/{id}/events for queued, progress, succeeded, failed and cancelled events, each carrying the generation. The stream closes after a terminal state; reconnecting returns the current state.

  • Errors

    Errors use application/problem+json with a stable code (for example INSUFFICIENT_CREDITS or VALIDATION_ERROR), a localized detail (send Accept-Language: ar or en) and a traceId to quote when you contact us.

  • Downloads

    Succeeded generations include signed MP3 and OGG links (WAV on plans that include it). Links expire after about 15 minutes; fetch the generation again for fresh ones.

Key endpoints

The full list, with request and response schemas, is in the API reference.

MethodEndpointWhat it doesScope
GET/v1/catalogModels, voice categories and upload limitsPublic
GET/v1/voicesSearch the voice library by language, dialect, gender, age and categoryvoices:read
POST/v1/generations/ttsText to speech in Arabic dialectsgenerations:write
POST/v1/uploadsStart a multipart upload for audio you want to transformuploads:write
POST/v1/generations/voice-changeSpeak a recording again in another voicegenerations:write
POST/v1/generations/musicGenerate music from a promptgenerations:write
GET/v1/generations/{id}Status, credits and download links of a generationgenerations:read
GET/v1/generations/{id}/eventsLive progress as server-sent eventsgenerations:read
POST/v1/generations/{id}/cancelCancel a queued or running generationgenerations:write

Other generation types

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}

What the event stream looks like

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://…"}}

Rate limits

Limits apply over a rolling minute per authenticated user or key and IP: 300 requests for the API and 30 for authentication endpoints. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). When you exceed a limit you receive 429 RATE_LIMITED; wait for the reset before retrying. Higher limits can be discussed for Enterprise workloads.

Webhooks

Not yet available

Outbound webhooks for generation events are not available yet. Use server-sent events or poll GET /v1/generations/{id}. If webhooks matter for your integration, tell us; it helps us prioritise.

Full API reference

Every endpoint, parameter and response schema, generated from the same OpenAPI document the API is built from.

https://api.vocla.ai/docs
Open the API referenceDownload openapi.json

Ready to integrate?

Tell us about your use case and expected volume, and we'll set up an Enterprise workspace with API access.

Enterprise planTalk to sales