开发者
把阿拉伯语语音集成到您的产品中
驱动 Vocla 应用的同一引擎，通过 REST API 提供：覆盖所有阿拉伯语方言的文本转语音、变声、音乐生成，以及实时的生成状态。
API 密钥包含在 Business 和企业版方案中。
快速入门
只需四个请求即可完成第一次阿拉伯语生成：选择模型和声音、创建生成任务、跟踪进度、下载结果。
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），仅显示一次，并可随时吊销。
幂等请求
所有消耗积分的请求都需要携带 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 的方案还提供 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 |
其他生成类型
# 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}事件流示例
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，以滚动一分钟为窗口计算：API 为 300 次请求，认证接口为 30 次。每个响应都带有 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset（秒）。超出限制时会收到 429 RATE_LIMITED，请等待重置后再重试。企业级负载可协商更高的限制。
Webhook
暂未开放生成事件的出站 Webhook 暂未开放。请使用服务器推送事件，或轮询 GET /v1/generations/{id}。如果 Webhook 对您的集成很重要，请告诉我们，这有助于我们安排优先级。