Page history
API usage primer for Claude
claude_api_primer
History
claude_api_primer Changed · +3 / -4 lines
from line 181
```python Python import anthropic import base64 - import httpx + import httpx2 # Option 1: Base64-encoded image image_url = "https://platform.claude.com/docs/images/vision-example.jpg" image_media_type = "image/jpeg" - image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8") + image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8") message = anthropic.Anthropic().messages.create( model="claude-opus-5",
from line 262
<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI - ant messages create \ - --transform content --format yaml <<'YAML' + ant messages create --transform content --format yaml <<'YAML' model: claude-opus-5 max_tokens: 16000 thinking:
claude_api_primer Changed · +8 / -8 lines
from line 21
### Basic request and response -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant messages create \ --model claude-opus-5 \
from line 66
The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don't necessarily need to actually originate from Claude. You can use synthetic `assistant` messages. -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant messages create <<'YAML' model: claude-opus-5
from line 105
Claude 4.6 and later models and Claude Mythos Preview do not support assistant message prefill; requests to those models must end with a user message. The examples below use a model that supports prefill. </Note> -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant messages create <<'YAML' model: claude-sonnet-4-5
from line 140
Claude can read both text and images in requests. Both `base64` and `url` source types are supported for images, along with the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types. -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"
from line 260
When thinking is on, Claude creates `thinking` content blocks where it outputs its internal reasoning. The API response includes `thinking` content blocks, followed by `text` content blocks. -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant messages create \ --transform content --format yaml <<'YAML'
from line 314
### Preserving thinking blocks -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI # First request: capture the assistant content array (thinking + tool_use # blocks, signatures intact) as compact JSON.
from line 448
On older models that use manual extended thinking (Claude 4, 4.5, and Sonnet 4.6 models), enable interleaved thinking by adding the beta header `interleaved-thinking-2025-05-14` to your API request: -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant beta:messages create --beta interleaved-thinking-2025-05-14 <<'YAML' model: claude-sonnet-4-6
from line 719
### Streaming with SDKs -<CodeGroup> +<CodeGroup exclude="shell:cURL, typescript, csharp, go, java, php, ruby"> ```bash CLI ant messages create --stream --format jsonl \ --model claude-opus-5 \
claude_api_primer First recorded · 815 lines, first recorded
# API usage primer for Claude ## Models ## Calling the API ### Basic request and response ### Multiple conversational turns ### Prefilling Claude's response ### Vision ## Thinking ### How thinking works ## Thinking with tool use ### Preserving thinking blocks ### Interleaved thinking ## Tool use ### Specifying client tools ### Best practices for tool definitions ## Controlling Claude's output ### Forcing tool use ### JSON output ### Chain of thought ### Parallel tool use ## Handling tool use and tool result content blocks ### Handling results from client tools ### Handling the `max_tokens` stop reason ### Handling the `pause_turn` stop reason ## Troubleshooting errors ### Tool execution error ### Invalid tool name ## Streaming messages ### Streaming with SDKs ### Event types ### Content block delta types #### Text delta #### Input JSON delta #### Thinking delta ### Basic streaming request example
The first capture of this source. The page was already there, and this is what it said.
---
title: API usage primer for Claude
url: https://platform.claude.com/docs/en/claude_api_primer
description: This guide is designed to give Claude the basics of using the Claude API. It gives explanation and examples of model IDs/the basic messages API, tool use, streaming, thinking, and nothing else.
---
# API usage primer for Claude
> This guide is designed to give Claude the basics of using the Claude API. It gives explanation and examples of model IDs/the basic messages API, tool use, streaming, thinking, and nothing else.
## Models
```text wrap
For complex agentic coding and enterprise work: Claude Opus 5: claude-opus-5
Previous Opus model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001
```
## Calling the API
### Basic request and response
<CodeGroup>
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 1024 \
--message '{"role": "user", "content": "Hello, Claude"}'
```
```python Python
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
```
</CodeGroup>
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}
```
### Multiple conversational turns
The Messages API is stateless, which means that you always send the full conversational history to the API. You can use this pattern to build up a conversation over time. Earlier conversational turns don't necessarily need to actually originate from Claude. You can use synthetic `assistant` messages.
<CodeGroup>
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
messages:
- role: user
content: Hello, Claude
- role: assistant
content: Hello!
- role: user
content: Can you describe LLMs to me?
YAML
```
```python Python
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message)
```
</CodeGroup>
### Prefilling Claude's response
You can prefill part of Claude's response in the last position of the input messages list. Use this technique to shape Claude's response. The following example uses `"max_tokens": 1` to get a single multiple choice answer from Claude.
<Note>
Claude 4.6 and later models and Claude Mythos Preview do not support assistant message prefill; requests to those models must end with a user message. The examples below use a model that supports prefill.
</Note>
<CodeGroup>
```bash CLI
ant messages create <<'YAML'
model: claude-sonnet-4-5
max_tokens: 1
messages:
- role: user
content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"
- role: assistant
content: "The answer is ("
YAML
```
```python Python
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message.content[0].text)
```
</CodeGroup>
### Vision
Claude can read both text and images in requests. Both `base64` and `url` source types are supported for images, along with the `image/jpeg`, `image/png`, `image/gif`, and `image/webp` media types.
<CodeGroup>
```bash CLI
IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"
# Option 1: Base64-encoded image (@ prefix auto-encodes binary files as base64)
curl -sSo vision-example.jpg "$IMAGE_URL"
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
messages:
- role: user
content:
- type: image
source:
type: base64
media_type: image/jpeg
data: "@./vision-example.jpg"
- type: text
text: What is in the above image?
YAML
# Option 2: URL-referenced image
ant messages create <<YAML
model: claude-opus-5
max_tokens: 1024
messages:
- role: user
content:
- type: image
source:
type: url
url: $IMAGE_URL
- type: text
text: What is in the above image?
YAML
```
```python Python
import anthropic
import base64
import httpx
# Option 1: Base64-encoded image
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(next(block.text for block in message.content if block.type == "text"))
# Option 2: URL-referenced image
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://platform.claude.com/docs/images/vision-example.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))
```
</CodeGroup>
## Thinking
Thinking can sometimes help Claude with very hard tasks. The current mechanism is [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {"type": "adaptive"}`): Claude decides when and how much to think, and you steer thinking depth with the [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter rather than a token budget. Adaptive thinking is supported on Claude 4.6 and later models and Claude Mythos Preview. On Claude 5 models and Claude Mythos Preview, thinking is on by default when the `thinking` parameter is omitted.
Temperature must be set to 1 (or left unset) whenever thinking is enabled, on all models. On Claude 4.7 and later models and Claude Mythos Preview, `temperature` is deprecated and only its default value is accepted, even when thinking is off.
Thinking is supported in the following models:
* Claude Opus 5 (claude-opus-5, adaptive thinking only, on by default)
* Claude Sonnet 5 (`claude-sonnet-5`, adaptive thinking only, on by default)
* Claude Opus 4.8 (claude-opus-4-8, adaptive thinking only)
* Claude Opus 4.7 (`claude-opus-4-7`, adaptive thinking only)
* Claude Opus 4.6 (`claude-opus-4-6`, adaptive or legacy manual thinking)
* Claude Sonnet 4.6 (`claude-sonnet-4-6`, adaptive or legacy manual thinking)
* Claude Opus 4.5 (`claude-opus-4-5-20251101`, legacy manual thinking only)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`, legacy manual thinking only)
* Claude Haiku 4.5 (`claude-haiku-4-5-20251001`, legacy manual thinking only)
<Note>
On Claude 4.7 and later models, manual extended thinking (`type: enabled` with a `budget_tokens` value) is not supported and returns a 400 error. Use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`type: adaptive`) instead.
</Note>
### How thinking works
When thinking is on, Claude creates `thinking` content blocks where it outputs its internal reasoning. The API response includes `thinking` content blocks, followed by `text` content blocks.
<CodeGroup>
```bash CLI
ant messages create \
--transform content --format yaml <<'YAML'
model: claude-opus-5
max_tokens: 16000
thinking:
type: adaptive
display: summarized
messages:
- role: user
content: Are there an infinite number of prime numbers such that n mod 4 == 3?
YAML
```
```python Python
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# The response contains summarized thinking blocks and text blocks
for block in response.content:
if block.type == "thinking":
print(f"\nThinking summary: {block.thinking}")
elif block.type == "text":
print(f"\nResponse: {block.text}")
Cut at 300 lines.