npm-anthropic-ai--sdk

1
# Beta Features
2

3
The Beta API provides access to experimental features, new capabilities, and preview functionality that may not be available in the main API. Beta features may change or be removed in future versions.
4

5
## Capabilities
6

7
### Beta API Access
8

9
Access beta features through the dedicated beta resource with feature-specific headers.
10

11
```typescript { .api }
12
/**
13
 * Beta features API providing access to experimental functionality
14
 */
15
class Beta extends APIResource {
16
  /** File management operations */
17
  files: Files;
18
  /** Beta model information */
19
  models: Models;  
20
  /** Beta message features */
21
  messages: Messages;
22
}
23

24
type AnthropicBeta = 
25
  | "computer-use-2024-10-22"
26
  | "pdfs-2024-09-25" 
27
  | "token-counting-2024-11-01"
28
  | "message-batches-2024-09-24"
29
  | string[];
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import Anthropic from "@anthropic-ai/sdk";
36

37
const client = new Anthropic();
38

39
// Access beta files
40
const files = await client.beta.files.list();
41

42
// Access beta models
43
const betaModels = await client.beta.models.list({
44
  betas: ["computer-use-2024-10-22"],
45
});
46

47
// Use beta message features
48
const message = await client.beta.messages.create({
49
  model: "claude-3-5-sonnet-20241022",
50
  max_tokens: 1024,
51
  messages: [{ role: "user", content: "Hello with beta features!" }],
52
  betas: ["pdfs-2024-09-25"],
53
});
54
```
55

56
### File Management
57

58
Upload, manage, and reference files in conversations through the beta files API.
59

60
```typescript { .api }
61
/**
62
 * File management for beta features
63
 */
64
class Files extends APIResource {
65
  upload(params: FileUploadParams): APIPromise<FileMetadata>;
66
  list(params?: FileListParams): PagePromise<FileMetadataPage, FileMetadata>;
67
  retrieveMetadata(fileId: string, params?: FileRetrieveMetadataParams): APIPromise<FileMetadata>;
68
  download(fileId: string, params?: FileDownloadParams): APIPromise<Response>;
69
  delete(fileId: string, params?: FileDeleteParams): APIPromise<DeletedFile>;
70
}
71

72
interface FileUploadParams {
73
  /** File content to upload */
74
  file: File | Blob;
75
  /** Purpose of the file upload */
76
  purpose: "vision";
77
  /** Beta features to enable */
78
  betas?: AnthropicBeta;
79
}
80

81
interface FileMetadata {
82
  /** Unique file identifier */
83
  id: string;
84
  /** Original filename */
85
  filename: string;
86
  /** File size in bytes */
87
  size: number;
88
  /** MIME type of the file */
89
  type: string;
90
  /** Upload timestamp */
91
  created_at: string;
92
  /** File purpose */
93
  purpose: "vision";
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
// Upload a file
101
const fileUpload = await client.beta.files.upload({
102
  file: new File([imageData], "image.jpg", { type: "image/jpeg" }),
103
  purpose: "vision",
104
  betas: ["pdfs-2024-09-25"],
105
});
106

107
console.log(`Uploaded file: ${fileUpload.id}`);
108

109
// List uploaded files
110
const files = await client.beta.files.list();
111
for (const file of files.data) {
112
  console.log(`${file.filename}: ${file.size} bytes`);
113
}
114

115
// Use file in message
116
const message = await client.beta.messages.create({
117
  model: "claude-3-5-sonnet-20241022",
118
  max_tokens: 1024,
119
  messages: [
120
    {
121
      role: "user", 
122
      content: [
123
        { type: "text", text: "What's in this image?" },
124
        { type: "image", source: { type: "file", file_id: fileUpload.id } }
125
      ]
126
    }
127
  ],
128
  betas: ["pdfs-2024-09-25"],
129
});
130

131
// Download a file
132
const downloadResponse = await client.beta.files.download(fileUpload.id);
133
const fileContent = await downloadResponse.arrayBuffer();
134

135
// Delete a file
136
await client.beta.files.delete(fileUpload.id);
137
```
138

139
### Computer Use
140

141
Interact with computer interfaces through Claude's computer use capabilities.
142

143
```typescript { .api }
144
/**
145
 * Computer use tool for screen interaction
146
 */
147
interface BetaComputerUseTool20241022 {
148
  type: "computer_20241022";
149
  name: "computer";
150
  /** Screen dimensions */
151
  display_width_px: number;
152
  display_height_px: number;
153
  /** Screen scaling factor */
154
  display_number?: number;
155
}
156

157
interface BetaComputerUseAction {
158
  /** Action type */
159
  action: "screenshot" | "click" | "type" | "key" | "scroll";
160
  /** Click coordinates (for click action) */
161
  coordinate?: [number, number];
162
  /** Text to type (for type action) */
163
  text?: string;
164
  /** Key to press (for key action) */
165
  key?: string;
166
  /** Scroll direction and amount */
167
  scrolling?: {
168
    direction: "up" | "down" | "left" | "right";
169
    pixels: number;
170
  };
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
// Enable computer use for a message
178
const computerMessage = await client.beta.messages.create({
179
  model: "claude-3-5-sonnet-20241022",
180
  max_tokens: 1024,
181
  tools: [
182
    {
183
      type: "computer_20241022",
184
      name: "computer",
185
      display_width_px: 1920,
186
      display_height_px: 1080,
187
    }
188
  ],
189
  messages: [
190
    { 
191
      role: "user", 
192
      content: "Take a screenshot and describe what you see" 
193
    }
194
  ],
195
  betas: ["computer-use-2024-10-22"],
196
});
197
```
198

199
### PDF Support
200

201
Enhanced PDF document processing and analysis capabilities.
202

203
```typescript { .api }
204
/**
205
 * PDF document source for beta features
206
 */
207
interface BetaBase64PDFSource {
208
  type: "base64";
209
  media_type: "application/pdf";
210
  data: string;
211
}
212

213
interface BetaURLPDFSource {
214
  type: "url";
215
  url: string;
216
}
217

218
interface BetaDocumentBlockParam {
219
  type: "document";
220
  source: BetaBase64PDFSource | BetaURLPDFSource;
221
  cache_control?: BetaCacheControlEphemeral;
222
}
223
```
224

225
**Usage Examples:**
226

227
```typescript
228
// Analyze a PDF document
229
const pdfMessage = await client.beta.messages.create({
230
  model: "claude-3-5-sonnet-20241022",
231
  max_tokens: 1024,
232
  messages: [
233
    {
234
      role: "user",
235
      content: [
236
        { type: "text", text: "Summarize this PDF document" },
237
        {
238
          type: "document",
239
          source: {
240
            type: "base64",
241
            media_type: "application/pdf",
242
            data: base64PdfData,
243
          },
244
        },
245
      ],
246
    },
247
  ],
248
  betas: ["pdfs-2024-09-25"],
249
});
250
```
251

252
### Code Execution
253

254
Execute code in a sandboxed environment with full input/output handling.
255

256
```typescript { .api }
257
/**
258
 * Code execution tools for beta features
259
 */
260
interface BetaCodeExecutionTool20250522 {
261
  type: "code_execution_20250522";
262
  name: "code_execution";
263
}
264

265
interface BetaCodeExecutionResultBlock {
266
  type: "code_execution_result";
267
  code_execution_result: {
268
    /** Exit code of the execution */
269
    exit_code: number;
270
    /** Standard output */
271
    stdout?: string;
272
    /** Standard error */
273
    stderr?: string;
274
    /** Generated files or artifacts */
275
    artifacts?: BetaCodeExecutionArtifact[];
276
  };
277
}
278

279
interface BetaCodeExecutionArtifact {
280
  /** Artifact type */
281
  type: "image" | "text" | "data";
282
  /** Artifact content */
283
  content: string;
284
  /** Content encoding */
285
  encoding?: "base64" | "utf8";
286
}
287
```
288

289
**Usage Examples:**
290

291
```typescript
292
// Execute Python code
293
const codeMessage = await client.beta.messages.create({
294
  model: "claude-3-5-sonnet-20241022",
295
  max_tokens: 1024,
296
  tools: [
297
    {
298
      type: "code_execution_20250522",
299
      name: "code_execution",
300
    }
301
  ],
302
  messages: [
303
    {
304
      role: "user",
305
      content: "Create a simple bar chart showing sales data"
306
    }
307
  ],
308
  betas: ["code-execution-2025-05-22"],
309
});
310
```
311

312
### Advanced Message Features
313

314
Beta message capabilities including enhanced streaming and batch processing.
315

316
```typescript { .api }
317
/**
318
 * Beta message features and enhancements
319
 */
320
class BetaMessages extends APIResource {
321
  create(params: BetaMessageCreateParams): APIPromise<BetaMessage>;
322
  stream(params: BetaMessageStreamParams): BetaMessageStream;
323
  countTokens(params: BetaMessageCountTokensParams): APIPromise<BetaMessageTokensCount>;
324
}
325

326
interface BetaMessageCreateParams extends MessageCreateParams {
327
  /** Beta features to enable */
328
  betas?: AnthropicBeta;
329
  /** Enhanced caching options */
330
  cache_control?: BetaCacheControlEphemeral;
331
  /** Citation configuration */
332
  citations?: BetaCitationsConfigParam;
333
}
334
```
335

336
## Beta Error Types
337

338
```typescript { .api }
339
/**
340
 * Beta-specific error types
341
 */
342
class BetaError extends AnthropicError {}
343
class BetaAPIError extends BetaError {
344
  status: number;
345
  error: BetaErrorResponse;
346
}
347
class BetaAuthenticationError extends BetaAPIError {}
348
class BetaBillingError extends BetaAPIError {}
349
class BetaInvalidRequestError extends BetaAPIError {}
350
class BetaNotFoundError extends BetaAPIError {}
351
class BetaOverloadedError extends BetaAPIError {}
352
class BetaPermissionError extends BetaAPIError {}
353
class BetaRateLimitError extends BetaAPIError {}
354
class BetaGatewayTimeoutError extends BetaAPIError {}
355

356
interface BetaErrorResponse {
357
  type: string;
358
  message: string;
359
}
360
```
361

362
## Beta Feature Guidelines
363

364
**Important Considerations:**
365

366
1. **Stability**: Beta features may change or be removed without notice
367
2. **Compatibility**: Not all beta features work with all models
368
3. **Access**: Some beta features require special access or approval
369
4. **Rate Limits**: Beta features may have different rate limits
370
5. **Pricing**: Beta features may have different pricing structures
371

372
**Best Practices:**
373

374
```typescript
375
// Always handle beta-specific errors
376
try {
377
  const result = await client.beta.messages.create({
378
    model: "claude-3-5-sonnet-20241022",
379
    max_tokens: 1024,
380
    messages: [{ role: "user", content: "Beta test" }],
381
    betas: ["new-feature-2024-12-01"],
382
  });
383
} catch (error) {
384
  if (error instanceof BetaError) {
385
    console.log("Beta feature error:", error.message);
386
    // Fallback to stable API
387
    const fallback = await client.messages.create({
388
      model: "claude-3-sonnet-20240229",
389
      max_tokens: 1024,
390
      messages: [{ role: "user", content: "Beta test" }],
391
    });
392
  }
393
}
394

395
// Feature detection
396
const isFeatureAvailable = async (feature: string) => {
397
  try {
398
    await client.beta.models.list({ betas: [feature] });
399
    return true;
400
  } catch {
401
    return false;
402
  }
403
};
404
```
405

406
## Available Beta Features
407

408
Current beta features (availability may change):
409

410
- **computer-use-2024-10-22**: Computer interface interaction
411
- **pdfs-2024-09-25**: Enhanced PDF document processing  
412
- **token-counting-2024-11-01**: Advanced token counting
413
- **message-batches-2024-09-24**: Batch message processing
414
- **code-execution-2025-05-22**: Sandboxed code execution
415
- **citations-2024-11-15**: Citation tracking and references
416

417
Check the official documentation for the most current list of available beta features and their capabilities.