The Cloudflare adapter provides access to Cloudflare Workers AI models and AI Gateway for routing requests to OpenAI, Anthropic, Gemini, Grok, and OpenRouter with caching, rate limiting, and unified billing.
Installation#
npm install @cloudflare/tanstack-ai @tanstack/ai
For AI Gateway with third-party providers, install the provider SDKs you need:
npm install @tanstack/ai-openai # For OpenAI via Gateway
npm install @tanstack/ai-anthropic # For Anthropic via Gateway
npm install @tanstack/ai-gemini # For Gemini via Gateway
npm install @tanstack/ai-grok # For Grok via Gateway
npm install @tanstack/ai-openrouter # For OpenRouter via Gateway
Basic Usage#
import { chat, toHttpResponse } from "@tanstack/ai";
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiChat(
"@cf/meta/llama-4-scout-17b-16e-instruct",
{ binding: env.AI },
);
const response = chat({
adapter,
stream: true,
messages: [{ role: "user", content: "Hello!" }],
});
return toHttpResponse(response);
Workers AI#
The simplest way to use AI in a Cloudflare Worker. No API keys needed when using the env.AI binding.
Chat#
import { chat, toHttpResponse } from "@tanstack/ai";
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiChat(
"@cf/meta/llama-4-scout-17b-16e-instruct",
{ binding: env.AI },
);
const response = chat({
adapter,
stream: true,
messages: [{ role: "user", content: "Hello!" }],
});
return toHttpResponse(response);
Chat with REST Credentials#
If you're not running inside a Worker, use account ID and API key instead:
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiChat(
"@cf/meta/llama-4-scout-17b-16e-instruct",
{
accountId: "your-account-id",
apiKey: "your-api-key",
},
);
Image Generation#
import { generateImage } from "@tanstack/ai";
import { createWorkersAiImage } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiImage(
"@cf/stabilityai/stable-diffusion-xl-base-1.0",
{ binding: env.AI },
);
const result = await generateImage({
adapter,
prompt: "a cat in space",
});
console.log(result.images[0].b64Json);
Transcription (Speech-to-Text)#
Supports Whisper and Deepgram models:
import { generateTranscription } from "@tanstack/ai";
import { createWorkersAiTranscription } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiTranscription(
"@cf/openai/whisper-large-v3-turbo",
{ binding: env.AI },
);
const result = await generateTranscription({
adapter,
audio: audioArrayBuffer,
});
console.log(result.text);
console.log(result.segments);
Supported transcription models: @cf/openai/whisper, @cf/openai/whisper-tiny-en, @cf/openai/whisper-large-v3-turbo, @cf/deepgram/nova-3
Text-to-Speech#
import { generateSpeech } from "@tanstack/ai";
import { createWorkersAiTts } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiTts("@cf/deepgram/aura-2-en", {
binding: env.AI,
});
const result = await generateSpeech({
adapter,
text: "Hello world",
});
console.log(result.audio);
Summarization#
import { summarize } from "@tanstack/ai";
import { createWorkersAiSummarize } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiSummarize("@cf/facebook/bart-large-cnn", {
binding: env.AI,
});
const result = await summarize({
adapter,
text: "Long article here...",
});
console.log(result.summary);
AI Gateway#
Route AI requests through Cloudflare's AI Gateway for caching, rate limiting, and unified billing. Supports both Workers AI and third-party providers.
Workers AI through Gateway#
import { createWorkersAiChat } from "@cloudflare/tanstack-ai";
const adapter = createWorkersAiChat(
"@cf/meta/llama-4-scout-17b-16e-instruct",
{
binding: env.AI.gateway("my-gateway-id"),
apiKey: env.WORKERS_AI_TOKEN,
},
);
Third-Party Providers through Gateway#
Use the binding approach (recommended for Cloudflare Workers):
import {
createOpenAiChat,
createAnthropicChat,
createGeminiChat,
createGrokChat,
createOpenRouterChat,
} from "@cloudflare/tanstack-ai";
const openai = createOpenAiChat("gpt-4o", {
binding: env.AI.gateway("my-gateway-id"),
});
const anthropic = createAnthropicChat("claude-sonnet-4-5", {
binding: env.AI.gateway("my-gateway-id"),
});
const grok = createGrokChat("grok-4", {
binding: env.AI.gateway("my-gateway-id"),
});
const openrouter = createOpenRouterChat("openai/gpt-4o", {
binding: env.AI.gateway("my-gateway-id"),
});
Or use credentials for non-Worker environments:
import { createOpenAiChat } from "@cloudflare/tanstack-ai";
const adapter = createOpenAiChat("gpt-4o", {
accountId: "your-account-id",
gatewayId: "your-gateway-id",
cfApiKey: "your-cf-api-key",
apiKey: "provider-api-key",
});
Cache Options#
Both binding and credentials modes support cache configuration:
const adapter = createOpenAiChat("gpt-4o", {
binding: env.AI.gateway("my-gateway-id"),
skipCache: false,
cacheTtl: 3600,
customCacheKey: "my-key",
metadata: { user: "test" },
});
Configuration Modes#
Workers AI supports four configuration modes:
| Mode | Config | Description |
|---|---|---|
| Plain binding | { binding: env.AI } | Direct access, no gateway |
| Plain REST | { accountId, apiKey } | REST API, no gateway |
| Gateway binding | { binding: env.AI.gateway(id) } | Through AI Gateway via binding |
| Gateway REST | { accountId, gatewayId, ... } | Through AI Gateway via REST |
Third-party providers (OpenAI, Anthropic, Gemini, Grok, OpenRouter) only support the gateway modes.
Supported Capabilities#
| Provider | Chat | Summarize | Image Gen | Transcription | TTS |
|---|---|---|---|---|---|
| Workers AI | ✅ | ✅ | ✅ | ✅ | ✅ |
| OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ |
| Anthropic | ✅ | ✅ | ❌ | ❌ | ❌ |
| Gemini | ✅ | ✅ | ✅ | ❌ | ✅ |
| Grok | ✅ | ✅ | ✅ | ❌ | ❌ |
| OpenRouter | ✅ | ✅ | ✅ | ❌ | ❌ |
Environment Variables#
For the REST credential path (outside of Cloudflare Workers):
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_KEY=your-api-key
When using the env.AI binding inside a Worker, no environment variables are needed.
API Reference#
Workers AI#
createWorkersAiChat(model, config)— Chat and structured outputcreateWorkersAiImage(model, config)— Image generationcreateWorkersAiTranscription(model, config)— Speech-to-text (Whisper, Deepgram)createWorkersAiTts(model, config)— Text-to-speech (Deepgram Aura)createWorkersAiSummarize(model, config)— Summarization (BART-large-CNN)
Gateway Providers#
createOpenAiChat(model, config)/createOpenAiSummarize/createOpenAiImage/createOpenAiTranscription/createOpenAiTtscreateAnthropicChat(model, config)/createAnthropicSummarizecreateGeminiChat(model, config)/createGeminiSummarize/createGeminiImage/createGeminiTtscreateGrokChat(model, config)/createGrokSummarize/createGrokImagecreateOpenRouterChat(model, config)/createOpenRouterSummarize/createOpenRouterImage
Next Steps#
- Cloudflare Workers AI — Workers AI documentation
- Cloudflare AI Gateway — AI Gateway documentation
- GitHub Repository — Source code and issues
- Streaming Guide — Learn about streaming responses
- Tools Guide — Learn about tool calling