使用 Messages API · LHQ 的网络日志

Anthropic 提供两种使用 Claude 进行构建的方式，每种方式适用于不同的使用场景：

	Messages API	Claude Managed Agents
它是什么	直接的模型提示访问	预构建、可配置的智能体框架，运行在托管基础设施中
最适合	自定义智能体循环和细粒度控制	长时间运行的任务和异步工作

本指南介绍使用 Messages API 的常见模式，包括基本请求、多轮对话、预填充技术和视觉功能。有关完整的 API 规范，请参阅 Messages API 参考。如需了解托管的 agent harness，请参阅 Claude Managed Agents 概述。

基本请求和响应

注意

Claude 4.7 及更高版本的模型以及 Claude Mythos Preview，以及从 API 版本 2026-10-21 开始的所有模型不支持 temperature、top_p 和 top_k 采样参数。将它们设置为非默认值会返回 400 错误，而从 2026-10-21 开始，设置任何值都会返回该错误。请在请求负载中省略这些参数，改用提示来引导模型的行为。请参阅迁移指南。

cURL

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'

CLI

ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

Python

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

TypeScript

const anthropic = new Anthropic();

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

AnthropicClient client = new();

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

client := anthropic.NewClient()

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

Java

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

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

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

PHP

$client = new Client();

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
    model: Model::CLAUDE_OPUS_5_5,
);
echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;

Ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Hello, Claude" }
  ]
)
puts message

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

在所有模型上，拒绝响应（stop_reason: "refusal"）还包含一个 stop_details 对象，用于标识触发拒绝的策略类别。有关字段参考和示例处理代码，请参阅处理停止原因。

多轮对话

Messages API 是无状态的，这意味着您始终需要将完整的对话历史发送给 API。您可以使用这种模式随时间逐步构建对话。较早的对话轮次不一定实际来自 Claude。您可以使用合成的 assistant 消息。

cURL

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"},
      {"role": "assistant", "content": "Hello!"},
      {"role": "user", "content": "Can you describe LLMs to me?"}

    ]
  }'

CLI

ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}' \
  --message '{role: assistant, content: "Hello!"}' \
  --message '{role: user, content: "Can you describe LLMs to me?"}'

Python

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-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)

TypeScript

const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Hello, Claude" },
    { role: "assistant", content: "Hello!" },
    { role: "user", content: "Can you describe LLMs to me?" }
  ]
});
console.log(message);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 1024,
    Messages =
    [
        new UserMessageParam { Content = "Hello, Claude" },
        new AssistantMessageParam { Content = "Hello!" },
        new UserMessageParam { Content = "Can you describe LLMs to me?" }
    ]
};

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

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	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

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_5_5)
    .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

$client = new Client();

$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: Model::CLAUDE_OPUS_5_5,
);

echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;

Ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 1024,
  messages: [
    { role: "user", content: "Hello, Claude" },
    { role: "assistant", content: "Hello!" },
    { role: "user", content: "Can you describe LLMs to me?" }
  ]
)
puts message

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

消息中的 system 角色

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，您可以在用户轮次之后包含 "role": "system" 的消息（需遵守放置规则），以便在对话中途添加新的系统指令。携带内容的 system 消息不能作为 messages 中的第一个条目。对于从一开始就适用的指令，请使用顶层 system 字段。

对话中途的系统消息与顶层 system 字段具有相同的权威性，但由于它被追加到消息历史的末尾，因此不会使其之前的任何已缓存前缀失效。对于应从第一轮就开始适用的指令，请使用顶层 system 字段；对于仅在之后才变得相关的指令，请使用对话中途的系统消息。

有关完整指南，包括如何将其与提示缓存结合使用，请参阅对话中途的系统消息。

预填充 Claude 的响应

您可以在输入消息列表的最后位置预填充 Claude 响应的一部分。使用此技术来塑造 Claude 的响应。以下示例使用 "max_tokens": 1 从 Claude 获取单个多项选择答案。

警告

Claude 4.6 及更高版本的模型和 Claude Mythos Preview 不支持预填充。对这些模型使用预填充的请求会返回 400 错误。请改为在支持的模型上使用结构化输出，或使用系统提示指令。有关迁移模式，请参阅迁移指南。

cURL

#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "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 ("}
    ]
  }'

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

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)

TypeScript

const anthropic = new Anthropic();

const message = await 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 (" }
  ]
});
console.log(message);

AnthropicClient client = new();

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

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

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeSonnet4_5,
	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

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_SONNET_4_5)
    .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

$client = new Client();

$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-sonnet-4-5',
);
echo $message->content[0]->text;

Ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: Anthropic::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 (" }
  ]
)
puts message

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

视觉

Claude 可以读取请求中的文本和图像。您可以使用 base64、url 或 file 源类型提供图像。file 源类型引用通过 Files API 上传的图像。支持的媒体类型为 image/jpeg、image/png、image/gif 和 image/webp。有关更多详细信息，请参阅视觉指南。

cURL

#!/bin/sh

# 选项 1：base64 编码的图像
IMAGE_BASE64=$(curl "https://platform.claude.com/docs/images/vision-example.jpg" | base64 | tr -d '\n')

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": [
      {"type": "image", "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "$IMAGE_BASE64"
      }},
      {"type": "text", "text": "What is in the above image?"}
    ]}
  ]
}
EOF

# 选项 2：通过 URL 引用的图像
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-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?"}
      ]}
    ]
  }'

CLI

# 选项 1：base64 编码的图像（CLI 会自动编码二进制 @file 引用）
curl -s "https://platform.claude.com/docs/images/vision-example.jpg" \
  -o ./vision-example.jpg

ant messages create <<'YAML'
model: claude-opus-5-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

# 选项 2：通过 URL 引用的图像
ant messages create <<'YAML'
model: claude-opus-5-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?
YAML

Python

import base64
import httpx2

# 选项 1：base64 编码的图像
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-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(message)

# 选项 2：通过 URL 引用的图像
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-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(message_from_url)

TypeScript

const anthropic = new Anthropic();

// 选项 1：base64 编码的图像
const imageUrl = "https://platform.claude.com/docs/images/vision-example.jpg";
const imageMediaType = "image/jpeg";
const imageArrayBuffer = await (await fetch(imageUrl)).arrayBuffer();
const imageData = Buffer.from(imageArrayBuffer).toString("base64");

const message = await anthropic.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: imageMediaType,
            data: imageData
          }
        },
        {
          type: "text",
          text: "What is in the above image?"
        }
      ]
    }
  ]
});
console.log(message);

// 选项 2：通过 URL 引用的图像
const messageFromUrl = await anthropic.messages.create({
  model: "claude-opus-5-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?"
        }
      ]
    }
  ]
});
console.log(messageFromUrl);

using System.Collections.Generic;
using System.Net.Http;
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

// 选项 1：base64 编码的图像
string imageUrl = "https://platform.claude.com/docs/images/vision-example.jpg";

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

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 1024,
    Messages =
    [
        new UserMessageParam
        {
            Content = 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);

// 选项 2：通过 URL 引用的图像
var parametersFromUrl = new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 1024,
    Messages =
    [
        new UserMessageParam
        {
            Content = new List<ContentBlockParam>
            {
                new ContentBlockParam(new ImageBlockParam(
                    new ImageBlockParamSource(new UrlImageSource()
                    {
                        Url = "https://platform.claude.com/docs/images/vision-example.jpg",
                    })
                )),
                new ContentBlockParam(new TextBlockParam("What is in the above image?")),
            },
        }
    ]
};

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

client := anthropic.NewClient()

// 选项 1：base64 编码的图像
imageURL := "https://platform.claude.com/docs/images/vision-example.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.ModelClaudeOpus5_5,
	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)

// 选项 2：通过 URL 引用的图像
messageFromURL, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(
			anthropic.NewImageBlock(anthropic.URLImageSourceParam{
				URL: "https://platform.claude.com/docs/images/vision-example.jpg",
			}),
			anthropic.NewTextBlock("What is in the above image?"),
		),
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(messageFromURL)

Java

AnthropicClient client = AnthropicOkHttpClient.fromEnv();

// 选项 1：base64 编码的图像
String imageUrl = "https://platform.claude.com/docs/images/vision-example.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_5_5)
        .maxTokens(1024L)
        .addUserMessageOfContentBlockParams(base64Content)
        .build());
System.out.println(message);

// 选项 2：通过 URL 引用的图像
List<ContentBlockParam> urlContent = List.of(
    ContentBlockParam.ofImage(
        ImageBlockParam.builder()
            .source(UrlImageSource.builder()
                .url("https://platform.claude.com/docs/images/vision-example.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_5_5)
        .maxTokens(1024L)
        .addUserMessageOfContentBlockParams(urlContent)
        .build());
System.out.println(messageFromUrl);

PHP

$client = new Client();

// 选项 1：base64 编码的图像
$image_url = 'https://platform.claude.com/docs/images/vision-example.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-5-5',
);
echo $message;

// 选项 2：通过 URL 引用的图像
$message_from_url = $client->messages->create(
    maxTokens: 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?',
                ],
            ],
        ],
    ],
    model: 'claude-opus-5-5',
);
echo $message_from_url;

Ruby

require "base64"
require "net/http"

client = Anthropic::Client.new

# 选项 1：base64 编码的图像
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = Base64.strict_encode64(Net::HTTP.get(URI(image_url)))

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

# 选项 2：通过 URL 引用的图像
message_from_url = client.messages.create(
  model: "claude-opus-5-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?"
        }
      ]
    }
  ]
)
puts message_from_url

Output

{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

后续步骤

停止原因和回退：处理每个 stop_reason 值，并决定响应结束时该如何处理。
Claude 的工具使用：为 Claude 提供工具，以便在 Messages API 中调用外部服务和 API。
计算机使用工具：使用 Messages API 控制桌面计算机环境。
浏览器使用工具：让 Claude 在您运行的浏览器中导航、阅读网页并与之交互。
结构化输出：从 Claude 获取有保证的、经过 schema 验证的 JSON 输出。
任务预算：使用 output_config.task_budget 为完整的智能体循环设置建议性的令牌预算。

可用性

Messages API在所有模型上可用，并具备零数据保留和HIPAA 就绪资格。

API 支持

可用

数据处理

数据处理概览

项目	零数据保留	HIPAA
状态	具备资格（不包括涵盖的模型）	具备资格
详细信息	用于生成 Claude 响应的标准 API 调用。	—

适用的端点：

/v1/messages