← Back to daily report

build-with-claude/working-with-messages.md

Changed on 2026-03-21 12:23:21 EST

+17 lines added
-19 lines removed
Visual Diff
# Using the Messages API¶

Practical patterns and examples for using the Messages API effectively¶

---¶

This guide covers common patterns for working with the Messages API, including basic requests, multi-turn conversations, prefill techniques, and vision capabilities. For complete API specifications, see the [Messages API reference](/docs/en/api/messages).¶

<Note>¶
This feature is eligible for [Zero Data Retention (ZDR)](/docs/en/build-with-claude/zero-data-retention). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.¶
</Note>¶

## Basic request and response¶

<CodeGroup>¶
```bash Shell¶
#!/bin/sh¶
curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "content-type: application/json" \¶
--data \¶
'{¶
"model": "claude-opus-4-6",¶
"max_tokens": 1024,¶
"messages": [¶
{"role": "user", "content": "Hello, Claude"}¶
]¶
}'¶
```¶

```python Python hidelines={1..2}
 import anthropic¶

message = anthropic.Anthropic().messages.create(¶
model="claude-opus-4-6",¶
max_tokens=1024,¶
messages=[{"role": "user", "content": "Hello, Claude"}],¶
)¶
print(message)¶
```¶

```typescript TypeScript hidelines={1..42}¶
import Anthropic from "@anthropic-ai/sdk";¶

const anthropic = new Anthropic();¶

const message = await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [{ role: "user", content: "Hello, Claude" }]¶
});¶
console.log(message);¶
```¶

```csharp C#¶
using System;¶
using System.Threading.Tasks;¶
using Anthropic;¶
using Anthropic.Models.Messages;¶

class Program¶
{¶
static async Task Main()¶
{¶
AnthropicClient client = new();¶

var parameters = new MessageCreateParams¶
{¶
Model = Model.ClaudeOpus4_6,¶
MaxTokens = 1024,¶
Messages = [new() { Role = Role.User, Content = "Hello, Claude" }]¶
};¶
var message = await client.Messages.Create(parameters);¶
Console.WriteLine(message);¶
}¶
}¶
```¶

```go Go hidelines={1..131,-1}¶
package main¶

import (¶
"context"¶
"fmt"¶
"log"¶

"github.com/anthropics/anthropic-sdk-go"¶
)¶

func main() {¶
client := anthropic.NewClient()¶

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{¶
Model: anthropic.ModelClaudeOpus4_6,¶
MaxTokens: 1024,¶
Messages: []anthropic.MessageParam{¶
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),¶
},¶
})¶
if err != nil {¶
log.Fatal(err)¶
}¶
fmt.Println(response)¶
}¶
```¶

```java Java hidelines={1..8,-12..}¶
import com.anthropic.client.AnthropicClient;¶
import com.anthropic.client.okhttp.AnthropicOkHttpClient;¶
import com.anthropic.models.messages.MessageCreateParams;¶
import com.anthropic.models.messages.Message;¶
import com.anthropic.models.messages.Model;¶

public class Main {¶
public static void main(String[] args) {¶
AnthropicClient client = AnthropicOkHttpClient.fromEnv();¶

MessageCreateParams params = MessageCreateParams.builder()¶
.model(Model.CLAUDE_OPUS_4_6)¶
.maxTokens(1024L)¶
.addUserMessage("Hello, Claude")¶
.build();¶

Message response = client.messages().create(params);¶
System.out.println(response);¶
}¶
}¶
```¶

```php PHP hidelines={1..4}
<?php¶

use Anthropic\Client;¶

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));¶

$message = $client->messages->create(¶
maxTokens: 1024,¶
messages: [['role' => 'user', 'content' => 'Hello, Claude']],¶
model: 'claude-opus-4-6',¶
);¶
echo $message->content[0]->text;¶
```¶

```ruby Ruby hidelines={1..2}
require "anthropic"¶

client = Anthropic::Client.new¶

message = client.messages.create(¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [¶
{ role: "user", content: "Hello, Claude" }¶
]¶
)¶
puts message¶
```¶
</CodeGroup>¶

```json JSON¶
{¶
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",¶
"type": "message",¶
"role": "assistant",¶
"content": [¶
{¶
"type": "text",¶
"text": "Hello!"¶
}¶
],¶
"model": "claude-opus-4-6",¶
"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 Shell¶
#!/bin/sh¶
curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "content-type: application/json" \¶
--data \¶
'{¶
"model": "claude-opus-4-6",¶
"max_tokens": 1024,¶
"messages": [¶
{"role": "user", "content": "Hello, Claude"},¶
{"role": "assistant", "content": "Hello!"},¶
{"role": "user", "content": "Can you describe LLMs to me?"}¶

]¶
}'¶
```¶

```python Python hidelines={1..2,-1}¶
import anthropic¶

message = anthropic.Anthropic().messages.create(¶
model="claude-opus-4-6",¶
max_tokens=1024,¶
messages=[¶
{"role": "user", "content": "Hello, Claude"},¶
{"role": "assistant", "content": "Hello!"},¶
{"role": "user", "content": "Can you describe LLMs to me?"},¶
],¶
)¶
print(message)¶
```¶

```typescript TypeScript hidelines={1..42}¶
import Anthropic from "@anthropic-ai/sdk";¶

const anthropic = new Anthropic();¶

await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [¶
{ role: "user", content: "Hello, Claude" },¶
{ role: "assistant", content: "Hello!" },¶
{ role: "user", content: "Can you describe LLMs to me?" }¶
]¶
});¶
```¶

```csharp C#¶
using System;¶
using System.Threading.Tasks;¶
using Anthropic;¶
using Anthropic.Models.Messages;¶

class Program¶
{¶
static async Task Main(string[] args)¶
{¶
AnthropicClient client = new();¶

var parameters = new MessageCreateParams¶
{¶
Model = Model.ClaudeOpus4_6,¶
MaxTokens = 1024,¶
Messages =¶
[¶
new() { Role = Role.User, Content = "Hello, Claude" },¶
new() { Role = Role.Assistant, Content = "Hello!" },¶
new() { Role = Role.User, Content = "Can you describe LLMs to me?" }¶
]¶
};¶

var message = await client.Messages.Create(parameters);¶
Console.WriteLine(message);¶
}¶
}¶
```¶

```go Go hidelines={1..131,-1}¶
package main¶

import (¶
"context"¶
"fmt"¶
"log"¶

"github.com/anthropics/anthropic-sdk-go"¶
)¶

func main() {¶
client := anthropic.NewClient()¶

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{¶
Model: anthropic.ModelClaudeOpus4_6,¶
MaxTokens: 1024,¶
Messages: []anthropic.MessageParam{¶
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),¶
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Hello!")),¶
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you describe LLMs to me?")),¶
},¶
})¶
if err != nil {¶
log.Fatal(err)¶
}¶
fmt.Println(response)¶
}¶
```¶

```java Java hidelines={1..8,-12..}¶
import com.anthropic.client.AnthropicClient;¶
import com.anthropic.client.okhttp.AnthropicOkHttpClient;¶
import com.anthropic.models.messages.MessageCreateParams;¶
import com.anthropic.models.messages.Message;¶
import com.anthropic.models.messages.Model;¶

public class MultiTurnConversation {¶
public static void main(String[] args) {¶
AnthropicClient client = AnthropicOkHttpClient.fromEnv();¶

MessageCreateParams params = MessageCreateParams.builder()¶
.model(Model.CLAUDE_OPUS_4_6)¶
.maxTokens(1024L)¶
.addUserMessage("Hello, Claude")¶
.addAssistantMessage("Hello!")¶
.addUserMessage("Can you describe LLMs to me?")¶
.build();¶

Message response = client.messages().create(params);¶
System.out.println(response);¶
}¶
}¶
```¶

```php PHP hidelines={1..64}¶
<?php¶

use Anthropic\Client;¶

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));¶

$message = $client->messages->create(¶
maxTokens: 1024,¶
messages: [¶
['role' => 'user', 'content' => 'Hello, Claude'],¶
['role' => 'assistant', 'content' => 'Hello!'],¶
['role' => 'user', 'content' => 'Can you describe LLMs to me?'],¶
],¶
model: 'claude-opus-4-6',¶
);¶

echo $message->content[0]->text;¶
```¶

```ruby Ruby hidelines={1..2}
require "anthropic"¶

client = Anthropic::Client.new¶

message = client.messages.create(¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [¶
{ role: "user", content: "Hello, Claude" },¶
{ role: "assistant", content: "Hello!" },¶
{ role: "user", content: "Can you describe LLMs to me?" }¶
]¶
)¶
puts message¶
```¶
</CodeGroup>¶

```json JSON¶
{¶
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",¶
"type": "message",¶
"role": "assistant",¶
"content": [¶
{¶
"type": "text",¶
"text": "Sure, I'd be happy to provide..."¶
}¶
],¶
"stop_reason": "end_turn",¶
"stop_sequence": null,¶
"usage": {¶
"input_tokens": 30,¶
"output_tokens": 309¶
}¶
}¶
```¶

## Putting words in Claude's mouth¶

You can pre-fill part of Claude's response in the last position of the input messages list. This can be used to shape Claude's response. The example below uses `"max_tokens": 1` to get a single multiple choice answer from Claude.¶

<CodeGroup>¶
```bash Shell¶
#!/bin/sh¶
curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "content-type: application/json" \¶
--data \¶
'{¶
"model": "claude-opus-4-6",¶
"max_tokens": 1,¶
"messages": [¶
{"role": "user", "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"},¶
{"role": "assistant", "content": "The answer is ("}¶
]¶
}'¶
```¶

```python Python hidelines={1..2,-1}¶
import anthropic¶

message = anthropic.Anthropic().messages.create(¶
model="claude-opus-4-6",¶
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)¶
```¶

```typescript TypeScript hidelines={1..42}¶
import Anthropic from "@anthropic-ai/sdk";¶

const anthropic = new Anthropic();¶

const message = await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
max_tokens: 1,¶
messages: [¶
{¶
role: "user",¶
content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"¶
},¶
{ role: "assistant", content: "The answer is (" }¶
]¶
});¶
console.log(message);¶
```¶

```csharp C#¶
using System;¶
using System.Threading.Tasks;¶
using Anthropic;¶
using Anthropic.Models.Messages;¶

class Program¶
{¶
static async Task Main(string[] args)¶
{¶
AnthropicClient client = new();¶

var parameters = new MessageCreateParams¶
{¶
Model = Model.ClaudeOpus4_6,¶
MaxTokens = 1,¶
Messages = [¶
new() { Role = Role.User, Content = "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae" },¶
new() { Role = Role.Assistant, Content = "The answer is (" }¶
]¶
};¶

var message = await client.Messages.Create(parameters);¶
Console.WriteLine(message);¶
}¶
}¶
```¶

```go Go hidelines={1..131,-1}¶
package main¶

import (¶
"context"¶
"fmt"¶
"log"¶

"github.com/anthropics/anthropic-sdk-go"¶
)¶

func main() {¶
client := anthropic.NewClient()¶

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{¶
Model: anthropic.ModelClaudeOpus4_6,¶
MaxTokens: 1,¶
Messages: []anthropic.MessageParam{¶
anthropic.NewUserMessage(anthropic.NewTextBlock("What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae")),¶
anthropic.NewAssistantMessage(anthropic.NewTextBlock("The answer is (")),¶
},¶
})¶
if err != nil {¶
log.Fatal(err)¶
}¶
fmt.Println(response)¶
}¶
```¶

```java Java hidelines={1..8,-12..}¶
import com.anthropic.client.AnthropicClient;¶
import com.anthropic.client.okhttp.AnthropicOkHttpClient;¶
import com.anthropic.models.messages.MessageCreateParams;¶
import com.anthropic.models.messages.Message;¶
import com.anthropic.models.messages.Model;¶

public class PrefillExample {¶
public static void main(String[] args) {¶
AnthropicClient client = AnthropicOkHttpClient.fromEnv();¶

MessageCreateParams params = MessageCreateParams.builder()¶
.model(Model.CLAUDE_OPUS_4_6)¶
.maxTokens(1L)¶
.addUserMessage("What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae")¶
.addAssistantMessage("The answer is (")¶
.build();¶

Message response = client.messages().create(params);¶
System.out.println(response);¶
}¶
}¶
```¶

```php PHP hidelines={1..64}¶
<?php¶

use Anthropic\Client;¶

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));¶

$message = $client->messages->create(¶
maxTokens: 1,¶
messages: [¶
['role' => 'user', 'content' => 'What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae'],¶
['role' => 'assistant', 'content' => 'The answer is ('],¶
],¶
model: 'claude-opus-4-6',¶
);¶
echo $message->content[0]->text;¶
```¶

```ruby Ruby hidelines={1..2}
require "anthropic"¶

client = Anthropic::Client.new¶

message = client.messages.create(¶
model: "claude-opus-4-6",¶
max_tokens: 1,¶
messages: [¶
{¶
role: "user",¶
content: "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"¶
},¶
{ role: "assistant", content: "The answer is (" }¶
]¶
)¶
puts message¶
```¶
</CodeGroup>¶

```json JSON¶
{¶
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",¶
"type": "message",¶
"role": "assistant",¶
"content": [¶
{¶
"type": "text",¶
"text": "C"¶
}¶
],¶
"model": "claude-opus-4-6",¶
"stop_reason": "max_tokens",¶
"stop_sequence": null,¶
"usage": {¶
"input_tokens": 42,¶
"output_tokens": 1¶
}¶
}¶
```¶

<Warning>¶
Prefilling is deprecated and not supported on Claude Opus 4.6, Claude Sonnet 4.6, and Claude Sonnet 4.5. Use [structured outputs](/docs/en/build-with-claude/structured-outputs) or system prompt instructions instead.¶
</Warning>¶

## Vision¶

Claude can read both text and images in requests. Images can be supplied using the `base64`, `url`, or `file` source types. The `file` source type references an image uploaded through the [Files API](/docs/en/build-with-claude/files). Supported media types are `image/jpeg`, `image/png`, `image/gif`, and `image/webp`. See the [vision guide](/docs/en/build-with-claude/vision) for more details.¶

<CodeGroup>¶
```bash Shell¶
#!/bin/sh¶

# Option 1: Base64-encoded image¶
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶
IMAGE_MEDIA_TYPE="image/jpeg"¶
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64 | tr -d '\n')¶

curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "content-type: application/json" \¶
--data \¶
'{¶
"model": "claude-opus-4-6",¶
"max_tokens": 1024,¶
"messages": [¶
{"role": "user", "content": [¶
{"type": "image", "source": {¶
"type": "base64",¶
"media_type": "'$IMAGE_MEDIA_TYPE'",¶
"data": "'$IMAGE_BASE64'"¶
}},¶
{"type": "text", "text": "What is in the above image?"}¶
]}¶
]¶
}'¶

# Option 2: URL-referenced image¶
curl https://api.anthropic.com/v1/messages \¶
--header "x-api-key: $ANTHROPIC_API_KEY" \¶
--header "anthropic-version: 2023-06-01" \¶
--header "content-type: application/json" \¶
--data \¶
'{¶
"model": "claude-opus-4-6",¶
"max_tokens": 1024,¶
"messages": [¶
{"role": "user", "content": [¶
{"type": "image", "source": {¶
"type": "url",¶
"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶
}},¶
{"type": "text", "text": "What is in the above image?"}¶
]}¶
]¶
}'¶
```¶


```python Python nocheck hidelines={-1}¶
import anthropic¶
import base64¶
import httpx¶

# Option 1: Base64-encoded image¶
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.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-4-6",¶
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(message)¶

# Option 2: URL-referenced image¶
message_from_url = anthropic.Anthropic().messages.create(¶
model="claude-opus-4-6",¶
max_tokens=1024,¶
messages=[¶
{¶
"role": "user",¶
"content": [¶
{¶
"type": "image",¶
"source": {¶
"type": "url",¶
"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",¶
},¶
},¶
{"type": "text", "text": "What is in the above image?"},¶
],¶
}¶
],¶
)¶
print(message_from_url)¶
```¶


```typescript TypeScript nocheck hidelines={1..42}¶
import Anthropic from "@anthropic-ai/sdk";¶

const anthropic = new Anthropic();¶

// Option 1: Base64-encoded image¶
const image_url =¶
"https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg";¶
const image_media_type = "image/jpeg";¶
const image_array_buffer = await (await fetch(image_url)).arrayBuffer();¶
const image_data = Buffer.from(image_array_buffer).toString("base64");¶

const message = await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
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?"¶
}¶
]¶
}¶
]¶
});¶
console.log(message);¶

// Option 2: URL-referenced image¶
const messageFromUrl = await anthropic.messages.create({¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [¶
{¶
role: "user",¶
content: [¶
{¶
type: "image",¶
source: {¶
type: "url",¶
url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶
}¶
},¶
{¶
type: "text",¶
text: "What is in the above image?"¶
}¶
]¶
}¶
]¶
});¶
console.log(messageFromUrl);¶
```¶


```csharp C# nocheck¶
using System;¶
using System.Collections.Generic;¶
using System.Net.Http;¶
using System.Threading.Tasks;¶
using Anthropic;¶
using Anthropic.Models.Messages;¶

public class Program¶
{¶
public static async Task Main(string[] args)¶
{¶
AnthropicClient client = new();¶

// Option 1: Base64-encoded image¶
string imageUrl = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg";¶

using HttpClient httpClient = new();¶
byte[] imageBytes = await httpClient.GetByteArrayAsync(imageUrl);¶
string imageData = Convert.ToBase64String(imageBytes);¶

var parameters = new MessageCreateParams¶
{¶
Model = Model.ClaudeOpus4_6,¶
MaxTokens = 1024,¶
Messages =¶
[¶
new()¶
{¶
Role = Role.User,¶
Content = new MessageParamContent(new List<ContentBlockParam>¶
{¶
new ContentBlockParam(new ImageBlockParam(¶
new ImageBlockParamSource(new Base64ImageSource()¶
{¶
Data = imageData,¶
MediaType = MediaType.ImageJpeg,¶
})¶
)),¶
new ContentBlockParam(new TextBlockParam("What is in the above image?")),¶
}),¶
}¶
]¶
};¶

var message = await client.Messages.Create(parameters);¶
Console.WriteLine(message);¶

// Option 2: URL-referenced image¶
var parametersFromUrl = new MessageCreateParams¶
{¶
Model = Model.ClaudeOpus4_6,¶
MaxTokens = 1024,¶
Messages =¶
[¶
new()¶
{¶
Role = Role.User,¶
Content = new MessageParamContent(new List<ContentBlockParam>¶
{¶
new ContentBlockParam(new ImageBlockParam(¶
new ImageBlockParamSource(new UrlImageSource()¶
{¶
Url = new Uri("https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"),¶
})¶
)),¶
new ContentBlockParam(new TextBlockParam("What is in the above image?")),¶
}),¶
}¶
]¶
};¶

var messageFromUrl = await client.Messages.Create(parametersFromUrl);¶
Console.WriteLine(messageFromUrl);¶
}¶
}¶
```¶


```go Go nocheck hidelines={1..16,-1}¶
package main¶

import (¶
"context"¶
"encoding/base64"¶
"fmt"¶
"io"¶
"log"¶
"net/http"¶

"github.com/anthropics/anthropic-sdk-go"¶
)¶

func main() {¶
client := anthropic.NewClient()¶

// Option 1: Base64-encoded image¶
imageURL := "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶

req, err := http.NewRequest("GET", imageURL, nil)¶
if err != nil {¶
log.Fatal(err)¶
}¶
req.Header.Set("User-Agent", "AnthropicDocsBot/1.0")¶

resp, err := http.DefaultClient.Do(req)¶
if err != nil {¶
log.Fatal(err)¶
}¶
defer resp.Body.Close()¶

imageBytes, err := io.ReadAll(resp.Body)¶
if err != nil {¶
log.Fatal(err)¶
}¶
imageData := base64.StdEncoding.EncodeToString(imageBytes)¶

message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{¶
Model: anthropic.ModelClaudeOpus4_6,¶
MaxTokens: 1024,¶
Messages: []anthropic.MessageParam{¶
anthropic.NewUserMessage(¶
anthropic.NewImageBlockBase64("image/jpeg", imageData),¶
anthropic.NewTextBlock("What is in the above image?"),¶
),¶
},¶
})¶
if err != nil {¶
log.Fatal(err)¶
}¶
fmt.Println(message)¶

// Option 2: URL-referenced image¶
messageFromURL, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{¶
Model: anthropic.ModelClaudeOpus4_6,¶
MaxTokens: 1024,¶
Messages: []anthropic.MessageParam{¶
anthropic.NewUserMessage(¶
anthropic.NewImageBlock(anthropic.URLImageSourceParam{¶
URL: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",¶
}),¶
anthropic.NewTextBlock("What is in the above image?"),¶
),¶
},¶
})¶
if err != nil {¶
log.Fatal(err)¶
}¶
fmt.Println(messageFromURL)¶
}¶
```¶


```java Java nocheck hidelines={1..12,-12..}¶
import com.anthropic.client.AnthropicClient;¶
import com.anthropic.client.okhttp.AnthropicOkHttpClient;¶
import com.anthropic.models.messages.*;¶
import java.net.URI;¶
import java.net.http.HttpClient;¶
import java.net.http.HttpRequest;¶
import java.net.http.HttpResponse;¶
import java.util.Base64;¶
import java.util.List;¶

public class VisionExample {¶
public static void main(String[] args) throws Exception {¶
AnthropicClient client = AnthropicOkHttpClient.fromEnv();¶

// Option 1: Base64-encoded image¶
String imageUrl = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg";¶

HttpClient httpClient = HttpClient.newHttpClient();¶
HttpRequest request = HttpRequest.newBuilder().uri(URI.create(imageUrl)).build();¶
HttpResponse<byte[]> response = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray());¶
String imageData = Base64.getEncoder().encodeToString(response.body());¶

List<ContentBlockParam> base64Content = List.of(¶
ContentBlockParam.ofImage(¶
ImageBlockParam.builder()¶
.source(Base64ImageSource.builder()¶
.data(imageData)¶
.mediaType(Base64ImageSource.MediaType.IMAGE_JPEG)¶
.build())¶
.build()),¶
ContentBlockParam.ofText(¶
TextBlockParam.builder()¶
.text("What is in the above image?")¶
.build())¶
);¶

Message message = client.messages().create(¶
MessageCreateParams.builder()¶
.model(Model.CLAUDE_OPUS_4_6)¶
.maxTokens(1024L)¶
.addUserMessageOfBlockParams(base64Content)¶
.build());¶
System.out.println(message);¶

// Option 2: URL-referenced image¶
List<ContentBlockParam> urlContent = List.of(¶
ContentBlockParam.ofImage(¶
ImageBlockParam.builder()¶
.source(UrlImageSource.builder()¶
.url("https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg")¶
.build())¶
.build()),¶
ContentBlockParam.ofText(¶
TextBlockParam.builder()¶
.text("What is in the above image?")¶
.build())¶
);¶

Message messageFromUrl = client.messages().create(¶
MessageCreateParams.builder()¶
.model(Model.CLAUDE_OPUS_4_6)¶
.maxTokens(1024L)¶
.addUserMessageOfBlockParams(urlContent)¶
.build());¶
System.out.println(messageFromUrl);¶
}¶
}¶
```¶


```php PHP hidelines={1..64} nocheck¶
<?php¶

use Anthropic\Client;¶

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));¶

// Option 1: Base64-encoded image¶
$image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg";¶
$image_media_type = "image/jpeg";¶
$image_data = base64_encode(file_get_contents($image_url));¶

$message = $client->messages->create(¶
maxTokens: 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?',¶
],¶
],¶
],¶
],¶
model: 'claude-opus-4-6',¶
);¶
echo $message;¶

// Option 2: URL-referenced image¶
$message_from_url = $client->messages->create(¶
maxTokens: 1024,¶
messages: [¶
[¶
'role' => 'user',¶
'content' => [¶
[¶
'type' => 'image',¶
'source' => [¶
'type' => 'url',¶
'url' => 'https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg',¶
],¶
],¶
[¶
'type' => 'text',¶
'text' => 'What is in the above image?',¶
],¶
],¶
],¶
],¶
model: 'claude-opus-4-6',¶
);¶
echo $message_from_url;¶
```¶


 ```ruby Ruby nocheck hidelines={1}
require "anthropic"¶
require "base64"¶
require "net/http"¶

client = Anthropic::Client.new¶

# Option 1: Base64-encoded image¶
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶
image_media_type = "image/jpeg"¶
image_data = Base64.strict_encode64(Net::HTTP.get(URI(image_url)))¶

message = client.messages.create(¶
model: "claude-opus-4-6",¶
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?"¶
}¶
]¶
}¶
]¶
)¶
puts message¶

# Option 2: URL-referenced image¶
message_from_url = client.messages.create(¶
model: "claude-opus-4-6",¶
max_tokens: 1024,¶
messages: [¶
{¶
role: "user",¶
content: [¶
{¶
type: "image",¶
source: {¶
type: "url",¶
url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"¶
}¶
},¶
{¶
type: "text",¶
text: "What is in the above image?"¶
}¶
]¶
}¶
]¶
)¶
puts message_from_url¶
```¶
</CodeGroup>¶

```json JSON¶
{¶
"id": "msg_01EcyWo6m4hyW8KHs2y2pei5",¶
"type": "message",¶
"role": "assistant",¶
"content": [¶
{¶
"type": "text",¶
"text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."¶
}¶
],¶
"model": "claude-opus-4-6",¶
"stop_reason": "end_turn",¶
"stop_sequence": null,¶
"usage": {¶
"input_tokens": 1551,¶
"output_tokens": 71¶
}¶
}¶
```¶

## Tool use and computer use¶

See the [tool use guide](/docs/en/agents-and-tools/tool-use/overview) for examples of how to use tools with the Messages API.¶
See the [computer use guide](/docs/en/agents-and-tools/tool-use/computer-use-tool) for examples of how to control desktop computer environments with the Messages API.¶
For guaranteed JSON output, see [Structured Outputs](/docs/en/build-with-claude/structured-outputs).

Unified Diff

--- a/build-with-claude/working-with-messages.md
+++ b/build-with-claude/working-with-messages.md
@@ -29,7 +29,7 @@
   }'
   ```
 
-  ```python Python
+  ```python Python hidelines={1..2}
   import anthropic
 
   message = anthropic.Anthropic().messages.create(
@@ -40,7 +40,7 @@
   print(message)
   ```
 
-  ```typescript TypeScript hidelines={1..4}
+  ```typescript TypeScript hidelines={1..2}
   import Anthropic from "@anthropic-ai/sdk";
 
   const anthropic = new Anthropic();
@@ -77,7 +77,7 @@
   }
   ```
 
-  ```go Go hidelines={1..13,-1}
+  ```go Go hidelines={1..11,-1}
   package main
 
   import (
@@ -105,7 +105,7 @@
   }
   ```
 
-  ```java Java hidelines={1..8,-1}
+  ```java Java hidelines={1..8,-2..}
   import com.anthropic.client.AnthropicClient;
   import com.anthropic.client.okhttp.AnthropicOkHttpClient;
   import com.anthropic.models.messages.MessageCreateParams;
@@ -128,7 +128,7 @@
   }
   ```
 
-  ```php PHP
+  ```php PHP hidelines={1..4}
   <?php
 
   use Anthropic\Client;
@@ -143,7 +143,7 @@
   echo $message->content[0]->text;
   ```
 
-  ```ruby Ruby
+  ```ruby Ruby hidelines={1..2}
   require "anthropic"
 
   client = Anthropic::Client.new
@@ -204,7 +204,7 @@
 }'
 ```
 
-```python Python hidelines={1..2,-1}
+```python Python hidelines={1..2}
 import anthropic
 
 message = anthropic.Anthropic().messages.create(
@@ -219,7 +219,7 @@
 print(message)
 ```
 
-```typescript TypeScript hidelines={1..4}
+```typescript TypeScript hidelines={1..2}
 import Anthropic from "@anthropic-ai/sdk";
 
 const anthropic = new Anthropic();
@@ -265,7 +265,7 @@
 }
 ```
 
-```go Go hidelines={1..13,-1}
+```go Go hidelines={1..11,-1}
 package main
 
 import (
@@ -295,7 +295,7 @@
 }
 ```
 
-```java Java hidelines={1..8,-1}
+```java Java hidelines={1..8,-2..}
 import com.anthropic.client.AnthropicClient;
 import com.anthropic.client.okhttp.AnthropicOkHttpClient;
 import com.anthropic.models.messages.MessageCreateParams;
@@ -320,7 +320,7 @@
 }
 ```
 
-```php PHP hidelines={1..6}
+```php PHP hidelines={1..4}
 <?php
 
 use Anthropic\Client;
@@ -340,7 +340,7 @@
 echo $message->content[0]->text;
 ```
 
-```ruby Ruby
+```ruby Ruby hidelines={1..2}
 require "anthropic"
 
 client = Anthropic::Client.new
@@ -400,7 +400,7 @@
   }'
   ```
 
-  ```python Python hidelines={1..2,-1}
+  ```python Python hidelines={1..2}
   import anthropic
 
   message = anthropic.Anthropic().messages.create(
@@ -417,7 +417,7 @@
   print(message)
   ```
 
-  ```typescript TypeScript hidelines={1..4}
+  ```typescript TypeScript hidelines={1..2}
   import Anthropic from "@anthropic-ai/sdk";
 
   const anthropic = new Anthropic();
@@ -464,7 +464,7 @@
   }
   ```
 
-  ```go Go hidelines={1..13,-1}
+  ```go Go hidelines={1..11,-1}
   package main
 
   import (
@@ -493,7 +493,7 @@
   }
   ```
 
-  ```java Java hidelines={1..8,-1}
+  ```java Java hidelines={1..8,-2..}
   import com.anthropic.client.AnthropicClient;
   import com.anthropic.client.okhttp.AnthropicOkHttpClient;
   import com.anthropic.models.messages.MessageCreateParams;
@@ -517,7 +517,7 @@
   }
   ```
 
-  ```php PHP hidelines={1..6}
+  ```php PHP hidelines={1..4}
   <?php
 
   use Anthropic\Client;
@@ -535,7 +535,7 @@
   echo $message->content[0]->text;
   ```
 
-  ```ruby Ruby
+  ```ruby Ruby hidelines={1..2}
   require "anthropic"
 
   client = Anthropic::Client.new
@@ -635,7 +635,7 @@
   ```
 
   
-  ```python Python nocheck hidelines={-1}
+  ```python Python nocheck hidelines={1}
   import anthropic
   import base64
   import httpx
@@ -691,7 +691,7 @@
   ```
 
   
-  ```typescript TypeScript nocheck hidelines={1..4}
+  ```typescript TypeScript nocheck hidelines={1..2}
   import Anthropic from "@anthropic-ai/sdk";
 
   const anthropic = new Anthropic();
@@ -908,7 +908,7 @@
   ```
 
   
-  ```java Java nocheck hidelines={1..12,-1}
+  ```java Java nocheck hidelines={1..12,-2..}
   import com.anthropic.client.AnthropicClient;
   import com.anthropic.client.okhttp.AnthropicOkHttpClient;
   import com.anthropic.models.messages.*;
@@ -979,7 +979,7 @@
   ```
 
   
-  ```php PHP hidelines={1..6} nocheck
+  ```php PHP hidelines={1..4} nocheck
   <?php
 
   use Anthropic\Client;
@@ -1043,7 +1043,7 @@
   ```
 
   
-  ```ruby Ruby nocheck
+  ```ruby Ruby nocheck hidelines={1}
   require "anthropic"
   require "base64"
   require "net/http"