コンテンツにスキップ
RouteAPI RouteAPI

音声からテキスト

RouteAPI は OpenAI の 2 つの音声認識エンドポイントを公開しています。文字起こしは元の言語でテキストを返し、翻訳は常に英語を返します。どちらも multipart/form-data で送信し、結果は同じレスポンスで返ります（非同期タスクやポーリングの手順はありません）。認証はモデル API と同じ API Key です。

エンドポイント用途レスポンス
POST /v1/audio/transcriptions音声を元の言語のテキストに変換response_format に応じて JSON またはテキスト
POST /v1/audio/translations音声を英語テキストに変換response_format に応じて JSON またはテキスト

クライアントの Base URL を /v1 なしで設定している場合も、POST /audio/transcriptions と POST /audio/translations は利用できます。ゲートウェイが内部で /v1 付きのパスに書き換えます。

文字起こし

Section titled “文字起こし”

音声ファイルを元の言語で文字起こしします。multipart/form-data で送信してください。

POST /v1/audio/transcriptions
https://api.routeapi.ai/v1/audio/transcriptions

リクエストパラメータ

Section titled “リクエストパラメータ”
フィールドタイプ必須説明
filefileはい音声ファイル。最初の file パートのみが転送されます
modelstringはい文字起こしモデル ID（例: whisper-1、gpt-4o-transcribe、gpt-4o-mini-transcribe）
response_formatstringいいえ要求する出力形式（json、text、srt、vtt、verbose_json など）。RouteAPI は自身のデフォルトとして json を記録しますが、転送するフォームにデフォルト値を書き込みません。フィールドを省略すると上流が独自のデフォルトを適用し、上流のボディはそのまま返されます
languagestringいいえISO-639-1 の言語ヒント。上流に転送されます
promptstringいいえコンテキストや用語のヒント。上流に転送されます
temperaturenumberいいえサンプリング温度。上流に転送されます
timestamp_granularities[]arrayいいえタイムスタンプの詳細レベル。転送され、上流で verbose_json と組み合わせた場合にのみ意味を持ちます

その他のフォームフィールドも転送されます。 ゲートウェイはあなたのフォームから multipart ボディを再構築します。model は自身で書き込み、最初のファイルパートをコピーし、他のすべてのテキストフィールドをそのままコピーします。RouteAPI が検証するのは model のみで、chunking_strategy などのフィールドが有効かどうかは上流モデルが決定します。

例

Section titled “例”
Terminal window
curl https://api.routeapi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./meeting.mp3" \
  -F "model=whisper-1" \
  -F "response_format=json" \
  -F "language=en"
import os


from openai import OpenAI


client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)


with open("meeting.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio_file,
        response_format="json",
    )


print(transcript.text)

レスポンス

Section titled “レスポンス”

上流のレスポンスボディは、Content-Type と Content-Length を正規化したうえでそのまま返されます。response_format が json（OpenAI 互換上流のデフォルト）の場合、次のようになります:

{
  "text": "This is the transcribed content of the uploaded audio."
}

verbose_json の場合は通常 task、language、duration、segments も返されます。text、srt、vtt の場合はボディが JSON ではなくプレーンテキストになります。これらのどれが特定のモデルでサポートされるかはプロバイダが定義しており、RouteAPI はボディを再整形しません。

翻訳

Section titled “翻訳”

文字起こしと同じ multipart 形式ですが、出力は入力言語に関係なく常に 英語テキスト です。同じフィールド（file、model、response_format、prompt、temperature）が適用されます。ソース言語はモデルが検出するため、翻訳の契約に language パラメータはありません。ゲートウェイは追加のフォームフィールドを転送しますが、それらを受け付けない上流はリクエストを拒否する可能性があります。

POST /v1/audio/translations
https://api.routeapi.ai/v1/audio/translations
Terminal window
curl https://api.routeapi.ai/v1/audio/translations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "file=@./interview-de.mp3" \
  -F "model=whisper-1"
import os


from openai import OpenAI


client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)


with open("interview-de.mp3", "rb") as audio_file:
    result = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )


print(result.text)

課金

Section titled “課金”

音声認識の呼び出しは、他のすべてのモデル API 呼び出しと同じウォレットとクォータの仕組みで課金されます。見積もりが事前に課金され、上流の応答後に確定し、失敗した呼び出しは返金されます。価格はモデルの設定から取得されます。価格がモデルの詳細ページでどのように表示されるかはモデル料金を参照してください。

  • 上流のレスポンスに 0 でない total_tokens を持つ usage オブジェクトが含まれる場合、その使用量が課金対象になります（prompt_tokens/completion_tokens がない場合は input_tokens/output_tokens が使用されます）。
  • 上流が使用量を報告しない場合、ゲートウェイは長さの見積もりにフォールバックします。アップロードされた音声 1 分あたり 1000 トークンで、出力トークンはありません。トークン課金モデルでは、同じ見積もりが事前課金にも使われます（ゲートウェイの全リクエスト共通の最低事前課金額が下限になります）。
  • 報告された使用量に音声トークンの詳細が含まれる場合、そのトークンは音声料率で価格付けされます。そうでない場合は通常の入力トークンとしてモデルの倍率で価格付けされます。長さフォールバックには音声の詳細がないため、1 分あたり 1000 トークンが 1 分あたりの料率と一致します。
  • フォールバックが適用される場合、文字起こしのコストは返されるテキストの量ではなく音声の長さに比例します。上流が使用量を報告する場合は、報告された内訳が優先されます。

エラー

Section titled “エラー”

音声リクエストは標準の { "error": { ... } } ボディを使用し、メッセージにはコンソールのログで検索できる request ID が含まれます。完全な一覧はよくあるエラーを参照してください。

ステータスコード原因
400invalid_requestmodel が欠落または空（Missing required field: model）
403insufficient_user_quota / pre_consume_token_quota_failedアカウント残高または Key のクォータが見積もり費用に足りない
403—モデルが Key のモデル許可リスト外（This token has no access to model ...）
429—リクエストのレート制限を超えた
503model_not_foundモデルに利用可能なチャネルがない（No valid upstream service）
500count_token_failedアップロードされた音声の長さを計測できない（未対応の拡張子またはコンテナ）
500convert_request_failedリクエストをチャネル向けに変換できない。例えば file パートのない文字起こしや、音声を実装していないアダプタのチャネル
4xx / 5xx上流のコードプロバイダがリクエストを拒否しました。ステータスとメッセージはそのまま返されます
{
  "error": {
    "message": "Missing required field: model (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

見落としやすい 2 つの失敗パターンは、プロバイダの問題と誤解しやすいため、事前に把握しておく価値があります:

  • file の欠落 は、文字起こしや翻訳でゲートウェイの検証レイヤーでは捕捉されず、後で convert_request_failed として表面化します。フィールド名が正確に file であること、クライアントが実際にパートを添付していることを確認してください。
  • 未対応の音声コンテナ は、上流呼び出しの前のトークン見積もり段階で失敗するため、上流エラーではなく count_token_failed として報告されます。

リクエストが失敗した場合、事前に課金された金額は返金されます。

次のステップ

Section titled “次のステップ”
  • テキスト読み上げ — テキストから音声を生成します。
  • モデル — 音声エンドポイントを呼び出す前に、モデル ID があなたの Key から見えることを確認します。
  • モデル料金 — 音声の入力価格と出力価格の表示方法。
  • よくあるエラー — ステータスコード、エラーボディ、トラブルシューティングの順序。