よくある質問
OpenAI SDKはそのまま使えますか?
はい、公式のOpenAI SDKをそのまま利用できます。APIキーをセットし、base_urlを当社のエンドポイントに変更するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同一です。リクエスト形状はOpenAIのspeechエンドポイントと同一です。
base_urlの変更点はどこですか?
base_urlを「https://api.woopwin.info/v1」に変更してください。これにより、公式SDKが当社のAPIエンドポイントへリクエストを送信します。認証には「Authorization: Bearer tts-...」ヘッダーを使用し、標準的なJSONボディで音声生成リクエストを送信可能です。
音声ファイルはダウンロードできますか?
生成された音声ファイルはレスポンスとして直接返されます。mp3、wav、opus、flac、pcmのいずれかの形式で取得可能です。ファイルはサーバー上に永続的に保存されず、生成時に受け取ったデータを利用することになります。
ストリーミング再生はサポートしていますか?
いいえ、ストリーミングやWebSocket、リアルタイムの部分的な音声配信はサポートしていません。テキストを送信すると、処理完了後に音声ファイル全体がレスポンスとして返されます。短めの文章でも数秒かかる場合があります。
SSMLタグは使えますか?
SSMLタグはサポートしていません。音声の制御には「speed」パラメータで速度調整(0.25〜4.0)を行うか、テキスト自体を分割して制御します。カスタム発音辞書、感情タグ、音声クローニング機能も提供していません。
音声の速度範囲はどれですか?
速度パラメータ「speed」は0.25から4.0の範囲で指定できます。デフォルト値は1.0です。これにより、教材の難易度や視聴者のペースに合わせて、読み上げの速さを細かく調整することが可能です。
言語を明示的に指定するには?
リクエストボディの「language」フィールドにISOコードを指定してください。指定しない場合、文字スクリプトから推測されますが、ラテン文字は英語とみなされるため、英語以外のラテン文字テキストには明示的な指定が推奨されます。
音声のウェーブマークは音として聞こえますか?
生成されるファイルには合成音声を示す不可視の透かし(ウォーターマーク)が埋め込まれています。これは音として聞こえるものではなく、ファイルの真正性を確認するための技術的なマークです。聴覚的な影響はありません。
最初のリクエスト
curl
curl https://api.woopwin.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.woopwin.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.woopwin.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 | 中文 |
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 |
はじめに
WoopWin APIは、英語教材の音声生成を高速化するクラウドサービスです。教師やメソドリストがテキストを即座に音声ファイルに変換できるシンプルなAPIで、教材作成の効率を向上させます。
このドキュメントでは、APIキーの取得からリクエスト送信まで、具体的な使い方を解説します。OpenAI互換のエンドポイントを採用しており、既存のSDKやcurlコマンドで簡単に統合できます。
APIのエンドポイント
主要なエンドポイントは POST https://api.woopwin.info/v1/audio/speech です。テキストを送信すると、音声ファイルが返されます。また、利用可能な音声や料金を確認するには GET /v1/voices を使用します。
認証方法
APIキーは /get-api-key/ ページでGoogleまたはメールアドレス登録後に発行されます。リクエストヘッダーに Authorization: Bearer tts-... を設定して認証します。
リクエストの形式
リクエストボディはJSON形式で、model、input、voice などの必須フィールドを含みます。OpenAI SDKの base_url を変更するだけで、そのまま利用可能です。
- POST https://api.woopwin.info/v1/audio/speech
- Content-Type: application/json
- Authorization: Bearer YOUR_API_KEY
クイックスタート
APIキーを取得して、英語教材の音声生成をすぐに開始できます。まずはアカウント登録から始めましょう。
設定は数分で完了します。cURLやPython SDKを使って、すぐにテストリクエストを送信してください。
APIキーの取得
/get-api-key/ にアクセスして、Googleまたはメールアドレスでサインアップします。Google認証では無料トライアルとして$0.50のクレジットが付与されます(7日間有効)。パスワード登録の場合はクレジットなしで開始します。ダッシュボードでAPIキーと残高を確認できます。
最初のcURLリクエスト
以下のコマンドを実行して、テキストから音声ファイルを取得します。Authorization ヘッダーに自分のAPIキーを設定してください。
- curl -X POST https://api.woopwin.info/v1/audio/speech \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- --data '{"model": "tts-1", "input": "Hello world.", "voice": "nova"}'
OpenAI SDKの設定
OpenAI SDKのbase_urlを当社のエンドポイントに変更するだけで利用可能です。base_urlを https://api.woopwin.info/v1 に設定し、APIキーを渡すだけで動作します。既存のコードをほぼ変更せずに統合できます。
音声とモデル
WoopWin APIでは、テキストを音声に変換するためのモデルとして「tts-1」と「tts-1-hd」の2種類が提供されています。これらは同じエンジンを使用しており、価格や機能に違いはありません。英語教材作成において、どちらを選んでも同じ品質の音声ファイルが生成されます。
tts-1 と tts-1-hd
両モデルは同等のエンジンを共有しており、仕様に差異はありません。教材作成の効率を重視する場合は、どちらを使用しても問題ありません。
8つの音声プリセット
8つのプリセットされた音声から選択できます。教師向けには「sage」や「atlas」が、生徒向けのストーリーテリングには「luna」や「nova」が適しています。
- aria: 温かく明確なナレーター
- nova: 明るく元気なトーン
- luna: ソフトなストーリーテリング
- sage: 落ち着いた指示的语气
- felix: エネルギー満点なプロモーション
- milo: フレンドリーな会話調
- atlas: ニュースのような中立的トーン
- orion: 深みのあるドキュメンタリー調
23言語のサポート
英語、日本語、中国語など23言語に対応しています。ただし、ベトナム語、インドネシア語、タイ語、ウクライナ語、ルーマニア語、チェコ語、ベンガル語などはサポートしていません。ラテン文字のテキストはデフォルトで英語と判断されるため、他の言語の場合は明示的にlanguageパラメータを設定してください。
パラメータの詳細
APIリクエストでテキストを音声に変換するには、input、voice、speedのパラメータを適切に設定します。これらは教材作成の出力形式や再生速度に影響する要素です。
input (テキスト)
最大4096文字までのテキストを送信できます。空白や句読点も文字数にカウントされるため、長文は分割して送信してください。
voice (音声)
8つのプリセットから選択可能です。教師向けには「aria」のクリアなナレーションや、「sage」の教育的なトーンが適しています。
言語は自動検出または明示的に指定します。英語教材の場合はlanguageを指定することを推奨します。
- aria: 温暖でクリアなナレーター
- sage: 冷静で教育的な指示
speed (速度)
0.25から4.0の範囲で再生速度を調整できます。学習者のレベルに合わせて、ゆっくりまたは速く再生させることが可能です。
デフォルト速度は1.0ですが、教材の難易度に応じて最適化してください。
レスポンス形式
APIは音声ファイルを直接レスポンス本文に含めて返します。response_formatでmp3、wav、opus、flac、pcmのいずれかを指定可能ですが、基本的にはmp3が推奨されます。
ファイルはバイナリデータとして送信されるため、クライアント側で適切にデコードまたは保存する必要があります。
mp3, wav, opus, flac, pcm
生成された音声は、リクエスト時に指定した形式で返されます。mp3は容量が小さく扱いやすいため、多くのケースで最適です。wavは非圧縮で品質を保ちます。opusやflac、pcmも必要に応じて選択可能です。
バイナリデータの受信
レスポンスボディには音声データそのものが格納されています。OpenAI SDKを使用している場合、ライブラリが自動的にバイナリデータを処理し、ローカルファイルとして保存する機能を提供します。
SDKを使用しない場合は、HTTPレスポンスのボディをそのままファイルに書き込む必要があります。
エラーレスポンス
リクエストに問題がある場合、JSON形式のエラーメッセージが返されます。ステータスコードには適切なHTTPエラー番号が設定されます。
失敗したリクエストは課金されません。ただし、ネットワークエラーやタイムアウトの場合は再試行戦略を検討してください。
- 400: Bad Request(パラメータエラー)
- 401: Unauthorized(APIキー不正)
- 429: Too Many Requests(レートリミット超過)
- 500: Internal Server Error(サーバーエラー)

レートリミットと制限
APIの利用では、1分間あたり60リクエストというレートリミットが適用されます。無料トライアル期間中や最初のトップアップ前には、この制限が1分間あたり10リクエストに緩和されています。この制限はAPIキーごとに設定され、超過すると429エラーが発生します。
生成テキストは1リクエストあたり最大4096文字まで対応可能です。それ以上の長さの教材を作成する場合は、クライアント側でテキストを分割し、複数のリクエストを送信して音声ファイルを結合する必要があります。
60リクエスト/分
通常の利用プランでは、1分間に60回のAPIリクエストが可能です。これは、複数の音声ファイルを一括で生成する場合に適した速度です。
新規アカウントや課金前の状態では、1分間あたり10リクエストに制限されます。トップアップ後、制限は自動的に解除され、通常の速度に戻ります。
- 通常: 60 req/min
- 初期/未課金: 10 req/min
- キーごとに独立してカウント
4096文字の制限
1つのAPIリクエストで送信できるテキストは、最大4096文字です。スペースや句読点も文字数に含めるため、長い教科書の章やスクリプトを処理する際は分割が必要です。
分割された各テキストは個別に音声化され、クライアント側で連続して再生できるよう結合してください。
キューの待機
音声生成はリクエストを順次処理するため、サーバーの負荷が高い場合はキューに待機することがあります。特に長いテキストやHDモードでの生成時は、待機時間が発生する可能性があります。
通常の短めのテキストでも、同時実行数が増加すると処理に若干の遅延が生じることがあります。
エラー処理
APIは正常に処理された場合でも、一時的な障害やサーバーの混雑によりエラーを返すことがあります。エラーレスポンスには具体的なコードとメッセージが含まれるため、原因を特定しやすくなっています。
これらのエラーを適切に処理することで、教材作成のワークフローを安定させることができます。
よくあるエラーコード
429 Too Many Requestsはレートリミット超過を示します。60リクエスト/分の制限を超えた場合、短時間待機後に再試行してください。400 Bad Requestはパラメータの誤りを意味します。
- 400: パラメータエラー
- 401: 認証失敗
- 429: レートリミット超過
- 500: サーバー内部エラー
タイムアウトの処理
短時間では数秒、長時間のテキストではキュー待ちで応答に時間がかかります。タイムアウトは、処理待ちの状況に応じて適切な値を設定してください。
再試行の戦略
指数関数的バックオフを採用してください。一時的なエラーは数回再試行で解決します。ただし、400や401エラーは再試行しても解決しないため、パラメータを確認してください。
データとプライバシー
WoopWin APIでは、入力されたテキストは音声生成のためだけに使用され、モデルの学習データとして再利用されることはありません。生成された音声ファイルはレスポンスで直接返され、サーバー上には保存されません。これにより、教材作成の効率性を保ちながら、学生の読み上げデータが長期にわたって蓄積されるリスクを最小限に抑えます。
課金と請求の明確化のため、リクエストのメタデータ(時間、文字数、ステータス)のみが保持されます。これにはテキストの内容は含まれないため、生徒の個人識別情報や教材の具体的な文脈が長期保存されることはありません。プライバシーを重視する英語教育現場でも、安心してAPIを利用することができます。
入力テキストの使用
送信されたテキストは、指定された音声と速度で音声ファイルを生成するプロセスにおいてのみ使用されます。入力テキストは音声生成のみに使用され、トレーニングデータとして再利用されることはありません。これにより、入力テキストがトレーニングデータとして利用される心配がありません。
- テキストは音声生成専用として使用
- トレーニングデータとして再利用しない
- 生成完了後、テキストは破棄
生成音声の保存
APIを通じて生成された音声ファイル(mp3, wav, opus, flac, pcm)は、サーバー上に永続的に保存されません。音声データはHTTPレスポンスとしてクライアントに直接返され、ユーザーのローカル環境やクラウドストレージにダウンロードされるまで、当社のサーバーには残存しません。これにより、一時的な教材作成やテスト用途でも、データの蓄積によるストレージコストや管理の手間がかかりません。
- 音声ファイルはレスポンスで返され、サーバーには保存されません。
- レスポンスで直接配信される
- ユーザー環境でのみ管理される
メタデータの保持
課金の正確性と請求明細の提供のために、リクエストのメタデータのみが保持されます。保持される情報は、リクエストのタイムスタンプ、処理された文字数、およびステータスコードです。これらにはテキストの内容や音声ファイル自体は含まれないため、生徒の名前や教材の具体的な内容が請求データと紐付くことはありません。
- リクエスト時刻、文字数、ステータスを記録
- ステータスコードを保持
- テキスト内容や音声ファイルは保持しない
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 レート制限や一時的な遅延、音声の質に関する課題をすばやく特定し、教材作成のワークフローを中断させない方法をご紹介します。
23言語
どの音声でも、これらの言語のいずれかを話します。
