APIドキュメント:クイックスタート

作成者 NpcVoice Lab編集部 · 更新日 2026-11-19

TTS APIのクイックスタートガイドでは、VoicemateのAPIをゲーム開発やNPC台詞の生成に即座に活用するための手順を解説します。curlコマンドやOpenAI SDKを用いた具体的な実装例から、パラメータの定義、サポートされる音声フォーマット、エラー処理、レートリミットの仕組みまで、必要な技術情報を網羅しています。

このドキュメントは、リソース効率を重視するフリーランスのゲーム開発者を対象にしています。APIキーの取得から最初の音声生成まで、開発ワークフローにスムーズに組み込めるよう、具体的で簡潔な情報をお届けします。

長文の生成や速度調整、エラー時の返金ルールなど、実装に直結する重要な要素を漏れなく確認してください。

APIドキュメント:クイックスタート

よくある質問

APIキーはどこに表示されますか?

APIキーは/get-api-key/ページで確認できます。アカウント作成時に発行され、ヘッダー「Authorization: Bearer tts-...」として使用します。キーは1アカウントにつき1つで、新しいキーを発行すると古いキーは即時無効になります。

curlコマンドの例はありますか?

はい、/get-api-key/ページに準備済みのcurl例が表示されます。POSTリクエストでJSONボディを送信し、音声ファイルを受信します。APIキーを適切に設定し、モデルや音声パラメータを指定してテストできます。

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

はい、OpenAI SDKがそのまま利用可能です。base_urlを当社のエンドポイントに変更し、APIキーを設定するだけで動作します。リクエスト形状はOpenAIのspeechエンドポイントと同じため、コードの修正は最小限で済みます。

base_urlはどこに変更しますか?

base_urlを「https://api.y7777.info/v1」に変更してください。これにより、OpenAI SDKやHTTPクライアントが当社のTTS APIに正しく接続されます。他のエンドポイントもこのベースURLに基づいて動作します。

パラメータの必須項目は何ですか?

必須項目は「model」、「input」、「voice」、「response_format」です。modelは「tts-1」または「tts-1-hd」を指定します。inputは音声化したいテキスト(最大4096文字)です。voiceやresponse_formatは指定しない場合、デフォルト値が適用されます。

エラーコードの意味は何ですか?

詳細なエラーコード定義は記載されていませんが、リクエスト形式や認証エラーが発生する可能性があります。失敗したリクエストは課金されず、返金が保証されています。具体的なエラー内容を確認するには、APIレスポンスのステータスコードをご参照ください。

レートリミットを超えるとどうなりますか?

1分あたり60リクエスト(初回チャージ前は10リクエスト)の制限があります。これを超えると、リクエストがキューに入れられ、処理待ちになります。リソース効率を重視するゲーム開発において、バッチ処理や間隔調整をお勧めします。

音声ファイルの形式は選べますか?

はい、mp3、wav、opus、flac、pcmの5形式から選択可能です。response_formatパラメータで指定します。ゲームエンジンや配信プラットフォームの要件に合わせて、最適な形式を選択してください。ファイルサイズと音質のバランスを考慮してください。

スピードパラメータの範囲は?

speedパラメータは0.25から4.0の範囲で設定できます。デフォルトは1.0です。NPCの感情や状況に応じて、読み上げの速さを調整できます。ただし、極端な速度変更は音声の自然さに影響を与える可能性があります。

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

必須ではありません。指定しない場合、文字ベースから言語が推測されます(ラテン文字は英語とみなされます)。非英語のラテン文字テキストの場合は、languageパラメータで明示的に言語コードを指定してください。正確な認識のために推奨します。

モデルの選択は必要ですか?

はい、modelパラメータは必須です。「tts-1」または「tts-1-hd」のどちらかを指定します。両者は同じエンジンと価格です。ゲームの品質要件に応じて選択してください。両モデルとも同じAPIエンドポイントで動作します。

音声の長さは制限されていますか?

1リクエストあたりのテキストは最大4096文字です。それを超える場合は、テキストを分割して複数のリクエストを送信し、音声ファイルを結合してください。生成速度は約25文字/秒で、長時間のテキストでも実時間程度の処理になります。

失敗したリクエストは課金されませんか?

はい、失敗したリクエストは課金されません。合成に失敗した場合、料金は全額返金されます。これは開発者のリスクを軽減し、テスト環境での頻回な呼び出しも安心しておこなえるように設計されています。正常なリクエストのみが課金対象となります。

SDKのバージョンは指定されていますか?

SDKのバージョンは特に指定されていません。OpenAI SDKであれば、最新のバージョンでも動作するはずです。base_urlとAPIキーの設定が正しければ、バージョンの違いは影響しません。ただし、最新のSDKを使用することを推奨します。

最初のリクエスト

curl

curl https://api.y7777.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.y7777.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.y7777.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キーの取得

VoicemateのAPIキーを取得するには、まずウェブサイト「/get-api-key/」ページにアクセスしてください。Googleアカウントを使ってワンクリックで登録できます。この方法だと、すぐに0.50ドル相当の無料トライアルクレジット(約5万文字分)が7日間付与されます。メールアドレスとパスワードでの登録でも利用可能ですが、この場合トライアルクレジットは付与されません。

アカウント作成後、ダッシュボード画面でAPIキーを確認できます。初期状態では1分あたり10リクエストという制限があります。最初のチャージを行うと、制限が1分あたり60リクエストに緩和されます。

APIキーの表示場所

APIキーの表示場所

ダッシュボードの「APIキー」セクションで、現在の有効なキーが表示されます。このキーはBearer認証のヘッダーに設定して使用します。

  • 現在のアクティブなキーが常に1つだけ有効です
  • キーの再発行すると、古いキーは直ちに無効になります

キーの再発行

キーの再発行

セキュリティの向上やキーの紛失時に、ダッシュボードから新しいキーを即時発行できます。再発行すると、それまでのキーはすぐに使えなくなるため、使用中の接続がある場合は注意してください。

最初のリクエスト(curl)

の音声波形イラスト: 最初のリクエスト(curl)

VoicemateのAPIは、OpenAI Speechエンドポイントと互換性のあるシンプルなJSONリクエストで動作します。ゲーム開発においてNPCのセリフを即座に生成するには、curlコマンドを使って音声データをダウンロードするだけです。

このセクションでは、APIキーを使用して最初の音声ファイルを生成する具体的な手順を示します。複雑な設定は不要で、テキストと音声スタイルを指定するだけで完了します。

基本的なリクエスト例

以下のコマンドを実行して、音声合成リクエストを送信します。APIキーはAuthorizationヘッダーに設定してください。

```bash curl -X POST https://api.y7777.info/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"}' \ -o speech.mp3 ```

JSONボディの構成

リクエストボディには必須項目としてmodel、input、voice、response_formatを含める必要があります。modelにはtts-1またはtts-1-hdを指定します。

inputフィールドには、最大4096文字までのテキストを設定します。スペースや句読点も文字数にカウントされるため、長いセリフは分割して送信してください。

  • model: tts-1 または tts-1-hd
  • input: 合成対象のテキスト文字列
  • voice: nova, aria, luna, sage, felix, milo, atlas, orion のいずれか
  • response_format: mp3, wav, opus, flac, pcm

レスポンスの確認

リクエストが成功すると、音声データを含むバイナリレスポンスが返されます。指定したファイル名(例: speech.mp3)で保存してください。

生成された音声ファイルは、NPCの台詞としてゲームエンジンに直接読み込めます。音声ファイルには合成音声を示す不可聴の透かしが含まれています。

OpenAI SDKとの連携

の音声波形イラスト: OpenAI SDKとの連携

VoicemateのAPIはOpenAIのspeechエンドポイントと互換性があるため、既存のOpenAI SDKをそのまま利用できます。base_urlのみをVoicemateのAPIベースURLに変更するだけで、同じリクエスト形状で音声合成が可能です。

SDKのインストールは通常の方法で構いません。認証キーはAuthorizationヘッダーにBearer形式で設定してください。これにより、PythonやNode.jsなどの環境ですぐに開発を始めることができます。

base_urlの変更

SDKの初期化時にbase_urlパラメータに https://api.y7777.info/v1 を指定します。これにより、すべてのAPI呼び出しがVoicemateのサーバーにルーティングされます。他のパラメータや構造はOpenAIと同一です。

SDKのインストール

Pythonの場合は pip install openai、Node.jsの場合は npm install openai でインストールできます。バージョンは最新のものをご利用ください。これにより、VoicemateのAPIと互換性のあるクライアントライブラリが利用可能になります。

コード例

以下はPythonでの基本的な音声合成コード例です。APIキーを環境変数から取得し、指定されたテキストから音声ファイルを生成します。このコードはOpenAI SDKの標準的な使い方を踏襲しています。

```python import openai client = openai.OpenAI( base_url="https://api.y7777.info/v1", api_key="YOUR_API_KEY" ) with client.audio.speech.create( model="tts-1", voice="nova", input="ゲームのNPCのセリフを生成中" ) as response: with open("output.mp3", "wb") as f: f.write(response.content) ```

エンドポイントの仕様

の音声波形イラスト: エンドポイントの仕様

VoicemateのAPIは、ゲーム開発に必要な音声生成とメタデータ取得の3つのエンドポイントを提供します。それぞれが独立した役割を持ち、開発ワークフローをスムーズにします。

エンドポイントの仕様はOpenAIの形式を踏襲しており、既存のSDKやツールとの互換性を確保しています。これにより、短いコードでNPCの台詞生成が可能になります。

POST /v1/audio/speech

テキストから音声ファイルを生成する主要なエンドポイントです。JSON bodyでmodel、input、voiceなどのパラメータを指定し、POSTリクエストを送信します。

生成された音声はmp3、wav、opusなどの形式で返されます。最大4096文字までのテキストを一度に処理でき、複数回リクエストすることで長い台詞も生成可能です。

  • リクエストはJSON形式で送信
  • 音声ファイルはレスポンス本体で返却
  • 最大4096文字まで処理可能

GET /v1/voices

利用可能な音声リスト、言語、フォーマット、価格情報を取得します。NPCの性格や役割に合わせた音声プリセットを選定する際に使用します。

8つの音声プリセットと23言語が利用可能です。各音声の特性や対応言語を確認し、ゲームの世界観に最適な音声を選びます。

  • 8つの音声プリセットを確認可能
  • 対応言語とフォーマットの一覧取得
  • 音声の特性や価格情報を確認

GET /v1/models

利用可能なモデルの情報を取得します。tts-1とtts-1-hdの2つのモデルが提供されており、音声の品質と価格の違いを確認できます。

モデル情報を確認することで、プロジェクトの要件に応じた適切なモデルを選択できます。両モデルとも同じエンジンを使用し、価格も同じです。

  • 2つのモデル情報(tts-1、tts-1-hd)
  • 音声品質と価格の確認
  • プロジェクト要件に応じたモデル選択

パラメータの説明

の音声波形イラスト: パラメータの説明

APIリクエストの核心となるパラメータを理解し、NPCの性格やゲームの雰囲気に合わせた音声生成を正確に制御しましょう。VoicemateのTTS APIでは、モデル選択から音声の速度・言語指定まで、リソース効率を最大化するための柔軟な設定が可能です。開発ワークフローに組み込む際、これらのパラメータを正しく設定することで、一貫性のあるクオリティの高いオーディオファイルを生成できます。

modelパラメータ

パラメータmodelにはtts-1またはtts-1-hdのいずれかを指定します。両者は同じ音声エンジンを使用しており、品質や価格の違いはありません。そのため、コストや仕様の統一性を重視する場合はtts-1を、特定の要件がある場合のみtts-1-hdを選択すれば十分です。

inputとvoice

inputには最大4096文字のテキストを指定します。ゲームのNPC台詞やナレーションなど、短く明確なテキストが適しています。voiceは8種類のプリセットから選択します。例えば、序盤のガイドには「aria」、敵キャラクターには「orion」など、キャラクターの性格に合わせた音声を選びましょう。

すべての音声は23言語に対応しており、特定の音声でも多言語で話せます。すべての音声は23言語に対応しており、どの音声でもどの言語でも話せます。ただし、ラテン文字のテキストが英語と誤判定されるリスクがあるため、非英語の場合はlanguageパラメータでISOコードを明示的に指定することを推奨します。

speedとlanguage

speedは0.25から4.0の範囲で再生速度を調整できます。会話のテンポを速めたり、緊張感を演出したりする際に役立ちます。デフォルト値は1.0ですが、NPCの会話リズムに合わせて微調整しましょう。

languageは省略可能ですが、ラテン文字でも英語以外(例:ドイツ語やフランス語)の場合は明示的に指定してください。省略時はスクリプトから推測されますが、英語と誤判定されるリスクがあります。正確な発音のために言語コードの設定を忘れないでください。

パラメータの説明

フォーマットと形式

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

音声ファイルの出力形式はmp3、wav、opus、flac、pcmの5種類から選択できます。各形式は用途に応じて使い分けることで、ストレージ効率や互換性を最適化できます。

mp3とwav

mp3は圧縮形式で、ネットワーク転送やWebアプリケーションでの利用に適しています。wavは非圧縮の標準形式で、ゲームエンジンや編集ソフトウェアとの互換性が高く、即時再生が必要なシーンで推奨されます。

  • mp3: 軽量、Web向け
  • wav: 高品質、ゲーム開発向け

opusとflac

opusは高音質かつ高圧縮率を実現し、帯域幅が限られる環境での配信に最適です。flacは可逆圧縮形式で、wavと同等の音質を維持しつつファイルサイズを削減します。

pcm形式

pcmは生データ形式で、後処理や特殊なオーディオパイプラインへの組み込みに適しています。エンコード/デコードの手間が少ない反面、ファイルサイズが大きくなるため注意が必要です。

  • 生データ: 後処理向け

エラー処理

の音声波形イラスト: エラー処理

API呼び出し時にエラーが発生した場合、適切なエラーコードとメッセージが返されます。これにより、リクエストのパラメータ指定ミスや一時的なシステム障害を迅速に特定できます。

重要な点として、音声合成が失敗したリクエストについては、課金が行われません。失敗したリクエストに対しては、請求額が全額返金される仕組みとなっています。

一般的なエラーコード

リクエストの形式が正しくない場合や、有効なAPIキーが含まれていない場合などに、エラーコードが返されます。開発者は、このレスポンスを確認して原因を特定してください。

失敗時の返金

音声合成の処理中にエラーが発生し、オーディオファイルが生成されなかった場合、そのリクエストは課金対象外となります。アカウントの残高から引き落とされた金額は自動的に返金されます。

タイムアウト

ネットワークの状態やサーバーの負荷により、リクエストの処理に時間がかかる場合があります。ただし、処理が正常に完了しなかった場合は、前述の返金ポリシーが適用されます。

レートリミット

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

APIキーごとに1分間あたり60リクエストの制限があります。長文の生成ではテキストを4096文字ずつ分割して複数回呼び出す必要があるため、この制限を考慮した実装が重要です。

1分間60リクエスト

1分あたりの最大処理数は60リクエストです。短く単純な音声生成では余裕がありますが、ゲームのNPC台詞を大量に生成する場合は、バッチ処理のタイミングを調整してください。

初回の制限

新規アカウントまたは未課金状態では、1分あたり10リクエストの制限が適用されます。最初のチャージを行うと制限が解除され、標準の60リクエスト/分にアップグレードされます。

キューの仕組み

リクエストは順次処理されるため、負荷が高い時間帯にはキューに待機することがあります。生成速度はリアルタイムに近づきますが、キュー待ちにより完了まで数秒かかる場合があります。

8つの音声を確認

以下の各サンプルは、同じ文章をこのAPIで生成したものです。 ただし、生成された音声ファイルには合成音声を示す不可視の透かしが埋め込まれており、これが人工知能による生成音源であることを示しています。

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

23言語

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

出典および参考資料

  1. Wikipedia
  2. Tether (USDT)
  3. FFmpeg documentation
  4. openai-python on GitHub
  5. IETF RFC 7845: Ogg Opus
  6. openai-node on GitHub
  7. ISO 639 language codes
  8. curl documentation
  9. Creative Commons Attribution 4.0
  10. MDN: Web Speech API
  11. Python documentation
  12. LibriTTS-R paper (arXiv 2305.18802)

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