pypi-anthropic

1
# Beta Features
2

3
Beta features provide access to experimental and preview functionality including advanced capabilities, new model features, and cutting-edge functionality that is in testing or early release phases.
4

5
## Capabilities
6

7
### Beta API Access
8

9
Access to beta versions of core APIs with experimental features and improvements.
10

11
```python { .api }
12
class Beta:
13
    messages: BetaMessages
14
    models: BetaModels
15
    files: BetaFiles
16

17
class AsyncBeta:
18
    messages: AsyncBetaMessages
19
    models: AsyncBetaModels
20
    files: AsyncBetaFiles
21

22
class BetaMessages:
23
    def create(
24
        self,
25
        max_tokens: int,
26
        messages: List[BetaMessageParam],
27
        model: str,
28
        *,
29
        betas: Optional[List[AnthropicBetaParam]] = None,
30
        **kwargs
31
    ) -> BetaMessage: ...
32
    
33
    batches: BetaBatches
34

35
class AsyncBetaMessages:
36
    async def create(
37
        self,
38
        max_tokens: int,
39
        messages: List[BetaMessageParam],
40
        model: str,
41
        *,
42
        betas: Optional[List[AnthropicBetaParam]] = None,
43
        **kwargs
44
    ) -> BetaMessage: ...
45
    
46
    batches: AsyncBetaBatches
47
```
48

49
### Beta Files API
50

51
File management capabilities for uploading, managing, and using files with beta features.
52

53
```python { .api }
54
class BetaFiles:
55
    def upload(
56
        self,
57
        *,
58
        file: FileTypes,
59
        betas: Optional[List[AnthropicBetaParam]] = None,
60
        **kwargs
61
    ) -> FileMetadata: ...
62
    
63
    def retrieve_metadata(self, file_id: str, **kwargs) -> FileMetadata: ...
64
    def list(**kwargs) -> List[FileMetadata]: ...
65
    def delete(self, file_id: str, **kwargs) -> DeletedFile: ...
66

67
class AsyncBetaFiles:
68
    async def upload(
69
        self,
70
        *,
71
        file: FileTypes,
72
        betas: Optional[List[AnthropicBetaParam]] = None,
73
        **kwargs
74
    ) -> FileMetadata: ...
75
    
76
    async def retrieve_metadata(self, file_id: str, **kwargs) -> FileMetadata: ...
77
    async def list(**kwargs) -> List[FileMetadata]: ...
78
    async def delete(self, file_id: str, **kwargs) -> DeletedFile: ...
79
```
80

81
### Beta Models API
82

83
Access to beta model features and experimental model capabilities.
84

85
```python { .api }
86
class BetaModels:
87
    def list(**kwargs) -> List[BetaModelInfo]: ...
88

89
class AsyncBetaModels:
90
    async def list(**kwargs) -> List[BetaModelInfo]: ...
91
```
92

93
## Core Types
94

95
### Beta Message Types
96

97
```python { .api }
98
class BetaMessage(TypedDict):
99
    id: str
100
    type: Literal["message"]
101
    role: Literal["assistant"]
102
    content: List[BetaContentBlock]
103
    model: str
104
    stop_reason: Optional[StopReason]
105
    stop_sequence: Optional[str]
106
    usage: BetaUsage
107

108
class BetaMessageParam(TypedDict):
109
    role: Literal["user", "assistant"]
110
    content: Union[str, List[BetaContentBlockParam]]
111

112
class BetaContentBlock(TypedDict):
113
    type: str
114

115
class BetaTextBlock(BetaContentBlock):
116
    type: Literal["text"]
117
    text: str
118

119
class BetaContentBlockParam(TypedDict):
120
    type: str
121

122
class BetaUsage(TypedDict):
123
    input_tokens: int
124
    output_tokens: int
125
    cache_creation_input_tokens: Optional[int]
126
    cache_read_input_tokens: Optional[int]
127
```
128

129
### Beta Tool Types
130

131
```python { .api }
132
class BetaToolParam(TypedDict):
133
    name: str
134
    description: str
135
    input_schema: Dict[str, Any]
136

137
class AnthropicBetaParam(TypedDict):
138
    type: str
139
```
140

141
### Beta File Types
142

143
```python { .api }
144
class FileMetadata(TypedDict):
145
    id: str
146
    type: Literal["file"]  
147
    filename: str
148
    purpose: str
149
    size_bytes: int
150
    created_at: str
151

152
class DeletedFile(TypedDict):
153
    id: str
154
    type: Literal["file"]
155
    deleted: bool
156
```
157

158
### Beta Model Types
159

160
```python { .api }
161
class BetaModelInfo(TypedDict):
162
    id: str
163
    type: Literal["model"]
164
    display_name: str
165
    created_at: str
166
```
167

168
### Beta Error Types
169

170
```python { .api }
171
class BetaError(TypedDict):
172
    type: str
173
    message: str
174

175
class BetaAPIError(TypedDict):
176
    type: Literal["api_error"]
177
    message: str
178

179
class BetaErrorResponse(TypedDict):
180
    type: Literal["error"]
181
    error: BetaError
182

183
class BetaBillingError(TypedDict):
184
    type: Literal["billing_error"]
185
    message: str
186

187
class BetaAuthenticationError(TypedDict):
188
    type: Literal["authentication_error"]
189
    message: str
190

191
class BetaPermissionError(TypedDict):
192
    type: Literal["permission_error"]
193
    message: str
194

195
class BetaNotFoundError(TypedDict):
196
    type: Literal["not_found_error"]
197
    message: str
198

199
class BetaRateLimitError(TypedDict):
200
    type: Literal["rate_limit_error"]
201
    message: str
202

203
class BetaOverloadedError(TypedDict):
204
    type: Literal["overloaded_error"]
205
    message: str
206

207
class BetaGatewayTimeoutError(TypedDict):
208
    type: Literal["gateway_timeout_error"]
209
    message: str
210

211
class BetaInvalidRequestError(TypedDict):
212
    type: Literal["invalid_request_error"]
213
    message: str
214
```
215

216
## Usage Examples
217

218
### Accessing Beta Features
219

220
```python
221
from anthropic import Anthropic
222

223
client = Anthropic()
224

225
# Access beta APIs
226
beta_message = client.beta.messages.create(
227
    model="claude-sonnet-4-20250514",
228
    max_tokens=1024,
229
    messages=[
230
        {"role": "user", "content": "Hello from beta!"}
231
    ],
232
    betas=["beta-feature-name"]  # Enable specific beta features
233
)
234

235
print(beta_message.content[0].text)
236
```
237

238
### Beta File Management
239

240
```python
241
# Upload a file for beta features
242
with open("document.pdf", "rb") as file:
243
    uploaded_file = client.beta.files.create(
244
        file=file,
245
        purpose="analysis"
246
    )
247

248
print(f"File uploaded: {uploaded_file.id}")
249
print(f"Filename: {uploaded_file.filename}")
250
print(f"Size: {uploaded_file.size_bytes} bytes")
251

252
# List uploaded files
253
files = client.beta.files.list()
254
for file in files:
255
    print(f"File: {file.filename} ({file.id})")
256

257
# Retrieve specific file
258
file_info = client.beta.files.retrieve(uploaded_file.id)
259
print(f"File info: {file_info}")
260

261
# Use file in beta message
262
beta_message_with_file = client.beta.messages.create(
263
    model="claude-sonnet-4-20250514",
264
    max_tokens=1024,
265
    messages=[
266
        {
267
            "role": "user",
268
            "content": [
269
                {"type": "text", "text": f"Analyze the uploaded file {uploaded_file.id}"}
270
            ]
271
        }
272
    ]
273
)
274

275
# Delete file when done
276
deleted = client.beta.files.delete(uploaded_file.id)
277
print(f"File deleted: {deleted.deleted}")
278
```
279

280
### Beta Models
281

282
```python
283
# List beta models
284
beta_models = client.beta.models.list()
285

286
print("Available beta models:")
287
for model in beta_models:
288
    print(f"- {model.display_name} ({model.id})")
289
    
290
# Use beta model
291
if beta_models:
292
    beta_model_id = beta_models[0].id
293
    
294
    message = client.beta.messages.create(
295
        model=beta_model_id,
296
        max_tokens=1024,
297
        messages=[
298
            {"role": "user", "content": "Hello from beta model!"}
299
        ]
300
    )
301
```
302

303
### Beta Message Batching
304

305
```python
306
# Create beta batch requests
307
beta_batch_requests = [
308
    {
309
        "custom_id": "beta-request-1",
310
        "method": "POST",
311
        "url": "/v1/messages",
312
        "body": {
313
            "model": "claude-sonnet-4-20250514",
314
            "max_tokens": 1024,
315
            "messages": [
316
                {"role": "user", "content": "Beta batch request 1"}
317
            ],
318
            "betas": ["beta-feature-name"]
319
        }
320
    },
321
    {
322
        "custom_id": "beta-request-2", 
323
        "method": "POST",
324
        "url": "/v1/messages",
325
        "body": {
326
            "model": "claude-sonnet-4-20250514",
327
            "max_tokens": 1024,
328
            "messages": [
329
                {"role": "user", "content": "Beta batch request 2"}
330
            ],
331
            "betas": ["beta-feature-name"]
332
        }
333
    }
334
]
335

336
# Create beta batch
337
beta_batch = client.beta.messages.batches.create(requests=beta_batch_requests)
338
print(f"Beta batch created: {beta_batch.id}")
339
```
340

341
### Beta Streaming
342

343
```python
344
# Stream with beta features
345
with client.beta.messages.stream(
346
    model="claude-sonnet-4-20250514",
347
    max_tokens=1024,
348
    messages=[
349
        {"role": "user", "content": "Stream with beta features"}
350
    ],
351
    betas=["beta-streaming-feature"]
352
) as stream:
353
    for text in stream.text_stream:
354
        print(text, end="", flush=True)
355
```
356

357
### Beta Error Handling
358

359
```python
360
from anthropic import BetaAPIError, BetaRateLimitError
361

362
try:
363
    beta_message = client.beta.messages.create(
364
        model="claude-sonnet-4-20250514",
365
        max_tokens=1024,
366
        messages=[
367
            {"role": "user", "content": "Beta request"}
368
        ],
369
        betas=["experimental-feature"]
370
    )
371
    
372
except BetaRateLimitError as e:
373
    print(f"Beta rate limit: {e}")
374
    
375
except BetaAPIError as e:
376
    print(f"Beta API error: {e}")
377
    
378
except Exception as e:
379
    print(f"Unexpected error: {e}")
380
```
381

382
### Async Beta Usage
383

384
```python
385
import asyncio
386
from anthropic import AsyncAnthropic
387

388
async def beta_async_example():
389
    client = AsyncAnthropic()
390
    
391
    # Async beta message
392
    beta_message = await client.beta.messages.create(
393
        model="claude-sonnet-4-20250514",
394
        max_tokens=1024,
395
        messages=[
396
            {"role": "user", "content": "Async beta request"}
397
        ]
398
    )
399
    
400
    # Async beta file operations
401
    with open("test.txt", "rb") as file:
402
        uploaded_file = await client.beta.files.create(
403
            file=file,
404
            purpose="testing"
405
        )
406
    
407
    files = await client.beta.files.list()
408
    print(f"Beta files: {len(files)}")
409
    
410
    # Cleanup
411
    await client.beta.files.delete(uploaded_file.id)
412
    
413
    return beta_message.content[0].text
414

415
result = asyncio.run(beta_async_example())
416
print(f"Beta result: {result}")
417
```
418

419
### Beta Feature Detection
420

421
```python
422
def check_beta_features(client: Anthropic) -> dict:
423
    """Check which beta features are available"""
424
    
425
    available_features = {
426
        "beta_messages": False,
427
        "beta_files": False,
428
        "beta_models": False,
429
        "beta_batching": False
430
    }
431
    
432
    try:
433
        # Test beta messages
434
        client.beta.messages.create(
435
            model="claude-sonnet-4-20250514",
436
            max_tokens=1,
437
            messages=[{"role": "user", "content": "test"}]
438
        )
439
        available_features["beta_messages"] = True
440
    except:
441
        pass
442
    
443
    try:
444
        # Test beta files
445
        client.beta.files.list()
446
        available_features["beta_files"] = True
447
    except:
448
        pass
449
    
450
    try:
451
        # Test beta models
452
        client.beta.models.list()
453
        available_features["beta_models"] = True
454
    except:
455
        pass
456
    
457
    try:
458
        # Test beta batching
459
        client.beta.messages.batches.list()
460
        available_features["beta_batching"] = True
461
    except:
462
        pass
463
    
464
    return available_features
465

466
# Check available beta features
467
features = check_beta_features(client)
468
print("Available beta features:")
469
for feature, available in features.items():
470
    status = "✅" if available else "❌"
471
    print(f"{status} {feature}")
472
```
473

474
### Beta Configuration
475

476
```python
477
class BetaConfig:
478
    """Configuration for beta features"""
479
    
480
    def __init__(self):
481
        self.enabled_features = [
482
            "beta-messages-2024",
483
            "beta-files-upload",
484
            "beta-streaming-enhanced"
485
        ]
486
    
487
    def create_beta_client(self) -> Anthropic:
488
        """Create client optimized for beta features"""
489
        
490
        return Anthropic(
491
            api_key=os.environ.get("ANTHROPIC_API_KEY"),
492
            default_headers={
493
                "Anthropic-Beta": ",".join(self.enabled_features),
494
                "X-Beta-User": "true"
495
            }
496
        )
497
    
498
    def create_beta_message(self, client: Anthropic, **kwargs) -> Any:
499
        """Create message with beta features enabled"""
500
        
501
        return client.beta.messages.create(
502
            betas=self.enabled_features,
503
            **kwargs
504
        )
505

506
# Usage
507
beta_config = BetaConfig()
508
beta_client = beta_config.create_beta_client()
509

510
message = beta_config.create_beta_message(
511
    beta_client,
512
    model="claude-sonnet-4-20250514",
513
    max_tokens=1024,
514
    messages=[{"role": "user", "content": "Beta configured message"}]
515
)
516
```