よくある質問
APIキーはどのように取得しますか?
サイトの/get-api-key/ページでGoogleまたはメールパスワードでサインアップしてください。アカウント作成後、ダッシュボードにAPIキーが表示されます。キーは1アカウントにつき1つ有効で、新しいキーを発行すると旧キーは即時無効になります。
curlの例は?
POST https://api.getf59.com/v1/audio/speech へ、AuthorizationヘッダーにBearerキー、JSONボディにmodel、input、voiceを指定します。response_formatやspeedも任意で設定可能です。失敗したリクエストは課金されません。
OpenAI SDKは使用できますか?
はい、公式OpenAI SDKが利用可能です。base_urlを https://api.getf59.com/v1 に変更し、APIキーを設定するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同一です。
base_urlはどう変更しますか?
SDKのbase_urlを https://api.getf59.com/v1 に設定してください。これにより、既存のOpenAI互換エンドポイントへ正しくリクエストが送信されます。認証ヘッダーにはAPIキーを付与してください。
modelのパラメータは?
tts-1 または tts-1-hd を指定します。両者は同じエンジンと価格を使用します。特定のモデルによる機能差はないため、用途に合わせて選択してください。
inputのパラメータは?
合成対象のテキスト文字列を指定します。最大4096文字まで可能です。スペースや句読点も文字数としてカウントされます。長いテキストの場合は分割して結合する必要があります。
voiceのパラメータは?
aria、nova、luna、sage、felix、milo、atlas、orion の8種類から選択します。任意の声は23言語に対応しています。languageパラメータを指定しない場合、スクリプトに基づいて言語が推測されます。
レスポンスフォーマットは?
mp3、wav、opus、flac、pcm のいずれかを指定できます。音声ファイルはレスポンスボディとして返され、サーバーには保存されません。
最初のリクエスト
curl
curl https://api.getf59.com/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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.getf59.com/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.getf59.com/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 | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
APIキーの取得
TextVoice LabのAPIキーは、/get-api-key/ページでGoogleアカウントまたはメールアドレスとパスワードを使って作成できます。認証情報は安全に管理され、必要に応じていつでも再生成が可能です。
キーの取得後、curlコマンドやOpenAI SDKで直ちに利用可能です。各アカウントには1つのアクティブなキーが割り当てられ、再生成すると旧キーは即座に無効になります。
Googleサインイン
Googleアカウントでサインインすると、すぐに$0.50の無料トライアルクレジットが付与されます(有効期限7日間)。これにより、50,000文字程度の音声合成を無料で試せます。
- Google認証による即座のAPIキー発行
- トライアルクレジット($0.50)の自動付与
パスワード登録
メールアドレスとパスワードで登録した場合、トライアルクレジットは付与されません。ただし、USDTによるチャージでいつでも利用を開始できます。
学校や教育機関での複数ユーザー管理に適した、シンプルで透明なアカウント構造を採用しています。
- Google以外でのアカウント作成が可能
- トライアルクレジットなしで利用開始
キーの再生成
セキュリティの観点から、APIキーは必要に応じていつでも再生成できます。再生成直後に古いキーは無効化されるため、連携中のサービスに注意が必要です。
再生成後の新しいキーは、即座にリクエストに使用可能になります。
最初のリクエスト
APIキーとモデル名が準備できたら、最初の音声合成リクエストを送信します。このセクションでは、最も基本的なcurlコマンドの例と、JSONボディの構造、そして得られるレスポンスの形式について解説します。
curlの例
以下のコマンドは、指定されたテキストを音声ファイルに変換する基本的なリクエストです。Authorizationヘッダーには、アカウントページで確認したAPIキーを設定してください。https://api.getf59.com/v1がAPIのベースURLです。
- curl -X POST https://api.getf59.com/v1/audio/speech \
- -H "Authorization: Bearer tts-your-api-key" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "こんにちは、これはテストです。", "voice": "nova", "response_format": "mp3"}'
JSONボディ
リクエストボディには必須パラメータとしてmodel、input、voice、response_formatを含める必要があります。inputは4096文字以内のテキスト、voiceは8つのプリセットから選択、response_formatはmp3、wav、opus、flac、pcmから指定します。speed(0.25〜4.0)やlanguageはオプションです。
レスポンス
成功した場合、APIは音声ファイル(バイナリデータ)を直接返します。Content-Typeヘッダーには指定したフォーマット(例:audio/mpeg)が含まれます。失敗した場合は、JSON形式のエラーメッセージと共にステータスコードが返され、その場合、課金はありません。
OpenAI SDKとの統合
TextVoice LabのAPIはOpenAIの音声エンドポイントと同一のJSONスキーマを採用しています。既存のOpenAI SDKを、base_urlを https://api.getf59.com/v1 に変更するだけで利用可能です。認証ヘッダーには発行されたAPIキーを指定してください。
SDKのインストール後、base_urlを指定してクライアントを初期化します。既存のコードベースを最小限の変更で移行でき、開発効率を維持できます。
base_urlの変更
OpenAI SDKを使用する場合、初期化時に base_url パラメータを https://api.getf59.com/v1 に設定します。これにより、SDKが当社のエンドポイントに対してリクエストを送信するようになります。他のパラメータは既存のOpenAI形式を維持します。
- base_url: https://api.getf59.com/v1
- 認証ヘッダー: Authorization: Bearer tts-...
SDKの使用法
PythonやNode.jsなどの公式SDKで、 client.audio.speech.create() メソッドを呼び出します。 model に "tts-1" または "tts-1-hd" を指定し、 voice に任意の音声プリセットを設定します。
互換性
リクエスト形状はOpenAIの音声エンドポイントと同一です。ただし、当社はOpenAIと提携していません。SDKのバージョンは、最新の安定版であれば問題なく動作します。
パラメータ
APIリクエストでは、生成エンジンと音声の選択が音声品質を決定します。モデルは「tts-1」または「tts-1-hd」の2種類で、エンジンは同一ですが「tts-1-hd」はより高い音質を提供します。料金は両者とも同一です。
音声選択では、8つのプリセットから目的に合った声を選びます。ナレーター用、教育用、会話用など、用途に応じてfemale/maleのバリエーションから最適なものを選択してください。
model
エンドポイントのmodelフィールドには、tts-1またはtts-1-hdを指定します。両モデルは同じ音声エンジンを共有しており、料金の差はありません。tts-1-hdを選択した場合、音声の解像度と自然さが向上します。長い教材の音声化にはtts-1で十分ですが、詳細な発音確認にはtts-1-hdが適しています。
- tts-1: 標準的な品質、高速生成
- tts-1-hd: 高解像度、滑らかな波形
input
inputフィールドには、音声化したいテキスト文字列を渡します。1リクエストあたりの文字数制限は4096文字です。これを超える場合は、クライアント側で分割して複数のリクエストを送信し、生成された音声ファイルを結合する必要があります。空白や句読点も文字数としてカウントされます。
- 最大4096文字/リクエスト
- 空白・句読点も文字数に含まれる
- 超えた場合は分割結合が必要
voice
voiceフィールドには、8つのプリセットのいずれかを指定します。female系にはaria、nova、luna、sageがあり、male系にはfelix、milo、atlas、orionがあります。言語を明示的に指定しない場合、ラテン文字は英語として扱われるため、日本語や中国語などの場合はlanguageパラメータを併用してください。
- aria: 暖かくクリアなナレーター
- nova: 明るく元気なトーン
- luna: 柔らかく物語的な語り
- sage: 落ち着いた説明調
- felix: エネルギー溢れるプロモーション
- milo: フレンドリーな会話体
レスポンスフォーマット
APIレスポンスには音声ファイルが直接含まれます。生成された音声は、リクエストで指定したフォーマットで返却され、追加の処理は不要です。
mp3、wav、opus、flac、pcmの5形式に対応しており、用途に合わせて選択してください。ファイルサイズや品質のバランスを考慮して最適な形式を指定します。
mp3
mp3は最も汎用性が高く、Webブラウザやモバイルアプリでの再生に最適です。ファイルサイズが小さく、帯域幅を節約できます。
- 広くサポートされている形式
- 効率的なデータサイズ
wav
wavは非圧縮形式で、高音質な音声処理や編集に適しています。データサイズは大きくなりますが、音声の劣化がありません。
- 非圧縮の高音質
- 編集や分析に最適
opus
opusは低遅延・高効率のコーデックです。mp3より高い圧縮効率を実現します。
- 高い圧縮効率
- 低遅延の通信に適合

エラーハンドリング
APIは標準的なHTTPステータスコードとJSONエラーオブジェクトを返します。合成に失敗した場合、課金は行われず、エラーメッセージには具体的な原因が含まれます。
レートリミットとタイムアウトは、安定したサービス利用のために設計されています。これらを理解することで、大量の教材生成時のエラーを最小限に抑えられます。
エラーコード
失敗時はHTTPステータス400または500番台が返されます。レスポンスボディにはerrorフィールドが含まれ、原因(例: invalid_input)が記述されます。失敗したリクエストは課金されません。
レートリミット
APIキーあたり1分間あたり60リクエストまでです。初回利用時は1分間10リクエストに制限されます。USDTでのチャージ後、制限は自動的に解放されます。
リミット超過時はHTTP 429が返されます。キューイングにより処理が待機する場合もあります。
- 通常: 60リクエスト/分
- 初期: 10リクエスト/分
- エラー時は返金される
タイムアウト
長文の合成には時間がかかります。標準的なタイムアウト設定で問題ありません。短く複雑なリクエストでも、サーバーの混雑により待機時間が発生することがあります。
レートリミット
APIキーごとに1分あたり60リクエストのレート制限が適用されます。これは、短くても長文のテキスト合成において安定した処理を提供するための基準です。
大量の教材を音声化する際、キュー待ちが発生する可能性があります。短文の場合は数秒、長文では実時間並みの速度で生成されます。
60リクエスト/分
1分間に60回までPOSTリクエストを送信できます。この制限はキーごとに独立しており、並列処理もこの範囲内で可能です。
制限に達すると、新しいリクエストはキューに待機するか、エラーを返します。負荷が高い時間帯でも、順次処理されるため、最終的にはすべてのリクエストが完了します。
- 60 requests per minute per key
- Queue-based processing under load
- No parallel limit beyond rate
初期の制限
初回利用時は1分あたり10リクエストの制限が適用されます。これはシステムが安定するまでの初期段階の調整です。
最初のチャージ(Top-up)を行うと、この制限は解除され、標準の60リクエスト/分の制限に切り替わります。
チャージ後の解放
TRONネットワーク(TRC-20)でのUSDTチャージ完了後、制限は自動的に解除されます。通常、送信から数分で反映されます。
チャージは最小5ドルから可能で、残高の有効期限はありません。制限の解除は手動での申請不要です。
- TRC-20 USDT only
- Minimum $5 top-up
- Auto-unlock within minutes
音声と言語
TextVoice Lab APIは8つの音声プリセットと23言語に対応しています。voicesエンドポイントで利用可能な音声と言語の一覧を取得できます。modelsエンドポイントではtts-1とtts-1-hdのモデル情報を確認できます。
音声はLibriTTS-RおよびLibriVoxの録音に基づいています。すべての生成音声には合成音声を示す不可聴の透かしが含まれます。
voicesエンドポイント
GET /v1/voicesで利用可能な音声プリセットと対応言語の一覧を取得できます。8つの音声は性別やトーンで分類され、すべての音声は指定された23言語のいずれかを話せます。
- 女性: aria, nova, luna, sage
- 男性: felix, milo, atlas, orion
modelsエンドポイント
GET /v1/modelsで利用可能なモデルを確認できます。tts-1とtts-1-hdは同じエンジンと価格を提供します。
言語の指定
言語コードを指定しない場合、文字に基づいて言語が推測されます。ラテン文字の非英語テキストはデフォルトで英語として扱われるため、明示的な指定が必要です。
対応言語: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish。
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 ラテン文字のテキストはデフォルトで英語として処理されるため、英語以外のラテン文字テキストでは明示的な言語指定が必要です。
23言語
どの音声でも、これらの言語のいずれかを話します。
