Choose and run a Workers AI model

Workers AI runs models on Cloudflare’s network. You don’t manage GPUs or pick a region. You add a binding to your Worker and call it like any other function.

The binding is one line in wrangler.jsonc:

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

That gives you env.AI inside the Worker, and env.AI.run(model, input) is the whole API. The first argument is a model ID from the catalog. The second is the input that model expects. A text model wants messages or a prompt. An embedding model wants text. An image model wants a prompt and returns bytes.

Pick the model from the catalog, not from memory

Browse what’s available right now:

npx wrangler ai models

Pick by task first: text generation, embeddings, classification, speech to text, image. Then narrow by language support, context length, output format, latency, and cost. A small instruct model answers a classification question in a fraction of the time and price of a large one, and for that task it’s often just as good.

Model IDs change. Workers AI adds models and retires old ones, so a name you copy from a blog post, or from this lesson, may be gone by the time you run it. Keep the model ID in configuration, not scattered through the code, and test the model you deployed, not the one you read about.

Validate the input

Never pass user text straight into a model call. Cap its length before you send it. A 100 KB paste is a cost problem and sometimes a context-length error. And don’t send secrets by default: strip tokens, emails, and internal IDs out of the input unless the task needs them.

The response is a plain object. For a text model, the answer is in result.response. Log it while you learn the shape, along with the model ID, the input, and how long the call took.

Run one short classification on a sentence you wrote yourself, and record five things: model ID, input, output, duration, and the usage units the dashboard shows for it. That’s your baseline for the next lessons.

Start with one bounded input and inspect the response shape:

const result = await env.AI.run('@cf/meta/llama-3.2-3b-instruct', {
  messages: [{ role: 'user', content: 'Summarize this alert in one sentence.' }]
})

Pin the model name in configuration, bound input length, and handle provider errors. Save a few representative inputs and expected qualities before changing models. A response returning 200 does not prove the answer is useful or safe.