INTERNAL API · V1

把配音安全接入内容工作流

面向后端服务、自动化 Agent 与团队内部工具。API 与网页端共用权限、金币和供应商路由,并提供可发现、可审计、可幂等重试的稳定契约。

Bearer Token原始 Key 仅创建时显示一次
能力可发现动态查询模型、音色和模板
统一计费与网页生成使用同一规则
最小权限Scope、用户组和资源所有权隔离
01 · QUICKSTART

快速开始

在账户中心创建 Key,按工作流选择最小权限。当前每把 Key 固定一个渠道和模型;Eleven v3 与 v4 的 A/B 测试请分别创建 Key。

Base URLhttps://tts.wiendeal.com/api/internal/v1

1. 在服务端保存认证信息

环境变量示例
TTS_SAAS_BASE_URL=https://tts.wiendeal.com
TTS_SAAS_API_KEY=el_internal_REPLACE_WITH_YOUR_KEY

2. 查询真实可用能力

启动自检
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. 直接指定音色创建生成记录

POST /batches
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"
02 · DISCOVERY

先发现,再调用

/models 是能力真相源。读取 available、supportsAudioTags、settings、outputFormats 和当前计费摘要,不要凭模型名称猜能力。

音色引用

使用音色 UUID 或返回的可读别名;旧 voice_* 别名继续兼容,不暴露上游 voice ID。

模板角色

从 /projects 获取稳定 roleKey,避免依赖显示序号。

直接音色模式无需预先创建模板;系统会把记录归入受保护的“API 调用项目”。使用模板时则冻结既有角色配置;两种方式都以每个 batch 自己的模型和音色快照为准。

正式计费单一口径/models、批次预估、钱包冻结与成功结算共用当前生效规则。预留保护只是临时冻结,结算后退回多余金币;语气标签也计入上游字符。
03 · FLOW

标准调用流程

1自检与发现查询账户、模型、音色或模板
2创建生成记录POST /batches 返回 batchId 与预估
3提交生成返回 operationId 与 attemptIds
4轮询状态直到成功、明确失败或结果不明
5校验下载按 attemptId 下载并核对 SHA-256
GET /attempts/{attemptId}/audio
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。

04 · SAFETY

幂等、取消与追溯

每个写操作使用稳定的 Idempotency-Key,每次调用可另带 X-Client-Request-Id。网络超时后复用原键,并先查询已有资源,不要换新键盲目重发。

可以自动处理

explicit_failed 会释放冻结金币;未发送任务可调用 POST /batches/{batchId}/cancel。

必须停止自动化

unknown 代表上游结果不明,应先查询和核对,避免重复计费或音频。

持有 audit:read 的 Key 可通过 GET /requests 查询自己的调用记录;响应还会回传 X-Api-Version、X-Idempotent-Replay 和调用方关联编号。

05 · CURRENT LIMITS

当前能力边界

  • 支持直接指定音色或使用已有模板创建批次,并下载本人成功音频。
  • Eleven v3 支持方括号语气标签;v4 与 v4 Turbo 当前不声明支持,按完整发送文本计费。
  • 仅接受模型目录公开的生成参数,实际参数冻结并随 attempt 返回。
  • VIP、团队成员和管理员可按用户组策略创建 API Key。
  • 暂不提供 Webhook、多模型单 Key和浏览器 CORS。
  • 当前仅提供 MP3;时间戳与无损格式尚未开放。
  • Google Cloud 真实生成尚未开放;当前实际渠道为 ElevenLabs。
  • 调用方不能指定 Workspace、供应商账号或上游 Key。
06 · OPERATIONS

状态与排错

保存每次响应的 X-Request-Id。认证响应还提供 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset;429 额外提供 Retry-After。

400字段、渠道或模型无效;查看 details
401 / 403Key 无效、Scope 或用户组权限不足
404 / 410资源不存在、无权访问或音频已过期
409幂等键或业务状态冲突
429超过 Key 的分钟限流
5xx先查询结果,再决定是否复用原键重试
完整规范字段、Scope、状态机、安全规则与兼容承诺见项目 API Key 接入指南;机器接入可直接读取 OpenAPI 3.1。