よくある質問
APIキーはどのように生成しますか?
サイト内の/get-api-key/ページでGoogleまたはメールアドレスとパスワードでサインアップすると、APIキーが生成されます。アカウントには有効なキーが1つだけ割り当てられ、必要に応じて再発行も可能です。
OpenAI SDKはそのまま使えますか?
はい、公式のOpenAI SDKをそのまま使用できます。base_urlをhttps://api.rv777.info/v1に変更し、サイト発行のAPIキーを使用するだけで動作します。
リクエストのJSON形式は?
POST https://api.rv777.info/v1/audio/speech へ、model、input、voice、response_format、speed、languageのフィールドを含むJSONボディを送信します。認証にはAuthorizationヘッダーにBearerトークンを設定します。
音声ファイルのフォーマットは選べますか?
mp3、wav、opus、flac、pcmの5つのフォーマットから選択可能です。response_formatフィールドで指定することで、必要な形式の音声ファイルを取得できます。
速度はどのくらい調整できますか?
speedパラメータで0.25から4.0の範囲で再生速度を調整できます。デフォルト値は1.0で、それより遅くまたは速く音声の再生速度を変更することが可能です。
言語を自動検知はどれくらい正確ですか?
言語が指定されない場合、スクリプトから推測されます。ラテン文字のテキストはデフォルトで英語とみなされるため、英語以外のラテン文字テキストにはlanguageフィールドを明示的に設定してください。
4096文字を超えるテキストはどう処理しますか?
4096文字ごとにテキストを分割し、それぞれの音声ファイルを生成します。その後、生成された音声ファイルを結合して1つの長い音声ファイルとして扱います。
レートリミットを超えた場合はどうなりますか?
1分あたり60リクエストの制限があります。制限を超えた場合は、キューに待機して順番に処理されます。最初のトップアップ前は1分あたり10リクエストです。
エラー時のレスポンス形式は?
合成に失敗した場合、課金は全額返金されます。エラー時のレスポンス形式は特に明記されていませんが、失敗したリクエストには費用がかかりません。
APIキーを再発行すると古いキーはどうなりますか?
新しいキーを発行すると、古いキーは直ちに無効になります。同時に有効なキーは1つだけになるため、新しいキーに切り替えてください。
音声ファイルの形式はPCMも含みますか?
はい、PCMフォーマットも選択可能です。response_formatフィールドで「pcm」を指定することで、PCM形式の音声ファイルを取得できます。
音声の生成には時間がかかりますか?
長いテキストではリアルタイム速度(1秒あたり約25文字)で生成されます。短いフレーズでも数秒かかり、負荷が高い場合はキューに待機する場合があります。
ストリーミングはサポートされていますか?
いいえ、ストリーミングやWebSocket、リアルタイムの部分的な音声はサポートされていません。テキストを送信すると、音声ファイルが返されます。
SSM Lは使えますか?
いいえ、SSMLはサポートされていません。
最初のリクエスト
curl
curl https://api.rv777.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.rv777.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.rv777.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 |
APIキーの取得
不動産ナレーション作成の第一歩は、APIキーの取得です。rv777.infoの/get-api-key/ページでGoogleアカウントまたはメールアドレスによるサインアップを行い、認証を完了させてください。
認証が完了すると、ダッシュボードに一意のAPIキーが表示されます。このキーを使って、音声合成APIのすべてのエンドポイントにアクセスできます。
Google認証でのサインアップ
Google認証を利用すると、すぐに$0.50の無料トライアルクレジット(約5万文字分)が付与され、7日間有効になります。メールアドレスのみで登録した場合は、トライアルクレジットは付きません。
アカウントはサイトごとに独立しており、Google認証でもパスワード認証でも、安全にキーを管理できます。
APIキーの生成と表示
ダッシュボードでは、生成されたキー、残高、使用状況がリアルタイムで確認できます。キーはBearer認証ヘッダーに設定して使用します。
キーは1アカウントにつき1つ有効です。必要に応じて後述の通り再発行が可能です。
キーの再発行と有効期限
キーはいつでも再発行できます。新しいキーを発行すると、古いキーは即時無効になります。これにより、キーの漏洩時に迅速に対応できます。
キー自体に有効期限はありませんが、トライアルクレジットの期限(7日間)には注意してください。
音声生成エンドポイント
音声合成APIのエンドポイントは、テキストデータを音声ファイルに変換するための核心部分です。POST https://api.rv777.info/v1/audio/speech へリクエストを送信することで、指定したパラメータに従って音声合成が実行され、生成されたオーディオファイルが返されます。
POST /v1/audio/speechの仕様
不動産映像のナレーション作成では、テキスト入力に対して音声ファイルが得られるこのエンドポイントが主要な操作となります。リクエストはJSON形式で送信し、成功時には対応するオーディオデータがレスポンスとして返されます。
JSONリクエストボディの構造
リクエストボディには、model、input、voice などの必須フィールドを含める必要があります。これらの設定により、生成される音声の質や話し手、テキスト内容が決まります。input フィールドには最大4096文字までのテキストを指定します。
base_urlの変更方法
公式OpenAI SDKを用いる場合、base_url を https://api.rv777.info/v1 に変更することで連携可能です。これにより、既存のコードベースを最小限の変更で当APIに接続できます。認証には Authorization: Bearer tts-... ヘッダーを使用します。
必須パラメータの設定
APIリクエストの核心となる必須パラメータを設定します。これらは音声ファイルの生成品質と内容を決める重要な要素です。
model、input、voiceの3つを正しく指定することで、目的のナレーションを確実に取得できます。
model (tts-1, tts-1-hd) の選択
両モデルは同一の音声エンジンを使用し、価格も$10/100万文字で同じです。標準的な不動産紹介やツアー案内には「tts-1」で十分です。
高音質が求められる詳細な物件説明や、静かな環境での視聴を想定する場合は「tts-1-hd」を選択してください。機能的な差はありません。
input (テキスト) の制約
1回のリクエストで送信できるテキストは最大4,096文字です。これを超過する長文ナレーションを送信するとエラーとなります。
長文の場合は、4,096文字ごとに分割して複数回リクエストし、生成された音声ファイルを結合する必要があります。スペースや句読点も文字数にカウントされます。
voice の8つのプリセット
8種類のプリセットから、映像のトーンに合う声質を選択します。女性4声(aria, nova, luna, sage)と男性4声(felix, milo, atlas, orion)があります。
例えば、活発なプロモーション動画には「felix」や「nova」を、静かな環境での視聴には「luna」や「atlas」が適しています。
すべての音声は23言語に対応しており、必要に応じて「language」パラメータで言語を明示することも可能です。
- aria: 暖かみのあるクリアなナレーター
- nova: 明るく元気なトーン
- luna: 柔らかく物語的な語り
- sage: 落ち着いた指導的な声
オプションパラメータ
音声ファイルの形式や速度、言語を指定して、不動産ナレーションやバーチャルツアーの音声に最適化できます。mp3はWeb配信向け、wavは無圧縮音声、opusは高効率な圧縮形式、flacはロスレス音声、pcmは生データです。
速度を調整すれば、視聴者の理解度に合わせたテンポに調整可能です。言語を明示することで、ラテン文字のテキストでも正しい発音を保証できます。
response_format の選択
出力形式はmp3、wav、opus、flac、pcmから選べます。mp3はWeb配信向けで汎用性が高く、wavは無圧縮音声として高品質な納品や編集用に向きます。opusは高効率な圧縮形式でファイルサイズを小さく保ちます。flacはロスレス音声で、pcmは生データとして扱いたい場合に適しています。
用途に合わせて最適な形式を選んでください。
- mp3: Web配信向け
- wav: 無圧縮音声
- opus: 高効率な圧縮形式
- flac: ロスレス音声
- pcm: 生データ
speed (0.25–4.0) の調整
speedパラメータで生成速度を0.25から4.0の範囲で調整できます。デフォルトは1.0です。不動産物件の解説では、視聴者が詳細を確認できるよう少し遅く設定するのが推奨されます。
逆に、短い案内文や通知音のような用途では、速度を上げて効率的に音声を作成しましょう。
language (ISOコード) の指定
languageパラメータでISO言語コードを指定できます。指定しない場合、文字スクリプトから言語が推測されますが、ラテン文字のテキストはデフォルトで英語とみなされるため、英語以外のラテン文字テキストでは明示的な指定が重要です。
これにより、正確な発音を保証し、不動産の説明音声の品質を向上させます。
cURLでのテスト実行
cURLコマンドを使ってAPIの動作を直接確認しましょう。リアルタイムで音声ファイルが生成される様子を、複雑な環境構築なしで手軽にテストできます。
まず、認証キーと合成したいテキスト準備してください。コマンドラインから送信し、音声データをローカルに保存するまでの一連の流れを確認します。
準備するcURLコマンド
POST https://api.rv777.info/v1/audio/speech に対してJSONボディを送信します。テキストは4096文字以内で指定してください。
- エンドポイントURLの確認
- JSONボディの準備
認証ヘッダーの設定
Authorizationヘッダーに、ダッシュボードで取得したBearerキーを設定します。これにより、あなたのアカウントの残高から課金が適切に処理されます。
- Authorization: Bearer YOUR_API_KEY
レスポンスの受信と保存
正常な応答では音声バイナリデータが返されます。-o オプションを使用して、mp3やwavなどの形式でローカルファイルとして保存できます。
- -o output.mp3
- ファイル形式の確認

OpenAI SDKとの連携
AmaeKoeのTTS APIはOpenAIのspeechエンドポイントと互換性があるため、既存のOpenAI SDKをそのまま利用できます。base_urlを https://api.rv777.info/v1 に変更し、APIキーを設定するだけで、リアル estate やバーチャルツアー用の音声生成が開始できます。
この互換性により、複雑なカスタムクライアント構築の手間を省き、PythonやNode.js環境ですぐにコードを組み込めます。
base_urlの変更手順
OpenAI SDKを使用する場合、初期化時に base_url パラメータを https://api.rv777.info/v1 に設定します。APIキーは Authorization: Bearer ヘッダーに設定されたAmaeKoeのキーを使用します。これにより、標準のspeechエンドポイント呼び出しが自動的にリダイレクトされます。
- base_url: https://api.rv777.info/v1
- 認証: Bearer <YOUR_API_KEY>
PythonまたはNode.jsでの実装例
Pythonでは openai クライアントを初期化し、audio.speech.create メソッドを呼び出します。テキストは4096文字以内に制限し、voiceパラメータでariaやatlasなどのプリセットを指定します。Node.jsでも同様に、OpenAI クラスのインスタンスを作成し、base_urlを設定することで同等の処理が可能です。
生成された音声ファイルはバイト列として返されるため、mp3やwav形式でファイルに保存してください。
SDKのエラーハンドリング
レートリミット超過時や無効なパラメータ送信時には、SDKが適切なHTTPエラーコードを返します。特に、テキスト長超過(4096文字超)や音声生成失敗時には、エラーメッセージを確認してテキストを分割するか、パラメータを修正してください。失敗したリクエストは課金されません。
レートリミットとキュー
APIは1分間あたり60リクエストという明確な制限を設けています。不動産物件のナレーションやバーチャルツアー音声を一括生成する際、この上限に達すると新しいリクエストはキューに入れられます。
キューの待ち時間は負荷状況により変動しますが、短時間のバッチ処理でも安定した生成が可能になるよう設計されています。
60リクエスト/分の制限
認証キーごとに1分あたり最大60回のリクエストが許可されます。これは音声生成エンジンが一つずつ処理を行うためです。
長時間のテキストを分割して送信する場合でも、合計数がこの制限を超えないように調整してください。
- 1分間: 60リクエストまで
- キー単位でのカウント
初回トップアップ前の制限
アカウント作成直後やトップアップ前の期間中は、1分あたりのリクエスト数が10回に制限されます。
これは初回の利用制限です。
- 制限: 1分間10リクエスト
- トップアップ後に緩和
キューの待ち時間と対策
リクエストがキューに入ると、処理順に待機します。短時間のテキストは数秒で完了しますが、長文では待ち時間が生じる可能性があります。
バッチ処理時は、リクエスト間隔を空けるか、並列数を調整することでキューの混雑を軽減できます。
- 待ち時間は負荷に依存
- 間隔を空けて送信
エラー処理とデバッグ
API呼び出し時には、認証エラーやリクエスト形式の誤りによりHTTPステータスコードが返されます。具体的なエラーコードと対応方法を理解することで、開発プロセスのトラブルシューティングを迅速化できます。
生成失敗時は料金が返金されるため、テストを実施できます。テキスト長やフォーマットの検証は、安定した音声合成処理のために不可欠です。
一般的なHTTPステータスコード
認証失敗時は401 Unauthorized、リクエスト形式の誤りには400 Bad Request、レート制限超過には429 Too Many Requestsが返されます。これらを確認し、Authorizationヘッダーのキーやリクエストパラメータを修正してください。
テキスト長超過のエラー
inputフィールドのテキストは1リクエストあたり4096文字までです。これを超える場合、エラーが発生します。長文を処理するには、4096文字ずつ分割して複数のリクエストを送信し、得られた音声ファイルを結合する必要があります。
音声生成失敗時のレスポンス
サーバー側の一時的な問題や無効なパラメータにより生成が失敗した場合、対応するHTTPエラーコードが返されます。この場合、請求は発生せず、料金は全額返金されます。
8つの音声を確認
以下の各サンプルは、同じ文章をこのAPIで生成したものです。 生成プロセスが完了すれば、元のテキストデータは即座に破棄され、他の目的やトレーニングデータとしての再利用は行われません。
23言語
どの音声でも、これらの言語のいずれかを話します。
出典および参考資料
- Wikipedia
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- ISO 639 language codes
- openai-python on GitHub
- openai-node on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- MDN: Web Speech API
- FFmpeg documentation
- curl documentation
