開発者向けクイックスタート
APIに最初のリクエストを送り、録音を文字に変換してみましょう。例では個人用APIキーとcurlを使えるターミナルを使用します。
APIキーを作成する
APIダッシュボードでキーを作成し、APIの請求と利用状況を確認します。キーのスコープを制限する場合は、以下の例のためにdictationとtranscriptionを含めます。
ターミナルで環境変数を設定し、プレースホルダーを自分のキーに置き換えます。アプリを開発する際はキーをサーバー側に保管してください。
export AQUA_API_KEY="your-api-key"

認証を確認する
curl --fail-with-body https://api.aquavoice.com/v1/me \
-H "Authorization: Bearer $AQUA_API_KEY"
レスポンスに現在のユーザーと認証情報が表示されます。401の場合はキーと有効期限を確認します。組織のキーにはユーザー選択の追加ルールがあります。APIリファレンスの認証をご覧ください。
話した言葉を文章にする
短い録音を作業ディレクトリのaudio.wavに保存します。このリクエストでは、アカウントの辞書、置換、カスタム指示が適用されます。
curl --fail-with-body https://api.aquavoice.com/v1/dictations \
-H "Authorization: Bearer $AQUA_API_KEY" \
-F "audio=@audio.wav" \
-F "operation=dictate" \
-F "language=en"
JSONレスポンスのtextに完成した文章が入ります。session_id、language、duration_secondsも返ります。プライバシーと保存の設定が適用されます。この例は英語を指定しています。日本語の音声にはlanguage=jaを使います。
音声で編集するには、operation=editと、変更対象の文章を入れたselected_textを送ります。録音には編集の指示を含めます。返されたtextが置換後の文章です。適用前にedit_unclearとedit_deletedを確認してください。音声入力エンドポイントをご覧ください。
Avalonでファイルを文字起こしする
録音をaudio.mp3に保存して呼び出します。文字起こしはtextフィールドで返ります。
curl --fail-with-body https://api.aquavoice.com/v1/audio/transcriptions \
-H "Authorization: Bearer $AQUA_API_KEY" \
-F "file=@audio.mp3" \
-F "model=avalon-v1.5" \
-F "response_format=json"
字幕にはresponse_format=srtまたはvttを使います。話者ラベルにはdiarize=trueとresponse_format=diarized_jsonを指定します。処理が長い場合は非同期の文字起こしを利用できます。
エラーと再試行
- サポートへの問い合わせ用にレスポンスの
X-Request-Idを記録します。 403は必要なスコープがない場合などに返ります。本文とダッシュボードの設定を確認します。429ではRetry-Afterに従います。- 再試行する可能性がある音声入力には、その録音とリクエストに固有の
Idempotency-Keyを付けます。同じリクエストの再試行には同じキーを使います。 - 同期の文字起こしは、処理が継続中でも
error.job_idを含む504 request_timeoutを返す場合があります。重複作成せず、そのジョブの状態を取得します。
制限、レスポンス、請求、データの扱いはAPIリファレンスをご覧ください。ターミナルから使うにはCLIリファレンス、AIアプリとの接続にはMCPドキュメントがあります。