Azure OpenAIのapi-versionとは？v1 APIへの移行とバージョン固定の判断

手元のコードは去年から変えていないのに、モデルを新しいものへ差し替えた途端にパラメータ不正で落ちる。あるいは公式のサンプルを写したら、今度は api-version を付けるなと怒られる。どちらもコードの書き方の問題ではなく、api-version というクエリパラメータが指し示している「仕様書」が食い違っているために起きます。この記事では、api-version が何を切り替えるパラメータなのか、2026年8月16日時点で使える値をどこで調べるのか、版の差でどの引数が壊れるのか、そして固定と追随のどちらを運用方針に据えるべきかを、Microsoft LearnとAzureのREST API仕様リポジトリの実測から整理します。

まとめ：api-versionで決めるのは体系・チャネル・固定方針の三点

結論から書きます。api-version をめぐって実装者が決めるのは三点です。第一に、日付付きの旧体系と v1 体系のどちらに乗るか。新規実装なら v1 体系を選び、api-version の指定そのものを持ち込まないのが素直な選択になるでしょう。

第二に、v1 体系の中で GA と プレビューのどちらのチャネルを使うか。v1 では api-version が必須パラメータではなくなった代わりに、値として受け付けるのは日付ではなく v1 と preview の2つだけという構造に変わりました。2026年8月16日時点の公開仕様を実測すると、GA側は71パス、プレビュー側は81パスで、差の10パスはすべて音声・画像・動画の生成系です。これらを使う実装は、api-version を省くのではなく preview を明示する側に回る必要があります。

第三に、選んだ値を固定するか自動で追随させるか。ここは案件の性格で割れる論点なので、後半の運用方針の章で条件付きに言い切ります。サービス全体の位置づけから確認したい場合はAzure OpenAI Serviceとは？できること・料金・導入事例まで実務目線で解説を先に読むと、この記事の話が接続しやすくなります。

api-versionクエリの役割と日付方式からv1方式への切り替わり

api-version は認証情報でもモデル指定でもありません。そのリクエストを「どの仕様書に沿って解釈するか」をサーバーへ伝えるための指定です。ここを取り違えると、モデルを替えたのにパラメータが通らないという症状の原因を延々とコード側で探すことになります。

日付付きapi-versionはリクエスト単位で仕様書を選ぶスイッチ

旧来の体系では、サービスAPIは api-version クエリパラメータでバージョン管理され、値はすべて YYYY-MM-DD の日付構造に従っていました。呼び出しは次の形です。

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-06-01

注意したいのは、この指定がリソース側の設定ではなくリクエスト単位の指定だという点です。同じリソース・同じデプロイに対して、あるコードは 2024-06-01 で、別のバッチは 2025-01-01-preview で叩くという状態が普通に成立します。障害調査のときに「アプリのバージョン」を見ても分からないのは、版がコード側の環境変数やハードコードに散らばっているからでした。

v1 APIではapi-versionが必須から任意の指定へ変わった

2025年8月から、Azure OpenAI は次世代の v1 API を選べるようになりました。従来は毎月のように新しい API バージョンが出て、新機能を取り込むたびにコードと環境変数を更新する必要がありましたが、v1 では日付付きの api-version を毎月指定し直す前提がなくなっています。

実装上の差は小さく、専用の AzureOpenAI クライアントではなく OpenAI 公式クライアントに基準URLを渡すだけになりました。

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

基準URLは openai.azure.com 形式と services.ai.azure.com 形式のどちらも受け付けます。SDKそのものの書き方やResponses APIとの関係はOpenAI Python SDKの使い方｜インストールから最新クライアント・Responses APIまでにまとめてあるので、クライアント側の実装はそちらを参照してください。

エンドポイントのパス形式そのものが体系を切り替える起点になる

ここが混乱の元になりやすいところです。v1 体系に乗るかどうかを決めているのは api-version の値ではなく、エンドポイントのパスに openai/v1 が入っているかどうかでした。旧体系は deployments 配下にデプロイ名を含むパスを持ち、api-version が必須。v1 体系は openai/v1 配下のフラットなパスで、api-version は任意です。

この二つを混ぜると、v1 のパスに日付付きの api-version を付けてしまい、サポート外だと返される状態になります。エラーメッセージが「APIバージョンが不正」と読めるため、より新しい日付を試すという逆方向の対処に走りがちですが、正解は日付の指定を外すことでした。

v1のGAとプレビューの違いをOpenAPI仕様のパス数で実測する

v1 に乗ると api-version を書かなくてよい、という説明は半分だけ正しい表現です。書かない場合に何が使えなくなるのかを、公開されている OpenAPI 仕様から実測しました。

GA版は71パス・プレビュー版は81パスで差分は十本だけだった

Azure の REST API 仕様リポジトリには、v1 の GA 仕様とプレビュー仕様が別ファイルで置かれています。2026年8月16日時点で両方を取得し、定義されているパスの集合を比較すると次の結果になりました。

GA にしかないパスは0本でした。つまりプレビューは GA の上位互換で、10本ぶんの機能が増えているという関係です。api-version を省いて GA 側に落ちても、既存の呼び出しが消えるわけではないと読み取れます。

音声と画像と動画の生成系はGA版のパス一覧に含まれていなかった

問題はその10本の中身です。内訳は音声3本、画像3本、動画4本でした。

音声合成・文字起こし・翻訳、画像の生成と編集、動画の生成と再編集。これらを組み込む実装では、api-version を省略した既定の v1 では届きません。preview を明示する必要があります。「v1にしたのでバージョン指定は不要」という理解のまま音声機能を足すと、この段差で詰まります。どのモデル系統がどの機能に対応しているかはAzure OpenAI Serviceのモデル一覧と選び方で用途別に整理しているので、機能とモデルの両面から確認しておくと手戻りが減るはずです。

プレビュー機能の入口は専用ヘッダーとalphaパスの二種類に移った

もう一つ、v1 体系ではプレビュー機能の入口が日付から別の仕組みへ移りました。機能ごとのプレビュー用ヘッダーを渡す方式と、パスに alpha を含めることでプレビュー状態を示す方式の二つです。前者の例が評価APIで、かつては専用ヘッダーが必要でしたが、現在は正式提供に切り替わっています。後者の例は微調整のグレーダー関連で、2026年8月16日時点の仕様では validate と run の2パスが alpha 配下に置かれていました。

この設計の意味は、機能ごとに個別で有効化できるという点にあります。旧体系ではプレビュー機能を一つ使うためにAPI全体をプレビュー版へ切り替える必要があり、意図しない他の変更まで一緒に取り込んでいました。

使えるapi-versionの値を一次情報から調べる三つの入り口

「今どの値が使えるのか」を調べる先は、実は公式ドキュメントの本文よりも仕様リポジトリのほうが確実です。三つの入り口を、確度の高い順に挙げます。

仕様リポジトリのディレクトリ名が使える版の一覧そのものになる

GitHub の Azure/azure-rest-api-specs には、推論APIの仕様が stable と preview に分かれて格納されています。ディレクトリ名がそのまま api-version の値なので、一覧を得るならここを見るのが最短でした。2026年8月16日時点の実測は次のとおりです。

日付付きの GA は 2022-12-01、2023-05-15、2024-02-01、2024-06-01、2024-10-21 の5本しかありません。プレビューは 2022-03-01-preview から 2025-04-01-preview まで22本あり、そこで打ち止めになっています。2025年4月より後に日付付きの版が増えていないという事実そのものが、体系の重心が v1 側へ移ったことを示す実測値です。

Learnのライフサイクル記事と廃止ページの統合状況を確かめる

二つ目は Microsoft Learn のライフサイクル記事です。日本語圏の解説記事では「廃止予定のAPIバージョン一覧は api-version-deprecation ページで確認できる」と案内されていることがありますが、2026年8月16日時点でそのURLを開くと v1 API のライフサイクル記事へ転送されました。廃止一覧を単独で参照する運用は、すでに前提が変わっています。転送先の記事は版間の変更履歴を持っているため、実務では一覧より変更履歴のほうを読むことになるでしょう。

v1のOpenAPI仕様書には既定値と列挙値まで書き込まれている

三つ目が、v1 の OpenAPI 仕様そのものです。この JSON を開くと、api-version パラメータの定義に「必須ではない」「既定は v1」「取りうる値は v1 と preview」と明示されています。ドキュメントの散文よりも機械可読な定義を見たほうが早い場面は多く、クライアント生成やAPI管理側の設定を書くときにも根拠となる定義です。なお 2025-04-01-preview の仕様は OpenAPI 3.1 で書かれており、Azure API Management が完全には対応していない既知の問題が案内されています。API管理層を挟む構成では、この一点が版選定を左右する制約です。

バージョン差で壊れるパラメータの見分け方と変更履歴の追いかけ方

版を上げたら動かなくなった、という事故の型はある程度決まっています。変更履歴を読むときの着眼点を整理します。

パラメータの削除と改名こそがバージョン差で壊れる主な原因になる

機能追加は既存コードを壊しません。壊すのは削除と改名です。公開されている変更履歴から、実装に効く破壊的な変更を抜き出すと次のようになります。

三つ目は追加なのに壊れるという点が厄介なところでした。max_tokens が推論モデル系で機能しなくなり、置き換え先として max_completion_tokens が入ったという経緯だからです。旧引数を送ってもエラーにならず、上限だけが効かないという静かな壊れ方をします。推論モデル側のパラメータ体系についてはAzure OpenAIでGPT-5を使う方法｜デプロイ・クォータ・推論パラメータの実装手順で実装手順に沿って扱っているので、移行時はそちらと突き合わせてください。

変更履歴は版と版の間の差分で並ぶため移行元の版から順に読んでいく

公開されている変更履歴は「2024-12-01-preview と 2024-10-01-preview の間の変更」という形で、隣り合う版の差分として並んでいます。したがって 2024-06-01 から 2025-04-01-preview へ一気に上げる場合、その間に挟まる版の差分をすべて重ねて読む必要がある構造でした。飛ばして読むと、途中の版で消えた引数を見落とします。

版を上げる作業は、モデルの世代交代とセットで発生することがほとんどです。提供終了に追われて版を上げる状況を避ける進め方はAzure OpenAIのモデル廃止に備える方法で手順化してあります。

応答オブジェクトの増加は壊れない前提に置いて読み取り側を組み立てる

リクエスト側とは逆に、応答側は「増える」方向の変更が予告なく入ります。公式には、新しい応答オブジェクトがいつ追加されてもおかしくないため、必要な項目だけを解析するよう案内されています。応答全体を厳密なスキーマで検証する実装は、版を固定していても将来壊れる余地を抱えることになるでしょう。読み取り側は寛容に、書き込み側は厳密に。この非対称が版差に強い実装の基本形です。

api-versionを固定するか追随するかを決める運用方針の立て方

ここからは判断の話です。固定と追随のどちらが正しいかという一般論はなく、案件の性格で答えが変わります。条件を切って言い切ります。

バージョン固定が向くのは検証済みの組み合わせを崩したくない場面

固定を選ぶべきなのは、出力の再現性が要件に入っている案件です。医療・金融の審査補助や、生成結果を証跡として保存する業務では、応答の揺れが仕様違反として扱われます。この場合は日付付きの版を明示し、モデルのバージョンも自動アップグレードを止めたうえで、版を上げる作業を計画的な保守項目として扱うのが筋でしょう。旧体系の日付付き GA である 2024-10-21 に留まる判断も、この文脈なら合理的です。

自動追随が向くのは新機能の取り込み速度を落としたくない開発現場

逆に追随が向くのは、社内向けの補助ツールや検証プロダクトのように、壊れたら直せる環境です。v1 体系に乗って api-version を書かなければ、GA に入った機能は自動的に届きます。プレビュー機能が要るなら preview を指定し、必要な機能だけヘッダーで開ける。毎月の版追随という作業自体が消えるので、保守の総量は確実に減ります。

環境変数に日付文字列を置く設計をやめて基準URL側へ寄せ替える

どちらを選ぶにせよ、設計として先に直したいのは版の置き場所です。AZURE_OPENAI_API_VERSION のような環境変数に日付を置く構成は、旧体系の名残でした。v1 体系では版の情報が基準URLのパスに含まれるため、環境変数は基準URLとキーの2つで足ります。設定項目が減れば、環境ごとに版がずれるという典型的な事故も起きません。

移行の順序は、読み取り専用の呼び出しから始めるのが安全です。まず1系統だけ v1 の基準URLへ切り替えて応答を比較し、次に書き込み系、最後に音声や画像のようなプレビュー限定の機能という順に進めます。プラットフォーム全体の構成が把握できていないと切り替えの影響範囲が読めないので、前提の整理にはAzure AI Foundryとは何か？概要と基本的なコンセプトを解説が入口になります。

v1へ寄せる条件と日付付きバージョンを残したままにする場面の判断

最後に、案件でどちらを採るかを条件付きで言い切ります。

v1へ寄せるべきなのは新規実装と将来の保守負担を軽くしたい案件

新規に書き起こすコードは、迷わず v1 体系にすべきです。理由は三つあります。第一に、日付付きの版が2025年4月で増えていない以上、新しい機能は v1 側にしか来ません。第二に、OpenAI 公式クライアントがそのまま使えるため、直APIとの間でコードを行き来させる際の書き換えが減ります。第三に、版を毎月追う保守作業そのものが消えます。音声や画像を扱うなら preview を明示するという一手間は残りますが、それでも日付を毎月更新する運用より軽い構成です。

日付付きを残す判断が通るのは再検証のコストが見合わない既存資産

すでに本番で安定して動いている旧体系のコードを、機能上の必要なしに v1 へ移す価値は薄いでしょう。移行には応答の差分検証が伴い、その工数はコード変更量とは比例しません。日付付きの版を残す判断が通るのは、次の条件に当てはまる場合です。追加したい機能が現行版で足りていること。API管理層の制約で新しい仕様形式を扱えないこと。そして、モデルの提供終了が当面先で、版を触る必然が発生していないこと。この三つが揃っているなら、移行は次の大きな改修に合わせるのが現実的です。

逆に、これらのどれか一つでも崩れた時点が移行の合図になります。とくにモデルの提供終了は待ってくれないため、廃止予定の確認と版の移行計画は同じ台帳で管理しておくべきでしょう。組織としてどこまで内製し、どこから外部に任せるかの線引きはAzure OpenAI Service導入支援の進め方｜五工程と外部委託の判断基準で発注視点から整理しています。版の移行を含めたAzure上の生成AI実装を設計から任せたい場合は、当社の生成AI開発・AI受託開発でご相談を受け付けています。

よくある質問

api-versionには結局どの値を指定すればよいですか？

新規実装なら指定しないのが既定の答えです。基準URLの末尾に openai/v1 を付ければ、api-version を省いても v1 として扱われます。音声・画像・動画の生成系を使う場合だけ preview を明示してください。既存の旧体系コードを動かし続けるなら、日付付きの GA である 2024-10-21 が2026年8月16日時点で最も新しい日付付き安定版です。

api-versionの一覧はどこで確認できますか？

GitHub の Azure/azure-rest-api-specs リポジトリで、推論APIの stable と preview の各ディレクトリ名を見るのが確実です。2026年8月16日時点で日付付きの安定版が5本、プレビューが22本あります。かつて案内されていた廃止情報ページは、同時点で v1 のライフサイクル記事へ転送される状態になっていました。

v1にしたら音声や画像の機能が呼べなくなったのはなぜですか？

v1 の GA 仕様に音声・画像・動画のパスが含まれていないためです。同時点の実測では GA が71パス、プレビューが81パスで、差の10パスがちょうどこれらの生成系にあたります。api-version に preview を指定すれば到達できます。

日付付きのapi-versionはいつまで使えますか？

終了日を名指しした案内は2026年8月16日時点で見当たりません。ただし日付付きの版は2025年4月を最後に追加されておらず、新機能は v1 側にのみ入っています。期限で判断するより、必要な機能が旧体系に来なくなった時点を移行の起点として計画するほうが現実的でしょう。

版を上げたらパラメータが不正になりました。どう切り分けますか？

まず移行元と移行先の間にあるすべての版の変更履歴を、順に重ねて読んでください。変更履歴は隣り合う版の差分として並んでいるため、飛ばすと途中で削除された引数を見落とします。次は、削除と改名の項目だけを抜き出して自分の送信内容と突き合わせる手順です。max_tokens のようにエラーを返さず挙動だけ変わる例もあるので、応答のトークン内訳まで確認すると原因に届きます。

関連記事

• Azure OpenAI Serviceとは？できること・料金・導入事例まで実務目線で解説：サービス全体の定義と料金体系から確認できます
• Azure OpenAIでGPT-5を使う方法｜デプロイ・クォータ・推論パラメータの実装手順：v1でのコード例と推論パラメータの体系を扱っています
• Azure OpenAIのモデル廃止に備える方法：版の移行時期を決める材料になる廃止情報の追い方です
• Azure OpenAI Serviceのモデル一覧と選び方：機能とモデル系統の対応を用途別に整理しています
• OpenAI Python SDKの使い方｜インストールから最新クライアント・Responses APIまで：クライアント側の書き方を補足します
• Azure OpenAI Service導入支援の進め方｜五工程と外部委託の判断基準：移行を含む意思決定の順序を発注視点で整理しています