Messages API 사용하기

Messages API 사용하기 (Using the Messages API)

Anthropic은 Claude로 구축하는 두 가지 방법을 제공하는데, 각각 사용 사례에 맞아요. 이 가이드는 기본 요청, 멀티턴 대화, 프리필 기법, 비전 역량을 포함한 Messages API 작업의 흔한 패턴을 다뤄요. 완전한 API 명세는 Messages API 참조를, 관리형 에이전트 하니스는 Claude Managed Agents 개요를 보세요.

출처: 문서

본문

Anthropic은 Claude로 구축하는 두 가지 방법을 제공하는데, 각각 사용 사례에 맞아요:

	Messages API	Claude Managed Agents
그것이란	직접 모델 프롬프팅 접근	관리형 인프라에서 실행되는 미리 만들어진 구성 가능한 에이전트 하니스
최적	커스텀 에이전트 루프와 세밀한 제어	장기 실행 과제와 비동기 작업

이 가이드는 기본 요청, 멀티턴 대화, 프리필 기법, 비전 역량을 포함한 Messages API 작업의 흔한 패턴을 다뤄요. 완전한 API 명세는 Messages API 참조를, 관리형 에이전트 하니스는 Claude Managed Agents 개요를 보세요.

이 기능에 zero data retention(ZDR)이 어떻게 적용되는지 배우려면 [API 및 데이터 보존](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention)을 보세요.

기본 요청과 응답

`temperature`, `top_p`, `top_k` 샘플링 파라미터는 Claude 4.7 이후 모델과 Claude Mythos Preview에서 지원되지 않아요. 기본이 아닌 값으로 설정하면 400 오류를 반환해요. 요청 페이로드에서 생략하고 프롬프팅으로 모델 행동을 안내하세요. [마이그레이션 가이드](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes) 참고. ```bash cURL #!/bin/sh curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...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"} ] }' ```

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() { Role = Role.User, 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: 'claude-opus-5-5',
);
echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;

client = Anthropic::Client.new

message = client.messages.create(
  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 객체를 포함해요. 필드 참조와 예시 처리 코드는 Stop reasons 처리를 보세요.

여러 대화 턴

Messages API는 무상태(stateless)라서 항상 전체 대화 기록을 API에 보내요. 이 패턴으로 시간이 지나며 대화를 쌓을 수 있어요. 이전 대화 턴이 실제로 Claude에서 비롯될 필요는 없어요. 합성 assistant 메시지를 사용할 수 있어요.

```bash cURL #!/bin/sh curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...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?"}

  ]
}'


```bash 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?"}'

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() { 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);

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: 'claude-opus-5-5',
);

echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;

client = Anthropic::Client.new

message = client.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?" }
  ]
)
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
  }
}

메시지의 시스템 역할

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에서는 사용자 턴 이후(배치 규칙에 따름) "role": "system" 메시지를 포함해 대화 중간에 새 시스템 지시를 추가할 수 있어요. system 메시지는 messages의 첫 항목일 수 없어요. 처음부터 적용되는 지시에는 최상위 system 필드를 쓰세요.

대화 중간 시스템 메시지는 최상위 system 필드와 같은 권위를 가지지만, 메시지 기록 끝에 덧붙여지므로 그 앞에 온 어떤 캐시된 접두사도 무효화하지 않아요. 첫 턴부터 적용돼야 하는 지시에는 최상위 system 필드를, 나중에만 관련이 되는 지시에는 대화 중간 시스템 메시지를 쓰세요.

완전한 가이드는 대화 중간 시스템 메시지(프롬프트 캐싱과 결합하는 방법 포함)를 보세요.

Claude의 응답 프리필

입력 메시지 목록의 마지막 위치에서 Claude의 응답 일부를 프리필할 수 있어요. 이 기법으로 Claude의 응답을 형태화하세요. 다음 예시는 "max_tokens": 1을 써서 Claude로부터 단일 객관식 답을 얻어요.

프리필은 Claude 4.6 이후 모델과 [Claude Mythos Preview](https://anthropic.com/glasswing)에서 지원되지 않아요. 이 모델들로 프리필을 쓰는 요청은 400 오류를 반환해요. 지원하는 모델에서는 [구조화된 출력](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)을, 그 외에는 시스템 프롬프트 지시를 쓰세요. 마이그레이션 패턴은 [마이그레이션 가이드](https://platform.claude.com/docs/en/about-claude/models/migration-guide)를 보세요. ```bash cURL #!/bin/sh curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHR...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 ("} ] }' ```

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() { 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);

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: "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
  }
}

Vision

Claude는 요청에서 텍스트와 이미지 둘 다 읽을 수 있어요. base64, url, file 소스 타입으로 이미지를 제공할 수 있어요. file 소스 타입은 Files API를 통해 업로드한 이미지를 참조해요. 지원되는 미디어 타입은 image/jpeg, image/png, image/gif, image/webp예요. 자세한 내용은 비전 가이드를 보세요.

```bash cURL #!/bin/sh

Option 1: Base64-encoded image

IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg" IMAGE_MEDIA_TYPE="image/jpeg" IMAGE_BASE64=$(curl "$IMAGE_URL" | base64 | tr -d '\n')

curl https://api.anthropic.com/v1/messages
-H "x-api-key: $ANTHR...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_MEDIA_TYPE", "data": "$IMAGE_BASE64" }}, {"type": "text", "text": "What is in the above image?"} ]} ] } EOF

Option 2: URL-referenced image

curl https://api.anthropic.com/v1/messages
-H "x-api-key: $ANTHR...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?"} ]} ] }'


```bash CLI
IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"

# Option 1: Base64-encoded image (CLI auto-encodes binary @file refs)
curl -s "$IMAGE_URL" -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

# Option 2: URL-referenced image
ant messages create <<YAML
model: claude-opus-5-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

import base64
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(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)

# Option 2: URL-referenced image
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();

// Option 1: Base64-encoded image
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);

// Option 2: URL-referenced image
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();

// Option 1: Base64-encoded image
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()
        {
            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.ClaudeOpus5_5,
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = new MessageParamContent(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()

// Option 1: Base64-encoded image
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)

// Option 2: URL-referenced image
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();

// Option 1: Base64-encoded image
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)
        .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://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)
        .addUserMessageOfBlockParams(urlContent)
        .build());
System.out.println(messageFromUrl);

$client = new Client();

// Option 1: Base64-encoded image
$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;

// Option 2: URL-referenced image
$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

# Option 1: Base64-encoded image
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

# Option 2: URL-referenced image
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
  }
}

다음 단계

Handle each `stop_reason` value and decide what to do when a response ends. Give Claude tools to call external services and APIs from within the Messages API. Control desktop computer environments with the Messages API. Let Claude navigate, read, and interact with webpages in a browser you run. Get guaranteed, schema-validated JSON output from Claude. Set an advisory token budget across a full agentic loop with `output_config.task_budget`.

Messages API 사용하기