指南

用 Python 调用语音合成 API：保存、流式传输与重试

云端语音合成 API 是让 Python 脚本开口说话的最短路径：无需下载模型，无需显卡，一个 HTTP 请求即可。本指南用 requests 库演示如何在 Python 中调用 SuperClonica 语音合成 API，从第一个文件到流式朗读长文本，再到像生产脚本那样处理限制。请注意：Supertonic 3 暂不支持中文，可朗读英语、日语、韩语等 31 种语言。

你需要一个密钥：用 Google 或 GitHub 登录 SuperClonica，在工作区的语音 API 部分创建。免费套餐每天提供 1 分钟音频。

选择声音 或在本地运行引擎

保存 mp3

把密钥放在环境变量中，带上声音和语言发送文本：

import os, requests; KEY = os.environ["SUPERCLONICA_KEY"]; r = requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": "Hello from Python!", "voice": "F1", "language": "en", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)

不指定 "format" 时返回 Ogg Vorbis，文件最小；也可以选择 wav。一次请求最多 20000 字符。

流式获取长文本

使用 "stream": true 时，服务器边生成边发送音频，因此从第一块开始就可以写入磁盘或交给播放器：

with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "en", "stream": True}, stream=True, timeout=120) as r: r.raise_for_status(); f = open("speech.ogg", "wb"); [f.write(chunk) for chunk in r.iter_content(8192)]; f.close()

在我们的测量中，无论文本多长，第一个声音最快 300 毫秒到达，约 16000 字符在 25.6 秒内朗读完毕。

声音与额度

列出密钥可用的声音；每一项都有 id、名称、类型（stock、own、bought 或 catalog）和语言：

voices = requests.get("https://superclonica.com/api/v1/voices", headers={"Authorization": "Bearer " + KEY}, timeout=30).json()["items"]

在大任务开始前查看套餐剩余额度：

usage = requests.get("https://superclonica.com/api/v1/usage", headers={"Authorization": "Bearer " + KEY}, timeout=30).json(); print(usage["plan"], usage["available_seconds"])

错误与重试

每个请求都带上 Idempotency-Key 头，例如文本的哈希：这样超时后重复的请求会等待同一个任务，而不会把文本朗读并计费两次。

  • 429：套餐的 10 分钟窗口已用完；等待 Retry-After 中的秒数后重新发送。
  • 503：队列已满；等待 Retry-After 秒后用同一个密钥重新发送。
  • 413：文本超过套餐一个窗口允许的长度；请拆分。
  • 401：密钥缺失、错误或已删除。
  • 失败的文本不计入套餐。