1# Workers AI API Reference
2 
3## Core Method
4 
5```typescript
6const response = await env.AI.run(model, input);
7```
8 
9## Text Generation
10 
11```typescript
12const result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
13  messages: [
14    { role: 'system', content: 'You are helpful' },
15    { role: 'user', content: 'Hello' }
16  ],
17  temperature: 0.7,  // 0-1
18  max_tokens: 100
19});
20console.log(result.response);
21```
22 
23**Streaming:**
24```typescript
25const stream = await env.AI.run(model, { messages, stream: true });
26return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
27```
28 
29## Embeddings
30 
31```typescript
32const result = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
33  text: ['Query', 'Doc 1', 'Doc 2'] // Batch for efficiency
34});
35const [queryEmbed, doc1Embed, doc2Embed] = result.data; // 768-dim vectors
36```
37 
38## Function Calling
39 
40```typescript
41const tools = [{
42  type: 'function',
43  function: {
44    name: 'getWeather',
45    description: 'Get weather for location',
46    parameters: {
47      type: 'object',
48      properties: { location: { type: 'string' } },
49      required: ['location']
50    }
51  }
52}];
53 
54const response = await env.AI.run(model, { messages, tools });
55if (response.tool_calls) {
56  const args = JSON.parse(response.tool_calls[0].function.arguments);
57  // Execute function, send result back
58}
59```
60 
61## Image Generation
62 
63```typescript
64const image = await env.AI.run('@cf/stabilityai/stable-diffusion-xl-base-1.0', {
65  prompt: 'Mountain sunset',
66  num_steps: 20,   // 1-20
67  guidance: 7.5    // 1-20
68});
69return new Response(image, { headers: { 'Content-Type': 'image/png' } });
70```
71 
72## Speech Recognition
73 
74```typescript
75const audioArray = Array.from(new Uint8Array(await request.arrayBuffer()));
76const result = await env.AI.run('@cf/openai/whisper', { audio: audioArray });
77console.log(result.text);
78```
79 
80## Translation
81 
82```typescript
83const result = await env.AI.run('@cf/meta/m2m100-1.2b', {
84  text: 'Hello',
85  source_lang: 'en',
86  target_lang: 'es'
87});
88console.log(result.translated_text);
89```
90 
91## REST API
92 
93```bash
94curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/meta/llama-3.1-8b-instruct \
95  -H "Authorization: Bearer $TOKEN" \
96  -d '{"messages":[{"role":"user","content":"Hello"}]}'
97```
98 
99## Error Codes
100 
101| Code | Meaning | Fix |
102|------|---------|-----|
103| 7502 | Model not found | Check spelling |
104| 7504 | Validation failed | Verify input schema |
105| 7505 | Rate limited | Reduce rate or upgrade |
106| 7506 | Context exceeded | Reduce input size |
107 
108## Performance Tips
109 
1101. **Batch embeddings** - single request for multiple texts
1112. **Stream long responses** - reduce perceived latency
1123. **Accept cold starts** - first request ~1-3s, subsequent ~100-500ms
113