Run Workers AI models without an API Key in Tanstack AI

.changeset/plenty-cooks-hide.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/tanstack-ai": patch
+---
+
+fix: add `run/` prefix to workers-ai gateway endpoint and make API key optional for gateway bindings

examples/tanstack-ai/worker/index.ts

@@ -155,13 +155,12 @@ function workersAiGatewayConfig(creds: RequestCredentials) {
 	if (creds.useBinding) {
 		return {
 			binding: env.AI.gateway(resolveGatewayId(creds)),
-			apiKey: env.CLOUDFLARE_API_TOKEN,
 		};
 	}
 	if (creds.cloudflare) {
-		return { ...gwRestConfig(creds), apiKey: creds.cloudflare.apiToken };
+		return gwRestConfig(creds);
 	}
-	return { binding: env.AI.gateway(resolveGatewayId(creds)), apiKey: env.CLOUDFLARE_API_TOKEN };
+	return { binding: env.AI.gateway(resolveGatewayId(creds)) };
 }
 
 // ---------------------------------------------------------------------------

packages/tanstack-ai/src/utils/create-fetcher.ts

@@ -233,7 +233,9 @@ export function createGatewayFetch(
 		};
 
 		if (provider === "workers-ai") {
-			request.endpoint = query.model as string;
+			if (!request.endpoint.startsWith("run/")) {
+				request.endpoint = `run/${query.model}`;
+			}
 			delete query.model;
 			delete query.instructions;
 		}

packages/tanstack-ai/test/gateway-fetch.test.ts

@@ -333,7 +333,7 @@ describe("createGatewayFetch", () => {
 
 			const request = mockBinding.run.mock.calls[0]![0];
 			expect(request.provider).toBe("workers-ai");
-			expect(request.endpoint).toBe("@cf/meta/llama-3.3-70b-instruct-fp8-fast");
+			expect(request.endpoint).toBe("run/@cf/meta/llama-3.3-70b-instruct-fp8-fast");
 			expect(request.query.model).toBeUndefined();
 			expect(request.query.messages).toEqual([{ role: "user", content: "Hello" }]);
 		});
@@ -358,6 +358,48 @@ describe("createGatewayFetch", () => {
 			expect(request.query.instructions).toBeUndefined();
 			expect(request.query.messages).toEqual([]);
 		});
+
+		it("should not double-prefix run/ when URL path already contains it", async () => {
+			const config: AiGatewayAdapterConfig = {
+				binding: mockBinding,
+				apiKey: "test-key",
+			};
+			const fetcher = createGatewayFetch("workers-ai", config);
+
+			await fetcher(
+				"https://gateway.ai.cloudflare.com/v1/run/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+				{
+					method: "POST",
+					body: JSON.stringify({
+						model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+						messages: [{ role: "user", content: "Hello" }],
+					}),
+				},
+			);
+
+			const request = mockBinding.run.mock.calls[0]![0];
+			expect(request.endpoint).toBe("run/@cf/meta/llama-3.3-70b-instruct-fp8-fast");
+			expect(request.query.model).toBeUndefined();
+		});
+
+		it("should prepend run/ when endpoint does not start with run/", async () => {
+			const config: AiGatewayAdapterConfig = {
+				binding: mockBinding,
+				apiKey: "test-key",
+			};
+			const fetcher = createGatewayFetch("workers-ai", config);
+
+			await fetcher("https://api.openai.com/v1/chat/completions", {
+				method: "POST",
+				body: JSON.stringify({
+					model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+					messages: [{ role: "user", content: "Hello" }],
+				}),
+			});
+
+			const request = mockBinding.run.mock.calls[0]![0];
+			expect(request.endpoint).toBe("run/@cf/meta/llama-3.3-70b-instruct-fp8-fast");
+		});
 	});
 
 	describe("endpoint extraction", () => {

packages/tanstack-ai/test/gateway-urls.test.ts

@@ -61,7 +61,7 @@ describe("Workers AI gateway URL verification", () => {
 		const body = JSON.parse((init as any).body as string);
 		expect(body.provider).toBe("workers-ai");
 		// createGatewayFetch moves model from query to endpoint for workers-ai
-		expect(body.endpoint).toBe("@cf/stabilityai/stable-diffusion-xl-base-1.0");
+		expect(body.endpoint).toBe("run/@cf/stabilityai/stable-diffusion-xl-base-1.0");
 		expect(body.query.prompt).toBe("test prompt");
 	});
 
@@ -89,7 +89,7 @@ describe("Workers AI gateway URL verification", () => {
 
 		const body = JSON.parse((init as any).body as string);
 		expect(body.provider).toBe("workers-ai");
-		expect(body.endpoint).toBe("@cf/openai/whisper");
+		expect(body.endpoint).toBe("run/@cf/openai/whisper");
 	});
 
 	it("TTS adapter sends model name in body and hits gateway URL", async () => {
@@ -107,7 +107,7 @@ describe("Workers AI gateway URL verification", () => {
 
 		const body = JSON.parse((init as any).body as string);
 		expect(body.provider).toBe("workers-ai");
-		expect(body.endpoint).toBe("@cf/deepgram/aura-1");
+		expect(body.endpoint).toBe("run/@cf/deepgram/aura-1");
 		expect(body.query.text).toBe("Hello world");
 	});
 
@@ -137,7 +137,7 @@ describe("Workers AI gateway URL verification", () => {
 
 		const body = JSON.parse((init as any).body as string);
 		expect(body.provider).toBe("workers-ai");
-		expect(body.endpoint).toBe("@cf/facebook/bart-large-cnn");
+		expect(body.endpoint).toBe("run/@cf/facebook/bart-large-cnn");
 		expect(body.query.input_text).toBe("A long article...");
 	});
 

packages/workers-ai-provider/test/utils.test.ts

@@ -454,7 +454,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway" } });
+		await run(
+			"@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway" } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			"https://gateway.ai.cloudflare.com/v1/test-account/my-gateway/workers-ai/run/@cf/meta/llama-3.1-8b-instruct",
@@ -494,7 +498,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("run/@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway" } });
+		await run(
+			"run/@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway" } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			"https://gateway.ai.cloudflare.com/v1/test-account/my-gateway/workers-ai/run/@cf/meta/llama-3.1-8b-instruct",
@@ -511,7 +519,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway", skipCache: true } });
+		await run(
+			"@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway", skipCache: true } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			expect.any(String),
@@ -532,7 +544,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway", cacheTtl: 3600 } });
+		await run(
+			"@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway", cacheTtl: 3600 } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			expect.any(String),
@@ -553,7 +569,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway", cacheKey: "my-custom-key" } });
+		await run(
+			"@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway", cacheKey: "my-custom-key" } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			expect.any(String),
@@ -574,7 +594,11 @@ describe("createRun", () => {
 		vi.mocked(globalThis.fetch).mockResolvedValue(mockResponse as unknown as Response);
 
 		const run = createRun({ accountId: "test-account", apiKey: "test-key" });
-		await run("@cf/meta/llama-3.1-8b-instruct" as any, { prompt: "Hi" }, { gateway: { id: "my-gateway", metadata: { user: "test", session: 123 } } });
+		await run(
+			"@cf/meta/llama-3.1-8b-instruct" as any,
+			{ prompt: "Hi" },
+			{ gateway: { id: "my-gateway", metadata: { user: "test", session: 123 } } },
+		);
 
 		expect(globalThis.fetch).toHaveBeenCalledWith(
 			expect.any(String),