Cloudflare Workers AI - Complete Reference

Production-ready knowledge domain for building AI-powered applications with Cloudflare Workers AI.

Status: Production Ready ✅ Last Updated: 2025-11-21 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: wrangler@4.43.0, @cloudflare/workers-types@4.20251014.0

Table of Contents

1. Quick Start (5 minutes)
2. Workers AI API Reference
3. Model Selection Guide
4. Common Patterns
5. AI Gateway Integration
6. Rate Limits & Pricing
7. Production Checklist

Quick Start (5 minutes)

1. Add AI Binding

wrangler.jsonc:

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

2. Run Your First Model

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'What is Cloudflare?',
    });

    return Response.json(response);
  },
};

3. Add Streaming (Recommended)

const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true, // Always use streaming for text generation!
});

return new Response(stream, {
  headers: { 'content-type': 'text/event-stream' },
});

Why streaming?

• Prevents buffering large responses in memory
• Faster time-to-first-token
• Better user experience for long-form content
• Avoids Worker timeout issues

Workers AI API Reference

Core API:

env.AI.run()

const response = await env.AI.run(model, inputs, options?);

model

@cf/meta/llama-3.1-8b-instruct

inputs

options.gateway.id

options.gateway.skipCache

Returns:

Promise<ModelOutput>

ReadableStream

Input Types by Model Category

messages[]

stream

max_tokens

temperature

{ response: string }

text: string | string[]

{ data: number[][], shape: number[] }

prompt

num_steps

guidance

messages[].content[].image_url

{ response: string }

📄 Full model details: Load

references/models-catalog.md

Model Selection Guide

Text Generation (LLMs)

@cf/meta/llama-3.1-8b-instruct

@cf/meta/llama-3.2-1b-instruct

@cf/qwen/qwen1.5-14b-chat-awq

@cf/deepseek-ai/deepseek-r1-distill-qwen-32b

@hf/thebloke/mistral-7b-instruct-v0.1-awq

Text Embeddings

@cf/baai/bge-base-en-v1.5

@cf/baai/bge-large-en-v1.5

@cf/baai/bge-small-en-v1.5

Image Generation

@cf/black-forest-labs/flux-1-schnell

@cf/stabilityai/stable-diffusion-xl-base-1.0

@cf/lykon/dreamshaper-8-lcm

Vision Models

@cf/meta/llama-3.2-11b-vision-instruct

@cf/unum/uform-gen2-qwen-500m

Common Patterns

Pattern 1: Chat with Streaming

app.post('/chat', async (c) => {
  const { messages } = await c.req.json<{ messages: Array<{ role: string; content: string }> }>();
  const stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, stream: true });
  return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
});

Pattern 2: RAG (Retrieval Augmented Generation)

// 1. Generate embedding for query
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [userQuery] });
// 2. Search Vectorize
const matches = await env.VECTORIZE.query(embeddings.data[0], { topK: 3 });
// 3. Build context
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');
// 4. Generate with context
const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
  messages: [
    { role: 'system', content: `Answer using this context:\n${context}` },
    { role: 'user', content: userQuery },
  ],
  stream: true,
});
return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });

📄 More patterns: Load

references/best-practices.md

AI Gateway Integration

Enable caching, logging, and cost tracking with AI Gateway:

const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' }, {
  gateway: { id: 'my-gateway', skipCache: false },
});

Benefits: Cost tracking, response caching (50-90% savings on repeated queries), request logging, rate limiting, analytics.

Rate Limits & Pricing

Information last verified: 2025-01-14

Rate limits and pricing vary significantly by model. Always check the official documentation for the most current information:

• Rate Limits: https://developers.cloudflare.com/workers-ai/platform/limits/
• Pricing: https://developers.cloudflare.com/workers-ai/platform/pricing/

Free Tier: 10,000 neurons/day Paid Tier: $0.011 per 1,000 neurons

📄 Per-model details: See

references/models-catalog.md

Production Checklist

Essential before deploying:

• Enable AI Gateway for cost tracking
• Implement streaming for text generation
• Add rate limit retry with exponential backoff
• Validate input length (prevent token limit errors)
• Add input sanitization (prevent prompt injection)

📄 Full checklist: Load

references/best-practices.md

External SDK Integrations

Workers AI supports OpenAI SDK compatibility and Vercel AI SDK:

// OpenAI SDK - use same patterns with Workers AI models
const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
});

// Vercel AI SDK - native integration
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });

📄 Full integration guide: Load

references/integrations.md

Limits Summary

When to Load References

references/models-catalog.md

references/best-practices.md

references/integrations.md

References

• Workers AI Docs
• Models Catalog
• AI Gateway
• Pricing