TTS APIの使い方:curl例とSDK連携

作成者 TTS Monitor編集部 · 更新日 2026-11-19

このページは、KoeFlowのTTS APIをすばやく実装するための技術リファレンスです。SaaS通知やUI音声合成を開発するインディー開発者向けに、curlコマンドとOpenAI互換のSDK連携手順を具体的な数値を交えて解説します。

APIキーの取得方法から、パラメータの詳細、レートリミットの仕組みまで、実際のワークフローに必要な情報を網羅しています。OpenAI互換SDKのbase_url変更やエラーハンドリング、課金ルールも記載しており、即時統合を可能にするデータ駆動型のガイドラインです。

TTS APIの使い方:curl例とSDK連携

よくある質問

APIキーはどこで取得できますか?

https://criex.info/get-api-key/ でGoogleまたはメールアドレスとパスワードでサインアップすると取得できます。Googleサインインには$0.50の無料クレジットが付与されますが、メール登録の場合は付与されません。アカウントには有効なキーが1つだけ割り当てられ、新しいキーを発行すると古いキーは即時無効になります。

OpenAI SDKをそのまま使えますか?

はい、公式OpenAI SDKをそのまま利用可能です。base_urlを https://api.criex.info/v1 に変更し、APIキーを設定するだけで統合できます。当社は独自SDKを持たないため、OpenAI SDKまたはプレーンHTTPを使用して音声生成リクエストを送信します。

base_urlはどのように変更しますか?

OpenAI SDKを使用する場合、base_urlを https://api.criex.info/v1 に設定します。これにより、同じリクエスト形状で音声合成エンドポイントにアクセスできます。他のエンドポイントもこのベースURL配下に配置されています。

modelパラメータの違いは何ですか?

tts-1 と tts-1-hd の2種類があります。両者は同じエンジンを使用し、価格も同一です。選択によって機能や品質に違いはなく、単なる識別子です。最大4096文字のテキストを入力として受け付けます。

speedの範囲は0.25から4.0ですか?

はい、速度パラメータは0.25から4.0の範囲で設定可能です。デフォルト値は指定されていません。これにより、音声の再生速度を調整できます。

response_formatには何がありますか?

mp3、wav、opus、flac、pcm の5つの形式から選択できます。音声ファイルはレスポンスとして返され、サーバーには保存されません。必要なフォーマットに応じて response_format パラメータを設定してリクエストを送信してください。

languageパラメータは必須ですか?

必須ではありません。指定しない場合、文字ベースから言語が推測されます。ラテン文字のテキストはデフォルトで英語とみなされるため、英語以外のラテン文字テキストには language パラメータを明示的に設定してください。

4096文字を超える場合はどうしますか?

テキストを最大4096文字のパートに分割し、各パートの音声ファイルを個別に生成します。その後、生成された音声ファイルを結合して1つのファイルにします。これにより、長いテキストでも音声合成が可能です。

失敗したリクエストのエラーコードは何ですか?

失敗したリクエストの具体的なエラーコードは指定されていません。ただし、合成に失敗した場合は請求が全額返金されます。ステータスコードやエラーメッセージは標準的なHTTPレスポンスに従います。

レートリミット超過時はどうなりますか?

1分間あたり60リクエスト(初回チャージ前は1分間10リクエスト)の制限があります。超過時はリクエストが拒否されます。負荷が高い場合、リクエストは順番に処理されるため、待機が発生する可能性があります。

音声リストはどのように取得しますか?

GET /v1/voices エンドポイントにアクセスすることで、利用可能な音声、言語、フォーマット、価格の一覧を取得できます。これにより、利用可能な8つの音声プリセットを確認できます。

モデル情報はどこで確認できますか?

GET /v1/models エンドポイントにアクセスすることで、利用可能なモデル情報を確認できます。tts-1 と tts-1-hd の2つのモデルが利用可能です。

認証ヘッダーの形式は何ですか?

Authorization: Bearer tts-... の形式でAPIキーをヘッダーに設定します。これはOpenAIの認証形式と互換性があり、SDK経由でも同じ形式でキーを渡すことで認証できます。

curlコマンドの例を教えてください。

curl -X POST https://api.criex.info/v1/audio/speech -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "tts-1", "input": "こんにちは", "voice": "nova", "response_format": "mp3"}'

最初のリクエスト

curl

curl https://api.criex.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.criex.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.criex.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria女性
nova女性
luna女性
sage女性
felix男性
milo男性
atlas男性
orion男性
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

APIキーの取得

の音声波形イラスト: APIキーの取得

APIキーの取得は、/get-api-key/ページでGoogleアカウントまたはメールアドレスによる登録から始まります。Googleサインインの場合は、登録と同時に$0.50の無料クレジット(約5万文字分、7日間有効)が付与されます。

メールアドレスとパスワードで登録した場合、初回のクレジット付与はありません。アカウントは各サイト独立であり、作成済みのキーはダッシュボードで確認・コピーできます。新しいキーを発行すると旧キーは即時無効化されます。

Googleサインインでの登録

Googleサインインでの登録

Googleアカウントでサインインすると、即時にAPIキーが生成され、ダッシュボードに表示されます。この方法で$0.50の無料トライアルクレジットが付与され、7日間の有効期間内に使用可能です。

クレジットカードや銀行口座の登録は不要です。残高は自動で減算され、課金情報はリアルタイムで確認できます。

  • Googleサインインで即時登録完了
  • $0.50の無料クレジット(7日間有効)が付与
  • クレジットカード登録不要

メールアドレス登録での登録

メールアドレス登録での登録

メールアドレスとパスワードを使用してアカウントを作成することもできます。この方法では、初期の無料クレジットは付与されません。

APIキーはダッシュボードで確認でき、必要に応じて新しいキーを発行できます。旧キーは新しいキーの発行と同時に即時無効化されます。

  • メールアドレスとパスワードで登録
  • 初期無料クレジットなし
  • キーの発行で旧キーは即時無効化

APIキーの表示とコピー

ダッシュボードには、現在のAPIキー、残高、試用期間、使用状況が明確に表示されます。キーはワンクリックでコピー可能で、すぐにAPIリクエストに使用できます。

キーは1アカウントあたり1つ有効です。セキュリティのため、必要に応じて新しいキーを発行して旧キーを無効にすることができます。

  • ダッシュボードでキーと残高を確認
  • ワンクリックでキーをコピー
  • キーの再発行で旧キーは即時無効化

初回のAPIリクエスト(cURL)

の音声波形イラスト: 初回のAPIリクエスト(cURL)

POSTリクエストをhttps://api.criex.info/v1/audio/speechに送信し、テキストから音声ファイルを取得します。最大4096文字の入力に対応し、失敗したリクエストは課金されません。

JSONボディでmodel、input、voiceを指定します。生成された音声は直接レスポンスとして返されます。

POSTリクエストの構文

エンドポイントへのPOSTリクエストにより、音声合成処理が実行されます。認証にはAuthorization: BearerヘッダーでAPIキーを渡します。

  • Endpoint: POST https://api.criex.info/v1/audio/speech
  • Content-Type: application/json

JSONボディの構成

modelにはtts-1またはtts-1-hdを指定します。両者は同じエンジンと価格です。inputフィールドに合成対象のテキスト(最大4096文字)を設定します。voiceには8種類のプリセットから選択します。speedは0.25〜4.0の範囲で調整可能です。

必須項目に加え、response_format(mp3, wav, opus, flac, pcm)やlanguage(ISOコード)も指定できます。languageを省略するとスクリプトから推測されますが、英語以外のラテン文字の場合は明示的に設定してください。

  • model: tts-1 or tts-1-hd
  • input: string (max 4096 chars)
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • speed: 0.25 - 4.0
  • response_format: mp3, wav, opus, flac, pcm
  • language: optional ISO code

レスポンスの受信

成功時、音声データがバイナリまたはベース64エンコードされた形式で返されます。リクエストが失敗した場合、料金は返還されます。

生成速度は長文で実時間程度(秒間約25文字)、短文では数秒かかります。リクエストはキューイングされ、順番に処理されます。

OpenAI SDKとの互換性

の音声波形イラスト: OpenAI SDKとの互換性

KoeFlowのAPIはOpenAIのspeechエンドポイントと互換性があり、公式SDKをそのまま利用できます。base_urlを https://api.criex.info/v1 に変更するだけで統合可能です。

認証は Authorization: Bearer <YOUR_KEY> ヘッダーで設定します。SDKの初期化時にAPIキーを渡すことで、既存のコードベースに最小限の修正で音声合成機能を組み込めます。

base_urlの変更方法

SDKの初期化時に base_url を https://api.criex.info/v1 に設定します。これにより、標準的な /v1/audio/speech エンドポイントが自動的に使用されます。

公式SDKのそのままの使用

OpenAI公式SDK(Python, Node.jsなど)の AudioClient を使用できます。モデル名は tts-1 または tts-1-hd を指定し、残りのパラメータは従来通り設定します。

認証ヘッダーの設定

リクエストヘッダーに Authorization: Bearer <API_KEY> を含めます。APIキーはダッシュボードで生成・コピーした値を使用します。

パラメータの詳細

の音声波形イラスト: パラメータの詳細

APIリクエストには model、voice、speed といった必須パラメータの設定が求められます。これらは音声の品質、トーン、再生速度を制御し、生成されるオーディオファイルの特性を決定します。

各パラメータは特定の範囲と制約を持ち、仕様に厳密に合わせることで予期しないエラーや不要な課金を回避できます。以下のセクションで具体的な値と動作を確認してください。

modelパラメータ(tts-1/tts-1-hd)

model には "tts-1" または "tts-1-hd" を指定します。両者は同じエンジンと価格(100万文字あたり$10)を使用するため、機能面での違いはありません。

両者は同じエンジンと価格ですが、識別子として選択してください。実装上の挙動は同一です。

voiceパラメータの選択

voice パラメータでは8つのプリセットから1つを選択します。Aria(ナレーター)、Nova(アップビート)、Luna(ストーリーテリング)、Sage(インストラクショナル)、Felix(プロモ)、Milo(会話)、Atlas(ニュース)、Orion(ドキュメンタリー)が利用可能です。

どの音声も23言語を話す能力を持ちます。SaaSの通知音声にはAtlasやMiloが、UI案内にはSageやAriaが適しています。

音声はLibriTTS-RおよびLibriVoxの録音データに基づいており、生成ファイルには合成音声を示す不可視の透かしが含まれます。

  • Aria: 暖かく明瞭なナレーター
  • Nova: 明るく元気なトーン
  • Luna: 柔らかく物語的な語り
  • Sage: 落ち着きのある指示音声
  • Felix: エネルギーに満ちたプロモーション音声
  • Milo: 親しみやすい会話調音声
  • Atlas: ニュース風の中立な音声
  • Orion: 深みのあるドキュメンタリー音声

speedパラメータの範囲

speed パラメータは0.25から4.0の範囲で再生速度を調整できます。デフォルト値は1.0です。

SaaSの通知では読みやすさを確保するため1.0〜1.5程度が適しています。一方、短時間のフィードバック通知には高速な速度が有効です。

速度を変更してもキャラクターやトーンは維持されますが、極端な速度では可読性が低下する可能性があります。

  • 最小値: 0.25(1/4倍速)
  • 標準値: 1.0
  • 最大値: 4.0(4倍速)

フォーマットと言語

の音声波形イラスト: フォーマットと言語

生成音声の形式をmp3、wav、opus、flac、pcmから選択できます。各形式は用途に応じて使い分け、APIレスポンスとして直接Audioファイルを取得します。

言語コードはISOコードで指定します。未指定時はスクリプトから推測されますが、ラテン文字の非英語テキストでは明示的な指定が必要です。

response_formatの選択肢

mp3はサイズが小さく汎用性が高く、wavはロスレスで品質を維持します。opusは効率的な圧縮、flacは可逆圧縮、pcmは未圧縮データを提供します。

選択したフォーマットはレスポンスボディの音声データとして返却され、追加の変換処理は不要です。

languageパラメータの指定

23言語に対応しており、任意の声で任意の言語を話せます。ISO 639-1コードを指定することで、発音の正確性を保証します。

指定しない場合、システムは入力テキストの文字セットに基づいて言語を自動判定します。

言語自動検出のルール

ラテン文字のテキストはデフォルトで英語として扱われます。日本語や中国語など、固有の文字セットを持つ場合は正しく検出されます。

英語以外のラテン文字言語(フランス語やドイツ語など)を使用する場合は、明示的にlanguageパラメータを設定してください。

  • mp3, wav, opus, flac, pcm
  • Latin text defaults to English
  • 23 languages supported
フォーマットと言語

エラー処理とステータスコード

の音声波形イラスト: エラー処理とステータスコード

TTS APIは標準的なHTTPエラーコードを返します。401 UnauthorizedはAPIキーが不正な場合、400 Bad RequestはJSON形式の誤りや無効なパラメータ指定を示します。各エラーレスポンスには原因を特定するための詳細メッセージが含まれるため、デバッグ時に迅速な修正が可能です。

レートリミット違反(429 Too Many Requests)が発生した場合、リクエストは拒否されます。ただし、音声合成処理そのものが失敗した場合(500番台エラーなど)、そのリクエストに対する課金は全額返還されます。正常に完了しなかった限り、コストは発生しません。

一般的なエラーコード

400エラーは、指定されたモデル(tts-1/tts-1-hd)や音声(voice)が無効な場合、または入力テキストが4096文字を超えている際に返されます。401エラーはAPIキーが期限切れまたは誤っている場合です。これらのエラーはリクエストの構文や設定に問題があることを意味します。

  • 400: 無効なパラメータまたはテキスト長超過
  • 401: APIキーの認証失敗
  • 500: サーバー側の合成処理エラー

レートリミットエラー

APIキーあたり1分あたり最大60リクエストまでが許可されています。アカウント作成直後やトップアップ前は1分あたり10リクエストの制限があります。制限を超えたリクエストは429ステータスコードを返し、即時拒否されます。キューイングは行われません。

  • 通常時: 60 req/min
  • 制限時: 10 req/min
  • 429エラー: 即時拒否

失敗時の課金返還

音声合成の処理中に何らかの理由でリクエストが失敗した場合、そのリクエストに対する課金は行われません。失敗したリクエストは課金対象外となり、残高から差し引かれません。これは、正常に音声ファイルが生成されなかった場合のみ適用されます。

  • 合成失敗: 課金なし
  • 返還: 自動処理
  • 残高: 変化しない

レートリミットの理解

の音声波形イラスト: レートリミットの理解

APIキー1つあたり1分間あたり60リクエストのレートリミットが適用されます。大量のバッチ処理を行う場合、この制限を前提に設計する必要があります。

アカウント作成直後は、最初のトップアップを行うまで1分あたり10リクエストの制限がかかります。これは無料トライアルの利用者にも適用される初期段階の制限です。

1分あたり60リクエスト

認証済みAPIキーの最大スループットは1分あたり60リクエストです。これは単一のAPIキーでの同時処理能力を示します。複数のプロジェクトで同じキーを使う場合、これらを合計した値が限界となります。

初回10 req/minの制限

最初のトップアップ(USDT送金)が完了するまで、レートリミットは1分あたり10リクエストに制限されます。

最小トップアップ額は$5です。送信後、数分で残高が反映され、制限が解除されます。

キューイングの動作

リクエストは順番に処理されます。短時間での大量リクエストが発生した場合、キューに待機します。

キューイング中は追加の課金は発生せず、処理が完了した時点でのみ課金されます。応答待機時間が長くなる可能性があります。

音声リストの取得

の音声波形イラスト: 音声リストの取得

APIキーの取得後、まず利用可能な音声とモデル情報を取得します。これにより、正しい voice パラメータと model パラメータの値を確認できます。

GET /v1/voices と GET /v1/models エンドポイントを活用し、8種類のプリセット音声やサポート言語の一覧をコード内で動的に参照できます。

GET /v1/voices エンドポイント

GET /v1/voices を呼び出すと、利用可能な音声リスト、対応言語、フォーマット、価格情報が取得できます。8つの音声プリセット(aria, nova, luna, sage, felix, milo, atlas, orion)の詳細を確認できます。

サポートされている言語の確認

23言語(英語、日本語、中国語、スペイン語など)がサポートされています。language パラメータを明示的に指定しない場合、スクリプトから言語が推測されます。

モデル情報の取得

GET /v1/models を使用して、tts-1 と tts-1-hd の2つのモデル情報を取得できます。両モデルは同じエンジンと価格を採用しています。

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 テキストは音声生成の処理中にのみ使用され、永続的なデータベースに格納されて学習データとして再利用されることはありません。

音声のアバター aria
aria女性
音声のアバター nova
nova女性
音声のアバター luna
luna女性
音声のアバター sage
sage女性
音声のアバター felix
felix男性
音声のアバター milo
milo男性
音声のアバター atlas
atlas男性
音声のアバター orion
orion男性

23言語

どの音声でも、これらの言語のいずれかを話します。

出典および参考資料

  1. Wikipedia
  2. curl documentation
  3. openai-node on GitHub
  4. MDN: Web Speech API
  5. Node.js documentation
  6. FFmpeg documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. Tether (USDT)
  9. IETF RFC 7845: Ogg Opus
  10. openai-python on GitHub
  11. TRON developer hub: TRC-20
  12. LibriVox public-domain audiobooks

このサイトに関するその他の情報