開発者向けクイックスタート

APIに最初のリクエストを送り、録音を文字に変換してみましょう。例では個人用APIキーとcurlを使えるターミナルを使用します。

APIキーを作成する

APIダッシュボードでキーを作成し、APIの請求と利用状況を確認します。キーのスコープを制限する場合は、以下の例のためにdictationとtranscriptionを含めます。

ターミナルで環境変数を設定し、プレースホルダーを自分のキーに置き換えます。アプリを開発する際はキーをサーバー側に保管してください。

export AQUA_API_KEY="your-api-key"
ローカルのデモ用アカウントでのAPIキー作成画面。画面は英語表示です。
ローカルのデモ用アカウントでのAPIキー作成画面。画面は英語表示です。

認証を確認する

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ドキュメントがあります。