Pythonで使う音声合成API：保存、ストリーミング、再送
クラウドの音声合成APIは、Pythonスクリプトに声を与えるいちばん短い方法です。モデルのダウンロードもGPUも不要で、HTTPリクエスト1回で済みます。このガイドでは、requestsライブラリを使ってPythonからSuperClonicaの音声合成APIを呼び出す方法を、最初のファイルから長文のストリーミング、本番スクリプトに必要な制限の扱いまで紹介します。
キーが必要です。GoogleまたはGitHubでSuperClonicaにログインし、ワークスペースの音声合成APIセクションで作成してください。無料プランは1日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": "Pythonからこんにちは！", "voice": "F1", "language": "ja", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)
"format" を指定しないと、最も小さいファイルであるOgg Vorbisで返ります。wavも使えます。1回のリクエストは最大2万文字です。
長いテキストをストリーミングする
"stream": true を付けると、サーバーは音声を作りながら送るので、最初の部分からディスクに書き込んだりプレーヤーに渡したりできます：
with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "ja", "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ミリ秒で届き、約1万6000文字が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：テキストがプランの1枠で許される長さを超えています。分割してください。
- 401：キーがない、間違っている、または削除されています。
- 失敗したテキストはプランに計上されません。