Universal Endpoint（非推奨）

Universal Endpoint を使うと、単一のエンドポイント経由ですべてのプロバイダーに連絡できます。

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}

ペイロードはメッセージの配列を期待します。各メッセージは次のパラメーターを持つオブジェクトです。

provider: このメッセージを向けるプロバイダー名です。OpenAI、workers-ai、または対応する任意のプロバイダーです。
endpoint: 到達しようとしているプロバイダー API のパス名です。たとえば OpenAI では chat/completions、Workers AI では @cf/meta/llama-3.1-8b-instruct です。各プロバイダー固有のセクションを参照してください。
authorization: このプロバイダーに連絡するときに使う Authorization HTTP ヘッダーの内容です。通常は Token または Bearer で始まります。
query: プロバイダーの公式 API が期待するペイロードです。

cURL の例

リクエストbash

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "provider": "workers-ai",
    "endpoint": "@cf/meta/llama-3.1-8b-instruct",
    "headers": {
      "Authorization": "Bearer {cloudflare_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "messages": [
        {
          "role": "system",
          "content": "You are a friendly assistant"
        },
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  },
  {
    "provider": "openai",
    "endpoint": "chat/completions",
    "headers": {
      "Authorization": "Bearer {open_ai_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "model": "gpt-4o-mini",
      "stream": true,
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }
]'

上記は Workers AI Inference API へリクエストを送ります。失敗した場合は OpenAI に進みます。配列に別のオブジェクトを追加して、必要な数のフォールバックを追加できます。

フォールバック

リクエスト失敗を処理し、信頼性を確保するために、モデルまたはプロバイダーのフォールバックを指定できます。ペイロード配列がフォールバックの順序を定義します。最初のプロバイダーが失敗すると、リクエストは配列の次のエントリへ落ちます。詳細はフォールバックを参照してください。

デフォルトでは、モデルリクエストがエラーを返すと Cloudflare がフォールバックを起動します。リクエストタイムアウトを設定して、プロバイダーの応答が遅すぎるときにフォールバックを起動することもできます。

レスポンスヘッダー（`cf-aig-step`）

フォールバックを使うとき、レスポンスヘッダー cf-aig-step は、リクエストを正常に処理したモデルをステップ番号で示します。

cf-aig-step:0 — 最初の（プライマリ）モデルが正常に使われました。
cf-aig-step:1 — リクエストが 2 番目のモデルへフォールバックしました。
cf-aig-step:2 — リクエストが 3 番目のモデルへフォールバックしました。
以降のステップ — フォールバックごとにステップ番号が 1 増えます。

リクエストタイムアウト

リクエストタイムアウトは、プロバイダーの応答が遅すぎるときにフォールバックを起動します。

プロバイダー固有の config オブジェクト内に requestTimeout プロパティ（ミリ秒）を設定してタイムアウトを構成します。プロバイダーごとに異なる requestTimeout 値を持てます。

タイムアウトは、レスポンスの最初の部分が返ってきた時点に基づきます。ストリーミング応答のように、指定時間内にレスポンスの最初の部分が返れば、ゲートウェイはレスポンスを待ちます。

Request timeout examplebash

curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type: application/json"
        },
        "config": {
            "requestTimeout": 1000
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type: application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "requestTimeout": 3000
        },
    }
]'

リクエストリトライ

Universal Endpoint は失敗したリクエストの自動リトライに対応し、最大 5 回まで再試行します。リトライは、設定したフォールバックを起動する前に試行されます。

プロバイダー固有の config で、次のプロパティを使ってリトライ設定を構成します。

config:{
	maxAttempts?: number;
	retryDelay?: number;
	backoff?: "constant" | "linear" | "exponential";
}

maxAttempts: 最大リトライ回数（最大 5）。
retryDelay: リトライ前の遅延（ミリ秒、最大 60 秒）。
backoff: バックオフ方法 — constant、linear、または exponential。

最後のリトライ試行では、かかる時間に関係なく、ゲートウェイはリクエスト完了まで待ちます。プロバイダーごとに異なるリトライ設定を持てます。

Request retry examplebash

curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type: application/json"
        },
        "config": {
            "maxAttempts": 2,
						"retryDelay": 1000,
						"backoff": "constant"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type: application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "maxAttempts": 4,
						"retryDelay": 1000,
						"backoff": "exponential"
        },
    }
]'

WebSockets API beta

Universal Endpoint は WebSockets API 経由でもアクセスできます。単一の永続接続により、継続的な通信ができます。この API は、ネイティブに WebSockets に対応していないものも含め、AI Gateway に接続されたすべての AI プロバイダーに対応します。

WebSockets の例

import WebSocket from "ws";
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/",
	{
		headers: {
			"cf-aig-authorization": "Bearer AI_GATEWAY_TOKEN",
		},
	},
);

ws.send(
	JSON.stringify({
		type: "universal.create",
		request: {
			eventId: "my-request",
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				Authorization: "Bearer WORKERS_AI_TOKEN",
				"Content-Type": "application/json",
			},
			query: {
				prompt: "tell me a joke",
			},
		},
	}),
);

ws.on("message", function incoming(message) {
	console.log(message.toString());
});

Workers バインディングの例

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

src/index.tstypescript

type Env = {
	AI: Ai;
};

export default {
	async fetch(request: Request, env: Env) {
		return env.AI.gateway("my-gateway").run({
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				authorization: "Bearer my-api-token",
			},
			query: {
				prompt: "tell me a joke",
			},
		});
	},
};

ヘッダー構成の階層

Universal Endpoint では、フォールバックのモデルまたはプロバイダーを設定し、プロバイダーまたはリクエストごとにヘッダーをカスタマイズできます。ヘッダーは 3 つのレベルで構成できます。

プロバイダーレベル: 特定のプロバイダー固有のヘッダー。
リクエストレベル: 個別リクエストに含めるヘッダー。
ゲートウェイ設定: ゲートウェイダッシュボードで構成するデフォルトヘッダー。

同じ設定を複数の場所で構成できるため、AI Gateway はどの構成が優先されるかを決める階層を適用します。

プロバイダーレベルのヘッダー は、他のすべての構成より優先されます。
リクエストレベルのヘッダー は、プロバイダーレベルのヘッダーが設定されていない場合に使われます。
ゲートウェイレベルの設定 は、プロバイダーまたはリクエストレベルでヘッダーが構成されていない場合にのみ使われます。

この階層により、一貫した動きが保証され、最も具体的な構成が優先されます。細かい制御にはプロバイダーレベルとリクエストレベルのヘッダーを使い、一般的なデフォルトにはゲートウェイ設定を使います。

階層の例

この例は、異なるレベルで設定したヘッダーがキャッシュ動作にどう影響するかを示します。

リクエストレベルのヘッダー: cf-aig-cache-ttl は 3600 秒に設定され、デフォルトでこのキャッシュ期間をリクエストに適用します。
プロバイダーレベルのヘッダー: フォールバックプロバイダー（OpenAI）では、cf-aig-cache-ttl が明示的に 0 秒に設定され、リクエストレベルのヘッダーを上書きして、OpenAI がプロバイダーとして使われるときの応答のキャッシュを無効にします。

これは、プロバイダーレベルのヘッダーがリクエストレベルのヘッダーより優先され、キャッシュ動作を細かく制御できることを示します。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-ttl: 3600' \
  --data '[
    {
      "provider": "workers-ai",
      "endpoint": "@cf/meta/llama-3.1-8b-instruct",
      "headers": {
        "Authorization": "Bearer {cloudflare_token}",
        "Content-Type": "application/json"
      },
      "query": {
        "messages": [
          {
            "role": "system",
            "content": "You are a friendly assistant"
          },
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    },
    {
      "provider": "openai",
      "endpoint": "chat/completions",
      "headers": {
        "Authorization": "Bearer {open_ai_token}",
        "Content-Type": "application/json",
        "cf-aig-cache-ttl": "0"
      },
      "query": {
        "model": "gpt-4o-mini",
        "stream": true,
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    }
  ]'