使用 Messages API

有效使用 Messages API 的实用模式和示例

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

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

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

基本请求和响应

示例代码
#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'
示例代码
ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'
示例代码
message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
示例代码
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)
示例代码
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);
示例代码
$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;
示例代码
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
示例代码
{
  "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 消息。

借助目前处于 beta 阶段的消息线程,API 可以将对话保留下来,这样之后的每个请求只需发送新消息。线程会在其最后一次请求后 5 分钟过期,并在其最后一次使用后不超过 1 小时内被删除。

示例代码
#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -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?"}

    ]
  }'
示例代码
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?"}'
示例代码
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)
示例代码
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)
示例代码
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);
示例代码
$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;
示例代码
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
示例代码
{
  "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 角色

如需在对话中途添加新的系统指令,请在用户轮次之后紧接着包含一条 "role": "system" 的消息。该消息不能作为 messages 中的第一个条目。此功能适用于 Claude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8、Claude Sonnet 5.5 和 Claude Haiku 5.5。请参阅完整的放置规则。

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

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

预填充 Claude 的响应

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

示例代码
#!/bin/sh
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -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 ("}
    ]
  }'
示例代码
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
示例代码
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)
示例代码
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)
示例代码
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);
示例代码
$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;
示例代码
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
示例代码
{
  "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。有关更多详细信息,请参阅视觉指南。

示例代码
#!/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: 2026-10-21" \
  -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: 2026-10-21" \
  -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?"}
      ]}
    ]
  }'
示例代码
# 选项 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
示例代码
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)
示例代码
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)
示例代码
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);
示例代码
$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;
示例代码
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
示例代码
{
  "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
  }
}

后续步骤

结构化输出

从 Claude 获取有保证的、经过 schema 验证的 JSON 输出。

任务预算

使用 output_config.task_budget 为完整的智能体循环设置建议性的令牌预算。

可用性

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

API 支持

可用

数据处理

数据处理概览

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

适用的端点:

  • /v1/messages
文档内容持续同步更新