PythonでのTTS APIキー：セットアップ、ストリーミング、JSONモード

キーが何を開くかを確認

「tts api key python example」で検索する人は通常、テキストを音声に変換したいと考えています。このサービスのキーはそれを行いません。これはテキストLLMへのリクエストを認証するものであり、POST /v1/chat/completionsおよびGET /v1/modelsを使用し、モデルuncensoredを利用します。音声合成、音声アップロード、埋め込みはありません。

スクリプト、対話、ナレーションを生成して別の音声ツールに渡す場合など、プロジェクトに合っている場合は、このページ以降で動作するPythonコードを提供します。API自体から音声出力が必要な場合は、このサービスは不適切です。そのことを今知っておくのが良いでしょう。機能セットの詳細はdocsをご覧ください。

音声プロジェクトでテキスト生成を効果的に利用するには、それを「執筆段階」として扱う方法があります。モデルがナレーションの下書きを作成したり、時間制限に合わせて文章を書き直したり、複数の話者による対話に変換したりします。その後、Pythonコードで最終的なテキストを任意の音声ツールに渡します。工程を分けることで、どちらか一方のみを交換しても他方に影響を与えず、このAPIには書かれた文字数に対してのみ課金されます。

進めるにはPython 3.9以降とキーが必要です。APIキーページでサインアップし、ワンクリックで$0.50の無料トライアルクレジットを受け取ってください。これは7日間有効で、カード登録は不要です。

キーの保存とパッケージのインストール

キーをコミットするファイルに直接書き込まないでください。環境変数に格納し、実行時に読み取ってください。

Copy# base URL used below: https://api.ttsapihub.com/v1 , model: uncensored
pip install openai
export API_KEY="paste-your-key-here"

Windows PowerShellでは$env:API_KEY = "paste-your-key-here"が相当します。プロジェクトではpython-dotenvなどのパッケージで読み込む.envファイルが一般的で、.envが.gitignoreに含まれている必要があります。

キーがリポジトリに漏洩した場合は、使用不能とみなしてください。履歴から削除できる場合は削除し、新しいキーを要求してください。キーは前払いクレジットを使用するため、漏洩したキーは金銭的な漏洩にもなります。

クライアントの作成と最初の呼び出し

公式パッケージはbase_urlを受け付けます。その他は通常のOpenAI呼び出しの形式です。

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ttsapihub.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "You write short narration scripts."},
        {"role": "user", "content": "Draft a 40-word intro for a podcast about night trains."},
    ],
    temperature=0.8,
    max_tokens=200,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

usageオブジェクトは、呼び出しに使用されたトークン数を示すため、コストを計算できます：入力トークン数×100万トークンあたり$0.15、出力トークン数×100万トークンあたり$0.50。上記の呼び出しが入力トークン60個、出力トークン80個を使用した場合、コストは$0.000009と$0.00004で、合計$0.000049となります。失敗または拒否されたリクエストには課金されません。

max_tokensはオプションです。指定しない場合、完了は100,000トークンのウィンドウの残りを何でも使用できるため、長さやコストに上限を設定したい場合は指定してください。

ストリーミングで応答を取得

ストリーミングはサーバー送信イベントを使用して、生成されたトークンを返します。stream=Trueを設定してイテレートしてください。

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe a rainy station platform in four sentences."}],
    stream=True,
)

parts = []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content or ""
    parts.append(delta)
    print(delta, end="", flush=True)

text = "".join(parts)

空のchoicesリストに対するガードは、ストリームの最終イベントに使用量データが含まれ、テキストが含まれない可能性があるためです。これをスキップするとインデックスエラーを回避できます。運用上の注意点：ストリーミングリクエストはストリームが終了するまで同時実行数の枠を保持します。スレッドで多くのストリームを開始し、それらの読み取りを完了しない場合、リクエストレートが低くても同時実行数の制限に達します。

JSONを要求し、ツールを呼び出す

JSON モード

response_formatをJSONオブジェクトに設定して、応答を解析可能にします。また、プロンプトでJSONを望んでいることをモデルに伝えてください。設定は形式を制約し、プロンプトは形状を指示します。

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply only with JSON: {\"title\": str, \"beats\": [str]}"},
        {"role": "user", "content": "Outline a three-beat radio drama about a lost key."},
    ],
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], len(data["beats"]))

json.loadsを必ずtryブロックで囲んでください。max_tokensに到達した応答は、オブジェクトの途中で切れる可能性があります。

ツール呼び出し

toolsとオプションでtool_choiceを渡します。モデルがツールを要求した場合、自分でツールを実行し、role: "tool"メッセージとして結果を返してください。

Copyimport json, os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "word_count",
        "description": "Count the words in a text",
        "parameters": {
            "type": "object",
            "properties": {"text": {"type": "string"}},
            "required": ["text"],
        },
    },
}]

messages = [{"role": "user", "content": "How many words are in: the quick brown fox?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = len(args["text"].split())
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": str(result)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)

会話を維持し、トークン予算を監視する

APIはステートレスです。発言を記憶するチャットを作りたい場合は、メッセージリストをプログラムで保持し、すべての呼び出しでそれらを送信します。小さなクラスでこのタスクを処理でき、コストが増加しないように履歴を制限するのにも適しています。

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"])

history = [{"role": "system", "content": "You are a dialogue writer. Keep replies under 120 words."}]

def say(user_text, keep_last=12):
    history.append({"role": "user", "content": user_text})
    # keep the system message plus the most recent turns
    trimmed = [history[0]] + history[1:][-keep_last:]
    resp = client.chat.completions.create(model="uncensored", messages=trimmed, max_tokens=250)
    reply = resp.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply, resp.usage.total_tokens

print(say("Open a scene in a ticket office at closing time.")[0])

ウィンドウよりも金額の削減が重要です。モデルは合計で最大100,000トークンまで受け付けますが、各ターンで履歴の30,000トークンを再送信すると、入力のみで1回あたり$0.0045（100万トークンあたり$0.15の30,000倍）かかります。そのようなターンが50回続くと、出力トークンが1つカウントされる前に$0.225に達します。最後の12ターンを保持するか、それ以前の会話を短いノートに要約することで、品質を維持しつつ請求額を大幅に削減できます。

同時実行数も設計すべき点です。プログラムが複数のユーザーにサービスを提供する場合、キーの制限（フルキーは8、トライアルキーは2）に合わせたセマフォを使用することで、concurrencyエラーを回避できます。制限を超える呼び出しは失敗するのではなく独自のキューで待機するため、429で再試行するよりもフレンドリーです。

テストについても一言触れておきます。固定されたseed、低いtemperature、短いmax_tokensでAPIを呼び出す小さなスクリプトを書き、プロンプトや設定を変更するたびに実行してください。シードと低い温度は出力の再現性を高め、ノイズなしで2つのプロンプトバージョンを比較できます。これらのチェックは小さく保ってください。1セント未満のコストのテストであれば、誰かが請求書に気づかずにすべてのコミットで実行できます。

最後に、各レスポンスのリクエストIDをログに記録してください。呼び出しが奇妙な動作をした場合、そのIDはサポートに正確なリクエストを指し示す最も迅速な方法です。

制限、エラー、残高の処理

フルキーは8つの同時リクエストと1分あたり300リクエストを許可します。トライアルキーは2と60を許可します。前者を超えるとHTTP 429が返され、エラーコードはconcurrency、後者を超えると429が返され、エラーコードはrate_limitedになります。一時的な過負荷もRetry-After: 5ヘッダー付きで429を返します。

OpenAIパッケージは一部の失敗を自動で再試行しますが、max_retriesでその上限値を設定できます。バッチジョブでは、再試行に頼らず同時実行数の制限内に収まるよう、並列作業の上限も設定してください。

Copyimport os
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.ttsapihub.com/v1", api_key=os.environ["API_KEY"], max_retries=3)

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "One sentence about trains."}],
    max_tokens=60,
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
print(raw.parse().choices[0].message.content)

レスポンスヘッダーX-Request-IdとX-Balance-USDはログに役立ちます。サポートに連絡する際は、リクエストIDを記載してください。料金は価格ページに記載：入力トークン1Mあたり$0.15、出力トークン1Mあたり$0.50。チャージは$20〜$500、ボーナスは$50、$100、$200のチャージでそれぞれ5%、10%、15%です。カード（Visa、Mastercard、Apple Pay、Google Pay）と暗号資産（TRC20上のUSDT、Base上のUSDC）が利用可能です。プロンプトは学習に使用されません。このモデルは成人の合法的な利用を目的としており、未成年者を含む性的コンテンツは決して許可されません。

その他のガイド

• SillyTavern用の無料API：トライアルクレジットとセットアップ
• TTS API Base URL：それは何か、そして何を入力するか
• Elevenlabs APIチェックリスト：無検閲TTSパイプライン