0
# Messages API
1

2
The Messages API is the primary interface for creating conversational interactions with Claude models. It supports single-turn queries and stateless multi-turn conversations, with capabilities including text generation, tool use, vision, document processing, streaming responses, and batch processing.
3

4
## Package Information
5

6
- **Package Name**: anthropic
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Module**: anthropic.resources.messages
10

11
## Core Imports
12

13
```python
14
from anthropic import Anthropic
15
from anthropic.types import Message, MessageParam, ContentBlock
16
```
17

18
Async version:
19

20
```python
21
from anthropic import AsyncAnthropic
22
from anthropic.types import Message, MessageParam, ContentBlock
23
```
24

25
## Basic Usage
26

27
```python
28
import anthropic
29

30
# Initialize the client
31
client = anthropic.Anthropic(api_key="your-api-key")
32

33
# Create a simple message
34
message = client.messages.create(
35
    model="claude-3-5-sonnet-20241022",
36
    max_tokens=1024,
37
    messages=[
38
        {"role": "user", "content": "Hello, Claude!"}
39
    ]
40
)
41

42
print(message.content[0].text)
43
```
44

45
## Architecture
46

47
The Messages API is built around a request-response model with support for streaming. Key components include:
48

49
- **Messages Resource**: Main interface accessed via `client.messages`
50
- **Message Objects**: Contain conversation turns with role and content
51
- **Content Blocks**: Structured units of content (text, tool use, thinking, images, documents)
52
- **Streaming**: Real-time token delivery via server-sent events
53
- **Batches**: Bulk processing for multiple message requests
54

55
Messages are stateless - each API call is independent and you must provide the full conversation history in the `messages` parameter.
56

57
## Capabilities
58

59
### Message Creation
60

61
Create conversational messages with Claude models supporting text, images, documents, tools, and various generation parameters.
62

63
```python { .api }
64
def create(
65
    *,
66
    max_tokens: int,
67
    messages: Iterable[MessageParam],
68
    model: ModelParam,
69
    metadata: MetadataParam | Omit = omit,
70
    service_tier: Literal["auto", "standard_only"] | Omit = omit,
71
    stop_sequences: SequenceNotStr[str] | Omit = omit,
72
    stream: Literal[False] | Literal[True] | Omit = omit,
73
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
74
    temperature: float | Omit = omit,
75
    thinking: ThinkingConfigParam | Omit = omit,
76
    tool_choice: ToolChoiceParam | Omit = omit,
77
    tools: Iterable[ToolUnionParam] | Omit = omit,
78
    top_k: int | Omit = omit,
79
    top_p: float | Omit = omit,
80
    extra_headers: Headers | None = None,
81
    extra_query: Query | None = None,
82
    extra_body: Body | None = None,
83
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
84
) -> Message | Stream[RawMessageStreamEvent]:
85
    """
86
    Send a structured list of input messages with text and/or image content, and the
87
    model will generate the next message in the conversation.
88

89
    Args:
90
        max_tokens: The maximum number of tokens to generate before stopping.
91
            Note that models may stop before reaching this maximum. Different models
92
            have different maximum values for this parameter.
93

94
        messages: Input messages representing the conversation history.
95
            Our models are trained to operate on alternating user and assistant
96
            conversational turns. Each input message must be an object with a role
97
            and content. You can specify a single user-role message, or multiple
98
            user and assistant messages. Consecutive user or assistant turns will
99
            be combined into a single turn.
100

101
        model: The model that will complete your prompt.
102
            Examples: "claude-3-5-sonnet-20241022", "claude-3-opus-20240229"
103

104
        metadata: An object describing metadata about the request.
105
            Contains optional user_id field for tracking and abuse detection.
106

107
        service_tier: Determines whether to use priority capacity (if available) or
108
            standard capacity for this request. Options: "auto", "standard_only"
109

110
        stop_sequences: Custom text sequences that will cause the model to stop generating.
111
            If the model encounters one of these sequences, the response stop_reason
112
            will be "stop_sequence" and stop_sequence will contain the matched sequence.
113

114
        stream: Whether to incrementally stream the response using server-sent events.
115
            When True, returns a Stream object instead of a Message.
116

117
        system: System prompt providing context and instructions to Claude.
118
            Can be a string or list of TextBlockParam objects. System prompts are used
119
            to specify a particular goal or role for the assistant.
120

121
        temperature: Amount of randomness injected into the response.
122
            Defaults to 1.0. Ranges from 0.0 to 1.0. Use temperature closer to 0.0
123
            for analytical tasks, and closer to 1.0 for creative tasks. Even with
124
            temperature of 0.0, results will not be fully deterministic.
125

126
        thinking: Configuration for enabling Claude's extended thinking.
127
            When enabled, responses include thinking content blocks showing Claude's
128
            reasoning process before the final answer. Requires a minimum budget of
129
            1,024 tokens and counts towards max_tokens limit.
130

131
        tool_choice: How the model should use the provided tools.
132
            Controls whether the model can use a specific tool, any tool, decide
133
            automatically, or not use tools at all.
134

135
        tools: Definitions of tools that the model may use.
136
            If included, the model may return tool_use content blocks. You then run
137
            those tools and return results via tool_result content blocks.
138

139
        top_k: Only sample from the top K options for each subsequent token.
140
            Used to remove "long tail" low probability responses. Recommended for
141
            advanced use cases only - usually you only need temperature.
142

143
        top_p: Use nucleus sampling.
144
            Computes the cumulative distribution over all options for each token
145
            in decreasing probability order and cuts off at top_p. You should alter
146
            either temperature or top_p, but not both. Recommended for advanced use
147
            cases only.
148

149
        extra_headers: Send extra headers with the request
150

151
        extra_query: Add additional query parameters to the request
152

153
        extra_body: Add additional JSON properties to the request body
154

155
        timeout: Override the client-level default timeout for this request, in seconds
156

157
    Returns:
158
        Message: The generated message response (when stream=False)
159
        Stream[RawMessageStreamEvent]: A stream of events (when stream=True)
160
    """
161
```
162

163
```python { .api }
164
async def create(
165
    *,
166
    max_tokens: int,
167
    messages: Iterable[MessageParam],
168
    model: ModelParam,
169
    metadata: MetadataParam | Omit = omit,
170
    service_tier: Literal["auto", "standard_only"] | Omit = omit,
171
    stop_sequences: SequenceNotStr[str] | Omit = omit,
172
    stream: Literal[False] | Literal[True] | Omit = omit,
173
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
174
    temperature: float | Omit = omit,
175
    thinking: ThinkingConfigParam | Omit = omit,
176
    tool_choice: ToolChoiceParam | Omit = omit,
177
    tools: Iterable[ToolUnionParam] | Omit = omit,
178
    top_k: int | Omit = omit,
179
    top_p: float | Omit = omit,
180
    extra_headers: Headers | None = None,
181
    extra_query: Query | None = None,
182
    extra_body: Body | None = None,
183
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
184
) -> Message | AsyncStream[RawMessageStreamEvent]:
185
    """
186
    Async version of create(). See create() for full documentation.
187
    """
188
```
189

190
### Streaming Messages
191

192
Create a streaming message response with a convenient context manager interface for real-time token delivery.
193

194
```python { .api }
195
def stream(
196
    *,
197
    max_tokens: int,
198
    messages: Iterable[MessageParam],
199
    model: ModelParam,
200
    metadata: MetadataParam | Omit = omit,
201
    container: Optional[str] | Omit = omit,
202
    service_tier: Literal["auto", "standard_only"] | Omit = omit,
203
    stop_sequences: SequenceNotStr[str] | Omit = omit,
204
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
205
    temperature: float | Omit = omit,
206
    top_k: int | Omit = omit,
207
    top_p: float | Omit = omit,
208
    thinking: ThinkingConfigParam | Omit = omit,
209
    tool_choice: ToolChoiceParam | Omit = omit,
210
    tools: Iterable[ToolUnionParam] | Omit = omit,
211
    extra_headers: Headers | None = None,
212
    extra_query: Query | None = None,
213
    extra_body: Body | None = None,
214
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
215
) -> MessageStreamManager:
216
    """
217
    Create a Message stream with context manager support.
218

219
    Returns:
220
        MessageStreamManager: A context manager that yields MessageStream for
221
            iterating over streaming events and accessing the final message.
222
    """
223
```
224

225
```python { .api }
226
def stream(
227
    *,
228
    max_tokens: int,
229
    messages: Iterable[MessageParam],
230
    model: ModelParam,
231
    metadata: MetadataParam | Omit = omit,
232
    container: Optional[str] | Omit = omit,
233
    service_tier: Literal["auto", "standard_only"] | Omit = omit,
234
    stop_sequences: SequenceNotStr[str] | Omit = omit,
235
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
236
    temperature: float | Omit = omit,
237
    top_k: int | Omit = omit,
238
    top_p: float | Omit = omit,
239
    thinking: ThinkingConfigParam | Omit = omit,
240
    tool_choice: ToolChoiceParam | Omit = omit,
241
    tools: Iterable[ToolUnionParam] | Omit = omit,
242
    extra_headers: Headers | None = None,
243
    extra_query: Query | None = None,
244
    extra_body: Body | None = None,
245
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
246
) -> AsyncMessageStreamManager:
247
    """
248
    Async version of stream(). Returns AsyncMessageStreamManager for async iteration.
249
    """
250
```
251

252
### Token Counting
253

254
Count the number of tokens in a message without creating it, useful for estimating costs and managing token limits.
255

256
```python { .api }
257
def count_tokens(
258
    *,
259
    messages: Iterable[MessageParam],
260
    model: ModelParam,
261
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
262
    thinking: ThinkingConfigParam | Omit = omit,
263
    tool_choice: ToolChoiceParam | Omit = omit,
264
    tools: Iterable[MessageCountTokensToolParam] | Omit = omit,
265
    extra_headers: Headers | None = None,
266
    extra_query: Query | None = None,
267
    extra_body: Body | None = None,
268
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
269
) -> MessageTokensCount:
270
    """
271
    Count the number of tokens in a Message.
272

273
    The Token Count API can be used to count tokens in a Message, including tools,
274
    images, and documents, without creating it. This is useful for:
275
    - Estimating API costs before making requests
276
    - Ensuring requests stay within model token limits
277
    - Optimizing prompt length
278

279
    Args:
280
        messages: Input messages to count tokens for.
281
            Same format as create() - alternating user and assistant turns.
282

283
        model: The model that would complete the prompt.
284
            Token counts vary by model.
285

286
        system: System prompt to include in the token count.
287

288
        thinking: Configuration for extended thinking.
289
            If enabled, includes thinking token budget in the count.
290

291
        tool_choice: How the model should use the provided tools.
292

293
        tools: Tool definitions to include in the token count.
294

295
        extra_headers: Send extra headers with the request
296

297
        extra_query: Add additional query parameters to the request
298

299
        extra_body: Add additional JSON properties to the request body
300

301
        timeout: Override the client-level default timeout for this request, in seconds
302

303
    Returns:
304
        MessageTokensCount: Object containing input_tokens count
305
    """
306
```
307

308
```python { .api }
309
async def count_tokens(
310
    *,
311
    messages: Iterable[MessageParam],
312
    model: ModelParam,
313
    system: Union[str, Iterable[TextBlockParam]] | Omit = omit,
314
    thinking: ThinkingConfigParam | Omit = omit,
315
    tool_choice: ToolChoiceParam | Omit = omit,
316
    tools: Iterable[MessageCountTokensToolParam] | Omit = omit,
317
    extra_headers: Headers | None = None,
318
    extra_query: Query | None = None,
319
    extra_body: Body | None = None,
320
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
321
) -> MessageTokensCount:
322
    """
323
    Async version of count_tokens(). See count_tokens() for full documentation.
324
    """
325
```
326

327
### Message Batches
328

329
Process multiple message creation requests in a single batch operation for cost-effective bulk processing.
330

331
```python { .api }
332
@property
333
def batches(self) -> Batches:
334
    """
335
    Access the Batches sub-resource for batch message processing.
336

337
    Returns:
338
        Batches: The batches resource with methods for creating, retrieving,
339
            listing, canceling, deleting batches, and streaming results.
340
    """
341
```
342

343
## Message Batches Resource
344

345
The Batches sub-resource provides methods for bulk message processing.
346

347
### Creating Batches
348

349
```python { .api }
350
def create(
351
    *,
352
    requests: Iterable[Request],
353
    extra_headers: Headers | None = None,
354
    extra_query: Query | None = None,
355
    extra_body: Body | None = None,
356
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
357
) -> MessageBatch:
358
    """
359
    Send a batch of Message creation requests.
360

361
    The Message Batches API can be used to process multiple Messages API requests
362
    at once. Once a Message Batch is created, it begins processing immediately.
363
    Batches can take up to 24 hours to complete.
364

365
    Args:
366
        requests: List of requests for prompt completion. Each is an individual
367
            request to create a Message with its own custom_id for identification.
368

369
        extra_headers: Send extra headers with the request
370
        extra_query: Add additional query parameters to the request
371
        extra_body: Add additional JSON properties to the request body
372
        timeout: Override the client-level default timeout for this request
373

374
    Returns:
375
        MessageBatch: The created batch with id, status, and request counts
376
    """
377
```
378

379
### Retrieving Batch Status
380

381
```python { .api }
382
def retrieve(
383
    message_batch_id: str,
384
    *,
385
    extra_headers: Headers | None = None,
386
    extra_query: Query | None = None,
387
    extra_body: Body | None = None,
388
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
389
) -> MessageBatch:
390
    """
391
    Retrieve the status of a Message Batch.
392

393
    This endpoint is idempotent and can be used to poll for Message Batch completion.
394
    To access the results of a Message Batch, make a request to the results_url
395
    field in the response.
396

397
    Args:
398
        message_batch_id: ID of the Message Batch
399
        extra_headers: Send extra headers with the request
400
        extra_query: Add additional query parameters to the request
401
        extra_body: Add additional JSON properties to the request body
402
        timeout: Override the client-level default timeout for this request
403

404
    Returns:
405
        MessageBatch: The batch with current status and request counts
406
    """
407
```
408

409
### Listing Batches
410

411
```python { .api }
412
def list(
413
    *,
414
    after_id: str | Omit = omit,
415
    before_id: str | Omit = omit,
416
    limit: int | Omit = omit,
417
    extra_headers: Headers | None = None,
418
    extra_query: Query | None = None,
419
    extra_body: Body | None = None,
420
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
421
) -> SyncPage[MessageBatch]:
422
    """
423
    List all Message Batches within a Workspace.
424

425
    Most recently created batches are returned first.
426

427
    Args:
428
        after_id: ID of the object to use as a cursor for pagination. When provided,
429
            returns the page of results immediately after this object.
430

431
        before_id: ID of the object to use as a cursor for pagination. When provided,
432
            returns the page of results immediately before this object.
433

434
        limit: Number of items to return per page.
435
            Defaults to 20. Ranges from 1 to 1000.
436

437
        extra_headers: Send extra headers with the request
438
        extra_query: Add additional query parameters to the request
439
        extra_body: Add additional JSON properties to the request body
440
        timeout: Override the client-level default timeout for this request
441

442
    Returns:
443
        SyncPage[MessageBatch]: Paginated list of message batches
444
    """
445
```
446

447
**Note**: The async version of `list()` returns `AsyncPaginator[MessageBatch, AsyncPage[MessageBatch]]` instead of `SyncPage[MessageBatch]`.
448

449
### Canceling Batches
450

451
```python { .api }
452
def cancel(
453
    message_batch_id: str,
454
    *,
455
    extra_headers: Headers | None = None,
456
    extra_query: Query | None = None,
457
    extra_body: Body | None = None,
458
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
459
) -> MessageBatch:
460
    """
461
    Cancel an in-progress Message Batch.
462

463
    Batches may be canceled any time before processing ends. Once cancellation is
464
    initiated, the batch enters a "canceling" state. The system may complete any
465
    in-progress, non-interruptible requests before finalizing cancellation.
466

467
    The number of canceled requests is specified in request_counts. To determine
468
    which requests were canceled, check the individual results within the batch.
469
    Note that cancellation may not result in any canceled requests if they were
470
    non-interruptible.
471

472
    Args:
473
        message_batch_id: ID of the Message Batch
474
        extra_headers: Send extra headers with the request
475
        extra_query: Add additional query parameters to the request
476
        extra_body: Add additional JSON properties to the request body
477
        timeout: Override the client-level default timeout for this request
478

479
    Returns:
480
        MessageBatch: The batch with updated canceling status
481
    """
482
```
483

484
### Deleting Batches
485

486
```python { .api }
487
def delete(
488
    message_batch_id: str,
489
    *,
490
    extra_headers: Headers | None = None,
491
    extra_query: Query | None = None,
492
    extra_body: Body | None = None,
493
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
494
) -> DeletedMessageBatch:
495
    """
496
    Delete a Message Batch.
497

498
    Message Batches can only be deleted once they've finished processing. If you'd
499
    like to delete an in-progress batch, you must first cancel it.
500

501
    Args:
502
        message_batch_id: ID of the Message Batch
503
        extra_headers: Send extra headers with the request
504
        extra_query: Add additional query parameters to the request
505
        extra_body: Add additional JSON properties to the request body
506
        timeout: Override the client-level default timeout for this request
507

508
    Returns:
509
        DeletedMessageBatch: Confirmation of deletion with id and deleted flag
510
    """
511
```
512

513
### Streaming Batch Results
514

515
```python { .api }
516
def results(
517
    message_batch_id: str,
518
    *,
519
    extra_headers: Headers | None = None,
520
    extra_query: Query | None = None,
521
    extra_body: Body | None = None,
522
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
523
) -> JSONLDecoder[MessageBatchIndividualResponse]:
524
    """
525
    Streams the results of a Message Batch as a .jsonl file.
526

527
    Each line in the file is a JSON object containing the result of a single request
528
    in the Message Batch. Results are not guaranteed to be in the same order as
529
    requests. Use the custom_id field to match results to requests.
530

531
    Args:
532
        message_batch_id: ID of the Message Batch
533
        extra_headers: Send extra headers with the request
534
        extra_query: Add additional query parameters to the request
535
        extra_body: Add additional JSON properties to the request body
536
        timeout: Override the client-level default timeout for this request
537

538
    Returns:
539
        JSONLDecoder[MessageBatchIndividualResponse]: Iterator over individual batch results
540
    """
541
```
542

543
## Type Definitions
544

545
### Core Message Types
546

547
```python { .api }
548
class Message:
549
    """
550
    Represents a message response from the API.
551

552
    Attributes:
553
        id (str): Unique message identifier
554
        type (Literal["message"]): Type identifier
555
        role (Literal["assistant"]): Role of the message
556
        content (List[ContentBlock]): Message content blocks
557
        model (str): Model that generated the message
558
        stop_reason (StopReason | None): Why generation stopped
559
        stop_sequence (str | None): Stop sequence that was matched (if any)
560
        usage (Usage): Token usage information
561
    """
562
```
563

564
```python { .api }
565
class MessageParam(TypedDict):
566
    """
567
    Message in conversation history for API requests.
568

569
    Attributes:
570
        role (Literal["user", "assistant"]): Message role
571
        content (str | List[ContentBlockParam]): Message content
572
            Can be a simple string or list of structured content blocks
573
    """
574
```
575

576
```python { .api }
577
class Usage:
578
    """
579
    Token usage information for a message.
580

581
    Attributes:
582
        input_tokens (int): Input tokens used
583
        output_tokens (int): Output tokens generated
584
        cache_creation_input_tokens (int | None): Tokens used for cache creation
585
        cache_read_input_tokens (int | None): Tokens read from cache
586
    """
587
```
588

589
```python { .api }
590
class MessageTokensCount:
591
    """
592
    Token count result from count_tokens().
593

594
    Attributes:
595
        input_tokens (int): Number of input tokens
596
    """
597
```
598

599
### Content Block Types
600

601
```python { .api }
602
ContentBlock = Union[
603
    TextBlock,
604
    ThinkingBlock,
605
    RedactedThinkingBlock,
606
    ToolUseBlock,
607
    ServerToolUseBlock,
608
    WebSearchResultBlock
609
]
610
```
611

612
```python { .api }
613
class TextBlock:
614
    """
615
    Text content block in a message response.
616

617
    Attributes:
618
        type (Literal["text"]): Block type identifier
619
        text (str): Text content
620
        citations (List[TextCitation] | None): Text citations (if any)
621
    """
622
```
623

624
```python { .api }
625
class ToolUseBlock:
626
    """
627
    Tool use content block in a message response.
628

629
    Attributes:
630
        type (Literal["tool_use"]): Block type identifier
631
        id (str): Unique tool use identifier
632
        name (str): Name of the tool
633
        input (dict): Tool input parameters
634
    """
635
```
636

637
```python { .api }
638
class ThinkingBlock:
639
    """
640
    Thinking content block showing Claude's reasoning process.
641

642
    Attributes:
643
        type (Literal["thinking"]): Block type identifier
644
        thinking (str): Thinking content showing reasoning
645
    """
646
```
647

648
### Content Block Parameters
649

650
```python { .api }
651
ContentBlockParam = Union[
652
    TextBlockParam,
653
    ImageBlockParam,
654
    DocumentBlockParam,
655
    SearchResultBlockParam,
656
    ThinkingBlockParam,
657
    RedactedThinkingBlockParam,
658
    ToolUseBlockParam,
659
    ToolResultBlockParam,
660
    ServerToolUseBlockParam,
661
    WebSearchToolResultBlockParam
662
]
663
```
664

665
```python { .api }
666
class TextBlockParam(TypedDict):
667
    """
668
    Text content block parameter for requests.
669

670
    Attributes:
671
        type (Literal["text"]): Block type
672
        text (str): Text content
673
        cache_control (CacheControlEphemeralParam | None): Cache control settings
674
    """
675
```
676

677
```python { .api }
678
class ImageBlockParam(TypedDict):
679
    """
680
    Image content block parameter for vision requests.
681

682
    Attributes:
683
        type (Literal["image"]): Block type
684
        source (Base64ImageSourceParam | URLImageSourceParam): Image source
685
        cache_control (CacheControlEphemeralParam | None): Cache control settings
686
    """
687
```
688

689
```python { .api }
690
class DocumentBlockParam(TypedDict):
691
    """
692
    Document content block parameter for document processing.
693

694
    Attributes:
695
        type (Literal["document"]): Block type
696
        source (Base64PDFSourceParam | URLPDFSourceParam): Document source
697
        cache_control (CacheControlEphemeralParam | None): Cache control settings
698
    """
699
```
700

701
```python { .api }
702
class ToolUseBlockParam(TypedDict):
703
    """
704
    Tool use content block parameter (for assistant messages).
705

706
    Attributes:
707
        type (Literal["tool_use"]): Block type
708
        id (str): Tool use identifier
709
        name (str): Tool name
710
        input (dict): Tool input parameters
711
    """
712
```
713

714
```python { .api }
715
class ToolResultBlockParam(TypedDict):
716
    """
717
    Tool result content block parameter (for user messages).
718

719
    Attributes:
720
        type (Literal["tool_result"]): Block type
721
        tool_use_id (str): ID of the tool use this is a result for
722
        content (str | List[ContentBlockParam]): Result content
723
        is_error (bool | None): Whether the result represents an error
724
    """
725
```
726

727
### Image and Document Sources
728

729
```python { .api }
730
class Base64ImageSourceParam(TypedDict):
731
    """
732
    Base64-encoded image source.
733

734
    Attributes:
735
        type (Literal["base64"]): Source type
736
        media_type (str): MIME type (e.g., "image/jpeg", "image/png", "image/gif", "image/webp")
737
        data (str): Base64-encoded image data
738
    """
739
```
740

741
```python { .api }
742
class URLImageSourceParam(TypedDict):
743
    """
744
    URL-based image source.
745

746
    Attributes:
747
        type (Literal["url"]): Source type
748
        url (str): Image URL
749
    """
750
```
751

752
```python { .api }
753
class Base64PDFSourceParam(TypedDict):
754
    """
755
    Base64-encoded PDF document source.
756

757
    Attributes:
758
        type (Literal["base64"]): Source type
759
        media_type (Literal["application/pdf"]): PDF media type
760
        data (str): Base64-encoded PDF data
761
    """
762
```
763

764
```python { .api }
765
class URLPDFSourceParam(TypedDict):
766
    """
767
    URL-based PDF document source.
768

769
    Attributes:
770
        type (Literal["url"]): Source type
771
        url (str): PDF URL
772
    """
773
```
774

775
### Tool Types
776

777
```python { .api }
778
class ToolParam(TypedDict):
779
    """
780
    Tool definition for API requests.
781

782
    Attributes:
783
        name (str): Tool name
784
        description (str | None): Tool description (strongly recommended)
785
        input_schema (dict): JSON schema for tool input
786
        cache_control (CacheControlEphemeralParam | None): Cache control settings
787
    """
788
```
789

790
```python { .api }
791
ToolChoiceParam = Union[
792
    ToolChoiceAutoParam,
793
    ToolChoiceAnyParam,
794
    ToolChoiceToolParam,
795
    ToolChoiceNoneParam
796
]
797
```
798

799
```python { .api }
800
class ToolChoiceAutoParam(TypedDict):
801
    """
802
    Allow model to automatically decide whether to use tools.
803

804
    Attributes:
805
        type (Literal["auto"]): Auto selection mode
806
        disable_parallel_tool_use (bool | None): Disable parallel tool use
807
    """
808
```
809

810
```python { .api }
811
class ToolChoiceAnyParam(TypedDict):
812
    """
813
    Require model to use at least one tool.
814

815
    Attributes:
816
        type (Literal["any"]): Any tool must be used
817
        disable_parallel_tool_use (bool | None): Disable parallel tool use
818
    """
819
```
820

821
```python { .api }
822
class ToolChoiceToolParam(TypedDict):
823
    """
824
    Require model to use a specific tool.
825

826
    Attributes:
827
        type (Literal["tool"]): Specific tool mode
828
        name (str): Name of the tool to use
829
        disable_parallel_tool_use (bool | None): Disable parallel tool use
830
    """
831
```
832

833
```python { .api }
834
class ToolChoiceNoneParam(TypedDict):
835
    """
836
    Prevent model from using any tools.
837

838
    Attributes:
839
        type (Literal["none"]): No tools mode
840
    """
841
```
842

843
### Thinking Configuration
844

845
```python { .api }
846
ThinkingConfigParam = Union[ThinkingConfigEnabledParam, ThinkingConfigDisabledParam]
847
```
848

849
```python { .api }
850
class ThinkingConfigEnabledParam(TypedDict):
851
    """
852
    Enable extended thinking with configuration.
853

854
    Attributes:
855
        type (Literal["enabled"]): Enable thinking mode
856
        budget_tokens (int): Token budget for thinking (minimum 1024)
857
    """
858
```
859

860
```python { .api }
861
class ThinkingConfigDisabledParam(TypedDict):
862
    """
863
    Disable extended thinking.
864

865
    Attributes:
866
        type (Literal["disabled"]): Disable thinking mode
867
    """
868
```
869

870
### Metadata Types
871

872
```python { .api }
873
class MetadataParam(TypedDict):
874
    """
875
    Request metadata.
876

877
    Attributes:
878
        user_id (str | None): User identifier for tracking and abuse detection
879
    """
880
```
881

882
### Batch Types
883

884
```python { .api }
885
class MessageBatch:
886
    """
887
    Batch processing job for multiple message requests.
888

889
    Attributes:
890
        id (str): Unique batch identifier
891
        type (Literal["message_batch"]): Type identifier
892
        processing_status (str): Current processing status
893
        request_counts (MessageBatchRequestCounts): Request count breakdown
894
        created_at (datetime): Batch creation timestamp
895
        expires_at (datetime): Batch expiration timestamp
896
        results_url (str | None): URL to download results
897
    """
898
```
899

900
```python { .api }
901
class MessageBatchRequestCounts:
902
    """
903
    Breakdown of request counts in a batch.
904

905
    Attributes:
906
        processing (int): Requests currently processing
907
        succeeded (int): Successfully completed requests
908
        errored (int): Requests that encountered errors
909
        canceled (int): Requests that were canceled
910
        expired (int): Requests that expired
911
    """
912
```
913

914
```python { .api }
915
class DeletedMessageBatch:
916
    """
917
    Confirmation of batch deletion.
918

919
    Attributes:
920
        id (str): Batch identifier
921
        type (Literal["message_batch_deleted"]): Type identifier
922
        deleted (bool): Whether deletion was successful
923
    """
924
```
925

926
```python { .api }
927
class MessageBatchIndividualResponse:
928
    """
929
    Individual batch result entry.
930

931
    Attributes:
932
        custom_id (str): Custom request identifier from the batch request
933
        result (MessageBatchResult): Result data (success, error, canceled, or expired)
934
    """
935
```
936

937
### Other Types
938

939
```python { .api }
940
ModelParam = Union[str, ModelInfo]
941
```
942

943
```python { .api }
944
StopReason = Literal["end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal"]
945
```
946

947
```python { .api }
948
class CacheControlEphemeralParam(TypedDict):
949
    """
950
    Prompt caching configuration.
951

952
    Attributes:
953
        type (Literal["ephemeral"]): Cache type
954
    """
955
```
956

957
## Usage Examples
958

959
### Multi-turn Conversation
960

961
```python
962
import anthropic
963

964
client = anthropic.Anthropic()
965

966
# Build conversation history
967
conversation = [
968
    {"role": "user", "content": "Hello, what's your name?"},
969
]
970

971
# First turn
972
message = client.messages.create(
973
    model="claude-3-5-sonnet-20241022",
974
    max_tokens=1024,
975
    messages=conversation
976
)
977

978
# Add assistant response to history
979
conversation.append({
980
    "role": "assistant",
981
    "content": message.content[0].text
982
})
983

984
# Second turn
985
conversation.append({
986
    "role": "user",
987
    "content": "Can you help me understand quantum computing?"
988
})
989

990
message = client.messages.create(
991
    model="claude-3-5-sonnet-20241022",
992
    max_tokens=2048,
993
    messages=conversation
994
)
995

996
print(message.content[0].text)
997
```
998

999
### System Prompts
1000

1001
```python
1002
message = client.messages.create(
1003
    model="claude-3-5-sonnet-20241022",
1004
    max_tokens=1024,
1005
    system="You are a helpful assistant that explains complex topics in simple terms suitable for children.",
1006
    messages=[
1007
        {"role": "user", "content": "What is photosynthesis?"}
1008
    ]
1009
)
1010
```
1011

1012
### Streaming Responses
1013

1014
```python
1015
with client.messages.stream(
1016
    model="claude-3-5-sonnet-20241022",
1017
    max_tokens=1024,
1018
    messages=[
1019
        {"role": "user", "content": "Write a short story about a robot."}
1020
    ]
1021
) as stream:
1022
    for text in stream.text_stream:
1023
        print(text, end="", flush=True)
1024

1025
    # Get the final complete message
1026
    final_message = stream.get_final_message()
1027
    print(f"\n\nStop reason: {final_message.stop_reason}")
1028
    print(f"Tokens used: {final_message.usage.output_tokens}")
1029
```
1030

1031
### Async Streaming
1032

1033
```python
1034
import asyncio
1035
import anthropic
1036

1037
async def main():
1038
    client = anthropic.AsyncAnthropic()
1039

1040
    async with client.messages.stream(
1041
        model="claude-3-5-sonnet-20241022",
1042
        max_tokens=1024,
1043
        messages=[
1044
            {"role": "user", "content": "Tell me about Python async programming."}
1045
        ]
1046
    ) as stream:
1047
        async for text in stream.text_stream:
1048
            print(text, end="", flush=True)
1049

1050
asyncio.run(main())
1051
```
1052

1053
### Vision - Images
1054

1055
```python
1056
import base64
1057

1058
# Load and encode image
1059
with open("image.jpg", "rb") as image_file:
1060
    image_data = base64.standard_b64encode(image_file.read()).decode("utf-8")
1061

1062
message = client.messages.create(
1063
    model="claude-3-5-sonnet-20241022",
1064
    max_tokens=1024,
1065
    messages=[
1066
        {
1067
            "role": "user",
1068
            "content": [
1069
                {
1070
                    "type": "image",
1071
                    "source": {
1072
                        "type": "base64",
1073
                        "media_type": "image/jpeg",
1074
                        "data": image_data,
1075
                    },
1076
                },
1077
                {
1078
                    "type": "text",
1079
                    "text": "What's in this image?"
1080
                }
1081
            ],
1082
        }
1083
    ],
1084
)
1085
```
1086

1087
### Document Processing
1088

1089
```python
1090
import base64
1091

1092
# Load and encode PDF
1093
with open("document.pdf", "rb") as pdf_file:
1094
    pdf_data = base64.standard_b64encode(pdf_file.read()).decode("utf-8")
1095

1096
message = client.messages.create(
1097
    model="claude-3-5-sonnet-20241022",
1098
    max_tokens=2048,
1099
    messages=[
1100
        {
1101
            "role": "user",
1102
            "content": [
1103
                {
1104
                    "type": "document",
1105
                    "source": {
1106
                        "type": "base64",
1107
                        "media_type": "application/pdf",
1108
                        "data": pdf_data,
1109
                    },
1110
                },
1111
                {
1112
                    "type": "text",
1113
                    "text": "Summarize the key points in this document."
1114
                }
1115
            ],
1116
        }
1117
    ],
1118
)
1119
```
1120

1121
### Tool Use
1122

1123
```python
1124
# Define tools
1125
tools = [
1126
    {
1127
        "name": "get_weather",
1128
        "description": "Get the current weather in a given location",
1129
        "input_schema": {
1130
            "type": "object",
1131
            "properties": {
1132
                "location": {
1133
                    "type": "string",
1134
                    "description": "The city and state, e.g. San Francisco, CA"
1135
                },
1136
                "unit": {
1137
                    "type": "string",
1138
                    "enum": ["celsius", "fahrenheit"],
1139
                    "description": "The unit of temperature"
1140
                }
1141
            },
1142
            "required": ["location"]
1143
        }
1144
    }
1145
]
1146

1147
# Initial request
1148
message = client.messages.create(
1149
    model="claude-3-5-sonnet-20241022",
1150
    max_tokens=1024,
1151
    tools=tools,
1152
    messages=[
1153
        {"role": "user", "content": "What's the weather like in San Francisco?"}
1154
    ]
1155
)
1156

1157
# Check if model wants to use a tool
1158
if message.stop_reason == "tool_use":
1159
    tool_use = next(block for block in message.content if block.type == "tool_use")
1160

1161
    # Execute the tool (your implementation)
1162
    tool_result = get_weather(tool_use.input["location"])
1163

1164
    # Return result to model
1165
    response = client.messages.create(
1166
        model="claude-3-5-sonnet-20241022",
1167
        max_tokens=1024,
1168
        tools=tools,
1169
        messages=[
1170
            {"role": "user", "content": "What's the weather like in San Francisco?"},
1171
            {"role": "assistant", "content": message.content},
1172
            {
1173
                "role": "user",
1174
                "content": [
1175
                    {
1176
                        "type": "tool_result",
1177
                        "tool_use_id": tool_use.id,
1178
                        "content": str(tool_result)
1179
                    }
1180
                ]
1181
            }
1182
        ]
1183
    )
1184

1185
    print(response.content[0].text)
1186
```
1187

1188
### Force Tool Use
1189

1190
```python
1191
# Require model to use a specific tool
1192
message = client.messages.create(
1193
    model="claude-3-5-sonnet-20241022",
1194
    max_tokens=1024,
1195
    tools=tools,
1196
    tool_choice={"type": "tool", "name": "get_weather"},
1197
    messages=[
1198
        {"role": "user", "content": "What's the weather?"}
1199
    ]
1200
)
1201
```
1202

1203
### Extended Thinking
1204

1205
```python
1206
message = client.messages.create(
1207
    model="claude-3-7-sonnet-20250219",
1208
    max_tokens=4096,
1209
    thinking={
1210
        "type": "enabled",
1211
        "budget_tokens": 2000
1212
    },
1213
    messages=[
1214
        {"role": "user", "content": "Solve this complex math problem: ..."}
1215
    ]
1216
)
1217

1218
# Check for thinking content
1219
for block in message.content:
1220
    if block.type == "thinking":
1221
        print(f"Thinking process: {block.thinking}")
1222
    elif block.type == "text":
1223
        print(f"Answer: {block.text}")
1224
```
1225

1226
### Token Counting
1227

1228
```python
1229
# Count tokens before making request
1230
count = client.messages.count_tokens(
1231
    model="claude-3-5-sonnet-20241022",
1232
    messages=[
1233
        {"role": "user", "content": "Tell me a long story about space exploration."}
1234
    ],
1235
    system="You are a science fiction author."
1236
)
1237

1238
print(f"This request will use {count.input_tokens} input tokens")
1239

1240
# Check if within limits and estimate cost
1241
if count.input_tokens < 10000:
1242
    message = client.messages.create(
1243
        model="claude-3-5-sonnet-20241022",
1244
        max_tokens=2048,
1245
        system="You are a science fiction author.",
1246
        messages=[
1247
            {"role": "user", "content": "Tell me a long story about space exploration."}
1248
        ]
1249
    )
1250
```
1251

1252
### Batch Processing
1253

1254
```python
1255
# Create a batch of message requests
1256
batch_requests = [
1257
    {
1258
        "custom_id": "request-1",
1259
        "params": {
1260
            "model": "claude-3-5-sonnet-20241022",
1261
            "max_tokens": 1024,
1262
            "messages": [
1263
                {"role": "user", "content": "What is machine learning?"}
1264
            ]
1265
        }
1266
    },
1267
    {
1268
        "custom_id": "request-2",
1269
        "params": {
1270
            "model": "claude-3-5-sonnet-20241022",
1271
            "max_tokens": 1024,
1272
            "messages": [
1273
                {"role": "user", "content": "What is deep learning?"}
1274
            ]
1275
        }
1276
    }
1277
]
1278

1279
# Create the batch
1280
batch = client.messages.batches.create(requests=batch_requests)
1281
print(f"Batch created: {batch.id}")
1282

1283
# Poll for completion
1284
import time
1285
while batch.processing_status == "in_progress":
1286
    time.sleep(10)
1287
    batch = client.messages.batches.retrieve(batch.id)
1288
    print(f"Status: {batch.processing_status}")
1289

1290
# Retrieve results
1291
if batch.processing_status == "ended":
1292
    results = client.messages.batches.results(batch.id)
1293
    for result in results:
1294
        print(f"Request {result.custom_id}:")
1295
        if result.result.type == "succeeded":
1296
            print(f"  Response: {result.result.message.content[0].text}")
1297
        else:
1298
            print(f"  Error: {result.result.error}")
1299
```
1300

1301
### Prefilling Assistant Response
1302

1303
```python
1304
# Guide the model's response by prefilling part of it
1305
message = client.messages.create(
1306
    model="claude-3-5-sonnet-20241022",
1307
    max_tokens=1024,
1308
    messages=[
1309
        {
1310
            "role": "user",
1311
            "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"
1312
        },
1313
        {
1314
            "role": "assistant",
1315
            "content": "The best answer is ("
1316
        }
1317
    ]
1318
)
1319

1320
# Model will continue from "The best answer is ("
1321
print(message.content[0].text)  # Should be "B) Helios" or similar
1322
```
1323

1324
### Temperature Control
1325

1326
```python
1327
# Lower temperature for factual/analytical responses
1328
factual_message = client.messages.create(
1329
    model="claude-3-5-sonnet-20241022",
1330
    max_tokens=1024,
1331
    temperature=0.2,
1332
    messages=[
1333
        {"role": "user", "content": "What is the capital of France?"}
1334
    ]
1335
)
1336

1337
# Higher temperature for creative responses
1338
creative_message = client.messages.create(
1339
    model="claude-3-5-sonnet-20241022",
1340
    max_tokens=1024,
1341
    temperature=0.9,
1342
    messages=[
1343
        {"role": "user", "content": "Write a creative poem about stars."}
1344
    ]
1345
)
1346
```
1347

1348
### Stop Sequences
1349

1350
```python
1351
message = client.messages.create(
1352
    model="claude-3-5-sonnet-20241022",
1353
    max_tokens=1024,
1354
    stop_sequences=["\n\nHuman:", "END"],
1355
    messages=[
1356
        {"role": "user", "content": "Write a list of items. End with the word END."}
1357
    ]
1358
)
1359

1360
print(f"Stop reason: {message.stop_reason}")
1361
if message.stop_sequence:
1362
    print(f"Stopped at: {message.stop_sequence}")
1363
```
1364