生成AIを利用した開発

AmiVoice API の公式ドキュメントを生成 AI やコーディングエージェントに参照させて、インタフェースの選定、仕様の調査、サンプルコードの生成などに役立てる方法を説明します。

llms.txtとは

llms.txtは、AmiVoice API の主要な仕様とドキュメントへのリンクを 1 つにまとめた、生成 AI 向けの索引ファイルです。次の URL で公開しています。

https://docs.amivoice.com/llms.txt

サイト全体のページを並べたものではありません。方式の選定、実装、運用で先に読むべきページを選んでまとめています。リンク先は、生成 AI が取得しやすい Markdown 版のドキュメントです。

できること

llms.txtを生成 AI に渡すと、次のような作業に利用できます。

• 使用するインタフェースやパラメータの調査
• 要件に合った方式の選定
• サンプルコードの生成
• 新しい機能を使った開発の支援
• コードレビュー

いずれも、公式ドキュメントを根拠として参照させることが目的です。

利用方法

生成 AI への指示に、llms.txtの URL を追加して使用します。「この URL を起点に、リンク先の公式ドキュメントを参照してください」と伝えると、生成 AI が必要なページを開いて回答します。

正確な回答を得るために、次の 3 点も指示に加えてください。

• パラメータ名や仕様を推測しないこと
• 公式ドキュメントに書かれていないことは、書かれていないと示すこと
• 回答に、参照した公式ドキュメントの URL を示すこと

llms.txtの冒頭には、実装するときに守ってほしい規則も書いてあります。たとえば「HTTP ステータスだけで成功を判定しない」「API キーをログや設定ファイルへ出力しない」といった規則です。生成 AI は、URL を渡されただけではこの規則を読み飛ばすことがあります。コードを書かせるときやレビューさせるときは、「冒頭の規則に従ってください」とはっきり伝えてください。

プロンプト例

そのままコピーして使えるプロンプトの例です。目的に応じて、音声の条件や実装したい内容を書き換えてください。

インタフェースを選定する

録音済みのファイルを扱う場合の例です。

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

録音済みの30分程度の音声ファイルを文字起こしする場合に、
使用すべきインタフェース、接続エンジン、必要なリクエストパラメータを整理してください。

パラメータ名や仕様を推測せず、
回答には参照した公式ドキュメントのURLを示してください。

リアルタイムに音声を送る場合の例です。

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

ブラウザからマイク音声をリアルタイムで送信し、
認識途中結果を画面に表示したいです。

同期HTTP、非同期HTTP、WebSocketのどれを使用すべきか、
理由、実装手順、参照すべきドキュメントを整理してください。

サンプルコードを生成する

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

16kHz、モノラル、WAV形式の音声ファイルを同期HTTPインタフェースで
文字起こしするPythonコードを作成してください。

APIキーは環境変数から取得し、URLのクエリ文字列には含めないでください。
HTTPエラーとレスポンス本文の結果コードを処理してください。
llms.txtの冒頭にある実装時の規則に従い、
存在しないエンドポイントやパラメータを推測しないでください。

回答には参照した公式ドキュメントのURLも示してください。

作成したコードをレビューする

生成 AI に書かせたコードは、そのまま使わずに、公式ドキュメントと照らし合わせるレビューを別に行ってください。コードを書いたときとは別の会話（セッション）で行うと、書いたときの思い込みを引き継がずに済みます。変更した部分だけでなく、API を呼び出すコード全体を対象にします。

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

このコードのうち、AmiVoice APIを呼び出す部分全体を、
公式ドキュメントと照らし合わせてレビューしてください。

まず、llms.txtの冒頭にある実装時の規則を1つずつ取り上げ、
コードが守っているかを規則ごとに確認してください。
次に、エンドポイント、パラメータの名前と書式、音声データの送り方、
結果コードの扱い、ログ保存の設定、制限値を、リファレンスと照らし合わせてください。

公式ドキュメントに書かれていない処理は、正しいと推測せず、書かれていないと示してください。
指摘には、該当するコードの場所と、根拠にした公式ドキュメントのURLを示してください。

認識精度を改善する

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

専門用語を多く含む音声の認識精度を上げたいです。
ユーザー辞書や接続エンジンの選択など、利用できる方法を整理し、
それぞれの設定手順と参照すべきドキュメントを示してください。

仕様を推測せず、回答には参照した公式ドキュメントのURLを示してください。

エラーを調査する

https://docs.amivoice.com/llms.txt を起点として、
リンク先のAmiVoice API公式ドキュメントを参照してください。

同期HTTPインタフェースのレスポンスで返る結果コードの意味と、
想定される原因、対処方法を整理してください。

HTTPステータスだけでなくレスポンス本文の結果コードも確認する前提で、
仕様を推測せず、参照した公式ドキュメントのURLを示してください。

生成AIが間違えやすい点

生成 AI を使って、AmiVoice API のコードを書くと次のような誤りをしやすいようです。生成 AI が書いたコードを確認するときには、特にこれらの点を見てください。

• API キーの送り方と置き場所: API キーを URL のクエリ文字列に入れてしまうことがあります。クエリ文字列は通信経路のログに残るため、API キーはマルチパートの HTTP ボディかAuthorizationヘッダで送ります（同期 HTTP インタフェース）。ブラウザで動くアプリケーションでは、所有している API キーを利用者のマシンへ送らず、有効期限や IP アドレスの制限付きの API キーを使ってください（API キーに付与できる制限・機能）。
• 成功かどうかの判定: 同期 HTTP では、HTTP ステータスだけを見て、成功として扱ってしまいます。AmiVoice APIの同期 HTTP では、認識に失敗しても200OKを返します。レスポンス本文のcodeとmessageに原因が入り、成功したときだけcodeが空文字になります（レスポンスコードとメッセージ）。HTTP ステータスだけを見て、成功として扱わないようにしてください。
• パラメータの書式: dに複数のパラメータを入れるときに、接続エンジン名をgrammarFileNames=なしで書き、値を URL エンコードしていないケースがあります。値にスペースが含まれると、パラメータが正しく渡らないことになります。同期 HTTP や非同期 HTTP では、パラメータをマルチパートで送り、音声データを最後のパートに入れます（同期 HTTP インタフェース）。
• インタフェースの選び方: 録音済みの音声ファイルを、サイズを確かめずに同期 HTTP で送ってしまう。同期 HTTP で送れる音声データには上限があり、長い録音や大きなファイルには非同期 HTTP を使います（インタフェースの種類と使い方、制限事項）。
• ログ保存ありのエンドポイントの利用: ログ保存ありのエンドポイントの利用を明示しないことがあります。ログ保存ありのエンドポイントに音声を送信すると音声データをサービス改善に使うことに合意して提供することになります（ログ保存）。意図に反してログ保存ありのエンドポイントを使わないようにしてください。
• ユーザー辞書の使い方: ハイブリッドエンジンではユーザー辞書が 8k 用と 16k 用に分かれるのに、adfを指定せず 16k 用しか扱えない不具合を作ることがあります（ユーザー辞書登録API）。また、ユーザー辞書を利用するためにprofileIdの設定が必要です(ユーザー辞書を利用する方法)。

llms.txtの規則やリンク先のページに書いてある内容です。最初からllms.txtを参照させ、規則を守るように指示すると防ぎやすくなります。

Webページを参照できないAIでの利用方法

llms.txtを URL で参照するには、生成 AI に Web ページを読む機能が必要です。その機能がない場合は、内容を直接プロンプトへ貼り付けて使用します。

https://docs.amivoice.com/llms.txt

ただし、llms.txtはリンクの一覧です。貼り付けただけでは、リンク先の詳しい仕様までは伝わりません。次の手順で使用してください。

1. llms.txtの内容を貼り付けて、目的に必要なページを特定させる。
2. 特定したページの Markdown 版ドキュメントも、続けて貼り付ける。

Markdown 版は、ページの URL の末尾に.mdを付けると取得できます。たとえば、はじめにのページはhttps://docs.amivoice.com/amivoice-api/manual/getting-started.mdです。

llms.txtでできないこと

llms.txtは、公式ドキュメントを見つけて参照しやすくするためのものです。次のことはできません。

• 生成 AI が AmiVoice API へ自動的に接続する
• 生成 AI が AmiVoice API をツールとして直接実行する
• 生成されたコードの正しさを保証する

生成されたコードは、必ず公式リファレンスと照らし合わせてから使用してください。そのうえで、実際に API を呼び出して動作を確かめてください。誤った API キーを使うなど、わざと失敗させたときの動作も確かめると、エラー処理の誤りが見つかります。

利用上の注意

音声認識 API を扱うため、特に次の点に注意してください。

APIキーと音声データの取り扱い

• APIキー、音声データ、個人情報などを生成AIへ入力する場合は、利用規約や所属組織等のセキュリティルールを確認してください。また、コードやエラーログを入力する際にも、これらの情報が意図せず含まれていないか必ず確認してください。
• APIキーそのものを提示する必要がない場合は、ダミー値や環境変数名に置き換えてください。

• 生成されたコードは、公式リファレンスと照合してから使用してください。
• 料金、制限事項、利用規約、SLA は、必ず現行の公式ページで確認してください。