通用端点（已弃用）

通用端点允许你通过单个端点联系每个提供商。

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 — 请求回退到第二个模型。
cf-aig-step:2 — 请求回退到第三个模型。
后续步骤 — 每次回退都会使步骤编号加 1。

请求超时

如果提供商响应时间过长，请求超时会触发回退。

通过在提供商特定的 config 对象中设置 requestTimeout 属性（以毫秒为单位）来配置超时。每个提供商可以有不同的 requestTimeout 值。

超时基于响应的第一部分返回的时间。只要响应的第一部分在指定时间范围内返回 — 例如在流式传输响应时 — 你的 gateway 就会等待响应。

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
        },
    }
]'

请求重试

通用端点支持对失败请求自动重试，最多五次重试尝试。重试会在触发任何已配置的回退之前进行。

使用提供商特定 config 中的以下属性配置重试设置：

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

maxAttempts：最大重试次数（最多 5 次）。
retryDelay：重试前的延迟，以毫秒为单位（最多 5 秒）。
backoff：退避方法 — constant、linear 或 exponential。

在最终重试尝试时，无论请求耗时多久，你的 gateway 都会等待请求完成。每个提供商可以有不同的重试设置。

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

通用端点也可以通过 WebSockets API 访问，它提供单个持久连接，支持持续通信。此 API 支持连接到 AI Gateway 的所有 AI 提供商，包括本身不支持 WebSockets 的提供商。

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",
			},
		});
	},
};

标头配置层级

通用端点允许你设置回退模型或提供商，并为每个提供商或请求自定义标头。你可以在三个层级配置标头：

提供商层级：特定于某个提供商的标头。
请求层级：包含在单个请求中的标头。
Gateway 设置：在 gateway 仪表板中配置的默认标头。

由于相同的设置可以在多个位置配置，AI Gateway 会应用层级来确定哪个配置优先：

提供商层级标头覆盖所有其他配置。
如果未设置提供商层级标头，则使用请求层级标头。
仅当提供商或请求层级未配置标头时，才使用 gateway 层级设置。

此层级确保行为一致，优先采用最具体的配置。使用提供商层级和请求层级标头进行精细控制，使用 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?"
          }
        ]
      }
    }
  ]'