把配音安全接入内容工作流
面向后端服务、自动化 Agent 与团队内部工具。API 与网页端共用权限、金币和供应商路由,并提供可发现、可审计、可幂等重试的稳定契约。
快速开始
在账户中心创建 Key,按工作流选择最小权限。当前每把 Key 固定一个渠道和模型;Eleven v3 与 v4 的 A/B 测试请分别创建 Key。
https://tts.wiendeal.com/api/internal/v11. 在服务端保存认证信息
TTS_SAAS_BASE_URL=https://tts.wiendeal.com
TTS_SAAS_API_KEY=el_internal_REPLACE_WITH_YOUR_KEY2. 查询真实可用能力
curl "$TTS_SAAS_BASE_URL/api/internal/v1/me" -H "Authorization: Bearer $TTS_SAAS_API_KEY"
curl "$TTS_SAAS_BASE_URL/api/internal/v1/models" -H "Authorization: Bearer $TTS_SAAS_API_KEY"
curl "$TTS_SAAS_BASE_URL/api/internal/v1/voices?enabled=true&limit=50" -H "Authorization: Bearer $TTS_SAAS_API_KEY"3. 直接指定音色创建生成记录
curl --fail-with-body -X POST "$TTS_SAAS_BASE_URL/api/internal/v1/batches" \
-H "Authorization: Bearer $TTS_SAAS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: workflow:batch:order-001' \
--data-binary @batch.json查看 batch.json 示例
{
"title": "order-001 英文旁白 A/B",
"clientRef": "workflow:order-001",
"metadata": {"workflow":"voiceover","run":"2026-11-18"},
"source": {"kind":"manual","label":"order-001","originalContent":"欢迎使用十一圈配音"},
"defaultVoice": "alias:voice_REPLACE_ME",
"generationSettings": {"stability":0.4,"similarity_boost":0.8},
"rows": [
{"id":"line-1","sourceRow":1,"sceneId":"1","lineId":"1","copy":"欢迎使用十一圈配音。"},
{"id":"line-2","sourceRow":2,"sceneId":"1","lineId":"2","voice":"VOICE_UUID","copy":"这是第二句话。"}
]
}4. 提交全部行并轮询
curl --fail-with-body -X POST "$TTS_SAAS_BASE_URL/api/internal/v1/batches/$BATCH_ID/generation" \
-H "Authorization: Bearer $TTS_SAAS_API_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: workflow:generate:order-001:v1' --data '{"kind":"initial"}'
curl "$TTS_SAAS_BASE_URL/api/internal/v1/batches/$BATCH_ID" -H "Authorization: Bearer $TTS_SAAS_API_KEY"先发现,再调用
/models 是能力真相源。读取 available、supportsAudioTags、settings、outputFormats 和当前计费摘要,不要凭模型名称猜能力。
使用音色 UUID 或返回的可读别名;旧 voice_* 别名继续兼容,不暴露上游 voice ID。
从 /projects 获取稳定 roleKey,避免依赖显示序号。
直接音色模式无需预先创建模板;系统会把记录归入受保护的“API 调用项目”。使用模板时则冻结既有角色配置;两种方式都以每个 batch 自己的模型和音色快照为准。
/models、批次预估、钱包冻结与成功结算共用当前生效规则。预留保护只是临时冻结,结算后退回多余金币;语气标签也计入上游字符。标准调用流程
curl --fail-with-body "$TTS_SAAS_BASE_URL/api/internal/v1/attempts/$ATTEMPT_ID/audio" \
-H "Authorization: Bearer $TTS_SAAS_API_KEY" -o result.mp3 -D response-headers.txt下载响应带 X-Content-SHA256。音频为私有临时资源,默认保留期通过 /me.capabilities.audioRetentionDays 发现;成功后应立即保存到自己的持久存储,过期返回 410。
幂等、取消与追溯
每个写操作使用稳定的 Idempotency-Key,每次调用可另带 X-Client-Request-Id。网络超时后复用原键,并先查询已有资源,不要换新键盲目重发。
explicit_failed 会释放冻结金币;未发送任务可调用 POST /batches/{batchId}/cancel。
unknown 代表上游结果不明,应先查询和核对,避免重复计费或音频。
持有 audit:read 的 Key 可通过 GET /requests 查询自己的调用记录;响应还会回传 X-Api-Version、X-Idempotent-Replay 和调用方关联编号。
当前能力边界
- 支持直接指定音色或使用已有模板创建批次,并下载本人成功音频。
- Eleven v3 支持方括号语气标签;v4 与 v4 Turbo 当前不声明支持,按完整发送文本计费。
- 仅接受模型目录公开的生成参数,实际参数冻结并随 attempt 返回。
- VIP、团队成员和管理员可按用户组策略创建 API Key。
- 暂不提供 Webhook、多模型单 Key和浏览器 CORS。
- 当前仅提供 MP3;时间戳与无损格式尚未开放。
- Google Cloud 真实生成尚未开放;当前实际渠道为 ElevenLabs。
- 调用方不能指定 Workspace、供应商账号或上游 Key。
状态与排错
保存每次响应的 X-Request-Id。认证响应还提供 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset;429 额外提供 Retry-After。
400字段、渠道或模型无效;查看 details401 / 403Key 无效、Scope 或用户组权限不足404 / 410资源不存在、无权访问或音频已过期409幂等键或业务状态冲突429超过 Key 的分钟限流5xx先查询结果,再决定是否复用原键重试