Aller au contenu
Français
Essai gratuit
Ouvrir le menu

Développeurs

Intégrez la voix arabe à votre produit

Le moteur qui fait tourner l'application Vocla, via une API REST : synthèse vocale dans tous les dialectes arabes, transformation de voix, musique et suivi des générations en temps réel.

Ouvrir la référence de l'APIObtenir un accès API

Les clés API sont incluses dans les offres Business et Entreprise.

Démarrage rapide

Créez votre première génération en arabe en quatre requêtes : choisissez un modèle et une voix, créez la génération, suivez sa progression et téléchargez le résultat.

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"

Fonctionnement de l'API

  • Authentification

    Les administrateurs d'un espace de travail sous offre Business ou Entreprise créent les clés API dans les paramètres. Envoyez-les sous la forme Authorization: Bearer vk_… . Chaque clé dispose de portées (generations:read, generations:write, voices:read, uploads:write), n'est affichée qu'une seule fois et peut être révoquée à tout moment.

  • Requêtes idempotentes

    Toute requête qui consomme des crédits exige un en-tête Idempotency-Key. Une nouvelle tentative avec la même clé et le même corps renvoie la génération d'origine au lieu de facturer deux fois ; réutiliser une clé avec un corps différent renvoie 409.

  • Cycle de vie d'une génération

    La création d'une génération renvoie 202 et réserve les crédits. Elle passe de queued à running, puis à succeeded, failed ou cancelled. En cas de succès, les crédits sont débités ; en cas d'échec ou d'annulation, ils sont libérés.

  • Server-sent events

    Ouvrez le flux GET /v1/generations/{id}/events pour recevoir les événements queued, progress, succeeded, failed et cancelled, chacun accompagné de la génération. Le flux se ferme après un état final ; une reconnexion renvoie l'état actuel.

  • Erreurs

    Les erreurs utilisent application/problem+json avec un code stable (par exemple INSUFFICIENT_CREDITS ou VALIDATION_ERROR), un détail localisé (envoyez Accept-Language: ar ou en) et un traceId à mentionner si vous nous contactez.

  • Téléchargements

    Les générations réussies incluent des liens signés MP3 et OGG (WAV sur les offres qui l'incluent). Les liens expirent au bout d'environ 15 minutes ; récupérez à nouveau la génération pour en obtenir de nouveaux.

Principaux endpoints

La liste complète, avec les schémas de requête et de réponse, se trouve dans la référence de l'API.

MéthodeEndpointRôlePortée
GET/v1/catalogModèles, catégories de voix et limites d'uploadPublic
GET/v1/voicesRecherchez dans la bibliothèque par langue, dialecte, genre, âge et catégorievoices:read
POST/v1/generations/ttsSynthèse vocale dans les dialectes arabesgenerations:write
POST/v1/uploadsDémarrez un upload multipart pour l'audio à transformeruploads:write
POST/v1/generations/voice-changeFaites redire un enregistrement par une autre voixgenerations:write
POST/v1/generations/musicGénérez de la musique à partir d'un promptgenerations:write
GET/v1/generations/{id}Statut, crédits et liens de téléchargement d'une générationgenerations:read
GET/v1/generations/{id}/eventsProgression en direct via server-sent eventsgenerations:read
POST/v1/generations/{id}/cancelAnnulez une génération en file d'attente ou en coursgenerations:write

Autres types de génération

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}

À quoi ressemble le flux d'événements

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

Limites de débit

Les limites s'appliquent sur une minute glissante, par utilisateur ou clé authentifiés et par IP : 300 requêtes pour l'API et 30 pour les endpoints d'authentification. Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (en secondes). Au-delà d'une limite, vous recevez 429 RATE_LIMITED ; attendez la réinitialisation avant de réessayer. Des limites plus élevées peuvent être discutées pour les charges Entreprise.

Webhooks

Pas encore disponible

Les webhooks sortants pour les événements de génération ne sont pas encore disponibles. Utilisez les server-sent events ou interrogez GET /v1/generations/{id}. Si les webhooks comptent pour votre intégration, dites-le-nous : cela nous aide à prioriser.

Référence complète de l'API

Chaque endpoint, paramètre et schéma de réponse, généré à partir du même document OpenAPI que celui qui sert à construire l'API.

https://api.voclalabs.com/docs
Ouvrir la référence de l'APITélécharger openapi.json

Prêt à intégrer ?

Présentez-nous votre cas d'usage et le volume prévu : nous configurerons un espace de travail Entreprise avec accès à l'API.

Offre EntrepriseContacter l'équipe commerciale