スマートルーティング

リクエストで指定したモデルが利用できない場合、スマートルーティングはエラーを返す代わりに、近い代替モデルで応答します。リトライ用のコードを書かなくても、障害中にアプリを動かし続けられます。自動モードはチャットモデルと画像モデルに対応しています。音声モデルが切り替わるのは、代替モデルを自分で指定した場合だけです。動画モデルは切り替わりません。

仕組み

1. 各リクエストは、まず指定したモデルに送られます。多くの問題はここで解決します。モデルへの経路の1つが停滞したりエラーになったりした場合、利用者にエラーが表示される前に別の経路でリトライします。
2. スマートルーティングが動くのは、モデル自体が応答できない場合（すべての経路が失敗したか、利用可能な経路がない場合）だけです。
3. 代替モデルを順番に試します。それぞれで同じように自動復旧を行い、応答が得られるまで続けます。
4. レスポンスには、応答したモデルが示されます（本文のmodel、x-zurelay-modelとx-zurelay-routed-fromのヘッダー）。料金はそのモデルの価格で計算されます。

代替モデルを試す前に、指定したモデルへのすべての経路を試します。そのため、別のモデルに切り替わるのは、指定したモデルが応答できない場合だけです。すべてがすぐに失敗した場合は、エラーを返す前に指定したモデルと各代替モデルをもう一度ずつ試します。停止中と判明しているモデルはすぐにスキップします。

有効にする方法

キーには次のいずれかを設定できます:

リクエストごと

代替モデルのリスト

modelの隣にmodelsを渡します。代替モデルを最大3つ指定でき、modelが利用できない場合に順番に試します。キーの設定やヘッダーより優先されます。リストがモデルに送られることはありません。OpenAI Python SDKではextra_bodyを通じて送れます。画像・音声リクエストでも利用でき、フォームで送る画像編集ではmodelsフィールドとして指定できます（繰り返すか、カンマ区切りのリストを1つ指定します）。

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
      {
        "role": "user",
        "content": "Summarize this ticket in one line: ..."
      }
    ],
    extra_body={
      "models": [
        "gpt-6.1-sol",
        "gpt-6-astra"
      ]
    },
)
print(response.choices[0].message.content)

ヘッダー

x-zurelay-fallback: off    # never reroute this request
x-zurelay-fallback: auto   # use the automatic alternatives (chat and image models)

適用される優先順位は、リクエストのmodels、ヘッダー、キーの設定、ワークスペースのデフォルトです。

応答に使える代替モデル

• 同じ種類のモデルです。 チャットモデルの代替はチャットモデル、画像モデルの代替は画像モデル、音声モデルの代替は音声モデルです。その他のすべてのモデル（*）のルールには複数の種類を指定できますが、各リクエストでは同じ種類のモデルだけを使用します。
• 送信した内容を読み取れます。 PDFや動画を含むリクエストは、それらを読み取れる代替モデルにだけ送られます。該当するモデルがなければ、ファイルを無視した回答ではなくエラーを返します。
• キーで使用が許可されています。 キーで許可されていない代替モデルはスキップします。
• エンドポイントに対応しています。 /v1/messagesでは、代替モデルはClaudeモデルです。
• リクエスト自体に問題がありません。 モデルがリクエストを拒否した場合（無効なパラメータ、長すぎるプロンプト、描画できないプロンプト、読み上げられないテキストなど）は、代替モデルにも拒否されるため、ルーティングし直しません。

画像

自動モードでは、画像リクエストはまず同じファミリーのモデルに送られます（GPT Image 2.5 SunburstからFlare、Nano Banana ProからNano Banana 2.1）。代替には、同程度の品質で画像を生成できるモデルだけを使用します。自動で選ばれる代替モデルの料金は、指定したサイズで元のモデルの1.5倍を超えません。独自のルールとリクエストのmodelsリストには、この制限はありません。どちらの場合も、次の条件を満たします:

• 同じサイズと縦横比です。 Nano Bananaモデルはsizeとaspect_ratioを同じように解釈します。GPT ImageがNano Bananaのサイズの代替になるのは、両方が同じ画像を生成できる場合だけです: 1Kの正方形（1024x1024）、1Kの3:2または2:3、2Kの正方形、4Kの16:9または9:16。Nano BananaがGPT Imageのピクセルサイズの代替になるのは、まったく同じピクセル数の画像を生成できる場合（1024x1024、2048x2048）、またはサイズを指定しなかった場合だけです。
• 参照画像に対応しています。 代替モデルは、送信した枚数の参照画像を受け取れる必要があります（Nano Bananaは14枚、GPT Imageは16枚）。
• 指定したオプションに対応しています。 透過のbackgroundを指定したリクエストは、GPT Imageモデルにだけ送られます。
• 回答ごとに1つのモデルを使用します。 nが1を超える場合も、すべての画像は同じモデルで生成されます。

音声

音声のモデルが切り替わるのは、独自のルールまたはリクエストのmodelsリストによる場合だけです。自動モードでは切り替わりません。すべての音声モデルで同じ声を使用できるため、代替モデルも指定されたvoiceとinstructionsでテキストを読み上げます。入力・出力トークンのヘッダーには、応答したモデルの情報が入ります。

自動で選ばれる代替モデル

カタログの最新情報に基づき、自動モードで各チャット・画像モデルの代わりに使われるモデルを示します。

知っておきたいこと

• 代替モデルの料金は、指定したモデルより高い場合も安い場合もあります。リクエストログには、応答したモデルとその料金が表示されます。
• ストリーミングでも同じです。モデルが応答を開始するまで何も送信されず、各チャンクにはそのモデル名が示されます。
• 画像と音声のレスポンスにも同じx-zurelay-modelとx-zurelay-routed-fromヘッダーが含まれます。ライブラリ内の画像には、生成したモデル名が表示されます。
• 動画は別のモデルに転送されません。動画ジョブは指定したモデルで、完成または失敗するまで再送信されます（無料）。