Repository Public
1---2title: Vision3url: https://platform.claude.com/docs/en/build-with-claude/vision4description: Claude's vision capabilities allow it to understand and analyze images, opening up exciting possibilities for multimodal interaction.5---67This guide describes how to send images to Claude, the limits and costs that apply, and where to find guidance for [coordinate-based workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates).89***1011## Send images to Claude1213Use Claude's vision capabilities through:1415* [claude.ai](https://claude.ai/). Upload an image like you would a file, or drag and drop an image directly into the chat window.16* [Playground](https://platform.claude.com/playground) in the Claude Console. Add images directly to any User message block.17* API request. See the following examples.1819On the API, provide images to Claude as `image` content blocks using one of three source types:20211. A base64-encoded image embedded in the request body222. A URL reference to an image hosted online233. A `file_id` returned by the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (upload once, reference many times)2425<Note>26 On Amazon Bedrock and Google Cloud, only base64-encoded sources are currently available.27</Note>2829<Tip>30 Just as [placing long documents before your query](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#long-context-prompting) improves results in text prompts, Claude works best when images come before text. Images placed after text or interpolated with text still perform well, but if your use case allows it, prefer an image-then-text structure.31</Tip>3233### Base64-encoded image example3435<CodeGroup>36 ```bash cURL37 curl https://api.anthropic.com/v1/messages \38 -H "x-api-key: $ANTHROPIC_API_KEY" \39 -H "anthropic-version: 2023-06-01" \40 -H "content-type: application/json" \41 -d @- <<EOF42 {43 "model": "claude-opus-5",44 "max_tokens": 1024,45 "messages": [46 {47 "role": "user",48 "content": [49 {50 "type": "image",51 "source": {52 "type": "base64",53 "media_type": "image/jpeg",54 "data": "$BASE64_IMAGE_DATA"55 }56 },57 {58 "type": "text",59 "text": "Describe this image."60 }61 ]62 }63 ]64 }65 EOF66 ```6768 ```bash CLI69 curl -sSo ./vision-example.jpg \70 https://platform.claude.com/docs/images/vision-example.jpg7172 ant messages create <<'YAML'73 model: claude-opus-574 max_tokens: 102475 messages:76 - role: user77 content:78 - type: image79 source:80 type: base6481 media_type: image/jpeg82 data: "@./vision-example.jpg"83 - type: text84 text: Describe this image.85 YAML86 ```8788 ```python Python89 image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"90 image1_media_type = "image/png"9192 client = anthropic.Anthropic()93 message = client.messages.create(94 model="claude-opus-5",95 max_tokens=1024,96 messages=[97 {98 "role": "user",99 "content": [100 {101 "type": "image",102 "source": {103 "type": "base64",104 "media_type": image1_media_type,105 "data": image1_data,106 },107 },108 {"type": "text", "text": "Describe this image."},109 ],110 }111 ],112 )113 print(message)114 ```115116 ```typescript TypeScript117 const anthropic = new Anthropic();118119 const message = await anthropic.messages.create({120 model: "claude-opus-5",121 max_tokens: 1024,122 messages: [123 {124 role: "user",125 content: [126 {127 type: "image",128 source: {129 type: "base64",130 media_type: "image/jpeg",131 data: imageData // Base64-encoded image data as string132 }133 },134 {135 type: "text",136 text: "Describe this image."137 }138 ]139 }140 ]141 });142143 console.log(message);144 ```145146 ```csharp C#147 using System.Collections.Generic;148 using Anthropic;149 using Anthropic.Models.Messages;150151 AnthropicClient client = new();152153 string imageData = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";154155 var message = await client.Messages.Create(new MessageCreateParams156 {157 Model = Model.ClaudeOpus5,158 MaxTokens = 1024,159 Messages =160 [161 new()162 {163 Role = Role.User,164 Content = new MessageParamContent(new List<ContentBlockParam>165 {166 new ContentBlockParam(new ImageBlockParam(167 new ImageBlockParamSource(new Base64ImageSource()168 {169 Data = imageData,170 MediaType = MediaType.ImagePng,171 })172 )),173 new ContentBlockParam(new TextBlockParam("Describe this image.")),174 }),175 }176 ]177 });178179 Console.WriteLine(message);180 ```181182 ```go Go183 client := anthropic.NewClient()184185 imageData := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"186187 message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{188 Model: anthropic.ModelClaudeOpus5,189 MaxTokens: 1024,190 Messages: []anthropic.MessageParam{191 anthropic.NewUserMessage(192 anthropic.NewImageBlockBase64("image/png", imageData),193 anthropic.NewTextBlock("Describe this image."),194 ),195 },196 })197 if err != nil {198 log.Fatal(err)199 }200201 fmt.Println(message)202 ```203204 ```java Java205 AnthropicClient client = AnthropicOkHttpClient.fromEnv();206 String imageData =207 "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";208209 List<ContentBlockParam> contentBlockParams = List.of(210 ContentBlockParam.ofImage(211 ImageBlockParam.builder()212 .source(213 Base64ImageSource.builder()214 .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)215 .data(imageData)216 .build()217 )218 .build()219 ),220 ContentBlockParam.ofText(TextBlockParam.builder().text("Describe this image.").build())221 );222 Message message = client223 .messages()224 .create(225 MessageCreateParams.builder()226 .model(Model.CLAUDE_OPUS_5)227 .maxTokens(1024)228 .addUserMessageOfBlockParams(contentBlockParams)229 .build()230 );231232 IO.println(message);233 ```234235 ```php PHP236 $client = new Client();237238 $imageData = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";239240 $message = $client->messages->create(241 maxTokens: 1024,242 messages: [243 [244 'role' => 'user',245 'content' => [246 [247 'type' => 'image',248 'source' => [249 'type' => 'base64',250 'media_type' => 'image/png',251 'data' => $imageData,252 ],253 ],254 ['type' => 'text', 'text' => 'Describe this image.'],255 ],256 ],257 ],258 model: 'claude-opus-5',259 );260261 echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;262 ```263264 ```ruby Ruby265 client = Anthropic::Client.new266267 image_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"268269 message = client.messages.create(270 model: "claude-opus-5",271 max_tokens: 1024,272 messages: [273 {274 role: "user",275 content: [276 {277 type: "image",278 source: {279 type: "base64",280 media_type: "image/png",281 data: image_data282 }283 },284 { type: "text", text: "Describe this image." }285 ]286 }287 ]288 )289290 puts message291 ```292</CodeGroup>293294### URL-based image example295296<CodeGroup>297 ```bash cURL298 curl https://api.anthropic.com/v1/messages \299 -H "x-api-key: $ANTHROPIC_API_KEY" \300 -H "anthropic-version: 2023-06-01" \301 -H "content-type: application/json" \302 -d '{303 "model": "claude-opus-5",304 "max_tokens": 1024,305 "messages": [306 {307 "role": "user",308 "content": [309 {310 "type": "image",311 "source": {312 "type": "url",313 "url": "https://platform.claude.com/docs/images/vision-example.jpg"314 }315 },316 {317 "type": "text",318 "text": "Describe this image."319 }320 ]321 }322 ]323 }'324 ```325326 ```bash CLI327 ant messages create <<'YAML'328 model: claude-opus-5329 max_tokens: 1024330 messages:331 - role: user332 content:333 - type: image334 source:335 type: url336 url: https://platform.claude.com/docs/images/vision-example.jpg337 - type: text338 text: Describe this image.339 YAML340 ```341342 ```python Python343 client = anthropic.Anthropic()344 message = client.messages.create(345 model="claude-opus-5",346 max_tokens=1024,347 messages=[348 {349 "role": "user",350 "content": [351 {352 "type": "image",353 "source": {354 "type": "url",355 "url": "https://platform.claude.com/docs/images/vision-example.jpg",356 },357 },358 {"type": "text", "text": "Describe this image."},359 ],360 }361 ],362 )363 print(message)364 ```365366 ```typescript TypeScript367 const anthropic = new Anthropic();368369 const message = await anthropic.messages.create({370 model: "claude-opus-5",371 max_tokens: 1024,372 messages: [373 {374 role: "user",375 content: [376 {377 type: "image",378 source: {379 type: "url",380 url: "https://platform.claude.com/docs/images/vision-example.jpg"381 }382 },383 {384 type: "text",385 text: "Describe this image."386 }387 ]388 }389 ]390 });391392 console.log(message);393 ```394395 ```csharp C#396 using System.Collections.Generic;397 using Anthropic;398 using Anthropic.Models.Messages;399400 AnthropicClient client = new();401402 var message = await client.Messages.Create(new MessageCreateParams403 {404 Model = Model.ClaudeOpus5,405 MaxTokens = 1024,406 Messages =407 [408 new()409 {410 Role = Role.User,411 Content = new MessageParamContent(new List<ContentBlockParam>412 {413 new ContentBlockParam(new ImageBlockParam(414 new ImageBlockParamSource(new UrlImageSource()415 {416 Url = "https://platform.claude.com/docs/images/vision-example.jpg",417 })418 )),419 new ContentBlockParam(new TextBlockParam("Describe this image.")),420 }),421 }422 ]423 });424425 Console.WriteLine(message);426 ```427428 ```go Go429 client := anthropic.NewClient()430431 message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{432 Model: anthropic.ModelClaudeOpus5,433 MaxTokens: 1024,434 Messages: []anthropic.MessageParam{435 anthropic.NewUserMessage(436 anthropic.NewImageBlock(anthropic.URLImageSourceParam{437 URL: "https://platform.claude.com/docs/images/vision-example.jpg",438 }),439 anthropic.NewTextBlock("Describe this image."),440 ),441 },442 })443 if err != nil {444 log.Fatal(err)445 }446447 fmt.Println(message)448 ```449450 ```java Java451 AnthropicClient client = AnthropicOkHttpClient.fromEnv();452453 List<ContentBlockParam> contentBlockParams = List.of(454 ContentBlockParam.ofImage(455 ImageBlockParam.builder()456 .source(457 UrlImageSource.builder()458 .url("https://platform.claude.com/docs/images/vision-example.jpg")459 .build()460 )461 .build()462 ),463 ContentBlockParam.ofText(TextBlockParam.builder().text("Describe this image.").build())464 );465 Message message = client466 .messages()467 .create(468 MessageCreateParams.builder()469 .model(Model.CLAUDE_OPUS_5)470 .maxTokens(1024)471 .addUserMessageOfBlockParams(contentBlockParams)472 .build()473 );474 System.out.println(message);475 ```476477 ```php PHP478 $client = new Client();479480 $message = $client->messages->create(481 maxTokens: 1024,482 messages: [483 [484 'role' => 'user',485 'content' => [486 [487 'type' => 'image',488 'source' => [489 'type' => 'url',490 'url' => 'https://platform.claude.com/docs/images/vision-example.jpg',491 ],492 ],493 ['type' => 'text', 'text' => 'Describe this image.'],494 ],495 ],496 ],497 model: 'claude-opus-5',498 );499500 echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;501 ```502503 ```ruby Ruby504 client = Anthropic::Client.new505506 message = client.messages.create(507 model: "claude-opus-5",508 max_tokens: 1024,509 messages: [510 {511 role: "user",512 content: [513 {514 type: "image",515 source: {516 type: "url",517 url: "https://platform.claude.com/docs/images/vision-example.jpg"518 }519 },520 { type: "text", text: "Describe this image." }521 ]522 }523 ]524 )525526 puts message527 ```528</CodeGroup>529530### Files API image example531532For images you'll use repeatedly or when you want to avoid encoding overhead, use the [Files API](https://platform.claude.com/docs/en/build-with-claude/files). Upload the image once, then reference the returned `file_id` in subsequent messages instead of resending base64 data.533534<Tip>535 In multi-turn conversations and agentic workflows, each request resends the full conversation history. If images are base64-encoded, the full image bytes are included in the payload on every turn, which can significantly increase request size and latency as the conversation grows. Uploading images to the Files API and referencing them by `file_id` keeps request payloads small regardless of how many images accumulate in the conversation history.536</Tip>537538<CodeGroup>539 ```bash cURL540 # First, upload your image to the Files API541 FILE_ID=$(curl -sS -X POST https://api.anthropic.com/v1/files \542 -H "x-api-key: $ANTHROPIC_API_KEY" \543 -H "anthropic-version: 2023-06-01" \544 -F "file=@vision-example.jpg" | jq -r '.id')545546 # Then use the returned file_id in your message547 curl https://api.anthropic.com/v1/messages \548 -H "x-api-key: $ANTHROPIC_API_KEY" \549 -H "anthropic-version: 2023-06-01" \550 -H "content-type: application/json" \551 -d @- <<EOF552 {553 "model": "claude-opus-5",554 "max_tokens": 1024,555 "messages": [556 {557 "role": "user",558 "content": [559 {560 "type": "image",561 "source": {562 "type": "file",563 "file_id": "$FILE_ID"564 }565 },566 {567 "type": "text",568 "text": "Describe this image."569 }570 ]571 }572 ]573 }574 EOF575 ```576577 ```bash CLI578 curl -sSo vision-example.jpg \579 https://platform.claude.com/docs/images/vision-example.jpg580581 # First, upload your image to the Files API582 FILE_ID=$(ant files upload \583 --file ./vision-example.jpg \584 --transform id --raw-output)585586 # Then use the returned file_id in your message587 ant messages create \588 --transform content --format yaml <<YAML589 model: claude-opus-5590 max_tokens: 1024591 messages:592 - role: user593 content:594 - type: image595 source:596 type: file597 file_id: $FILE_ID598 - type: text599 text: Describe this image.600 YAML601 ```602603 ```python Python604 client = anthropic.Anthropic()605606 # Upload the image file607 with open("vision-example.jpg", "rb") as f:608 file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))609610 # Use the uploaded file in a message611 message = client.messages.create(612 model="claude-opus-5",613 max_tokens=1024,614 messages=[615 {616 "role": "user",617 "content": [618 {619 "type": "image",620 "source": {"type": "file", "file_id": file_upload.id},621 },622 {"type": "text", "text": "Describe this image."},623 ],624 }625 ],626 )627628 print(message.content)629 ```630631 ```typescript TypeScript632 import Anthropic, { toFile } from "@anthropic-ai/sdk";633 import fs from "node:fs";634635 const anthropic = new Anthropic();636637 // Upload the image file638 const fileUpload = await anthropic.files.upload({639 file: await toFile(fs.createReadStream("vision-example.jpg"), undefined, {640 type: "image/jpeg"641 })642 });643644 // Use the uploaded file in a message645 const response = await anthropic.messages.create({646 model: "claude-opus-5",647 max_tokens: 1024,648 messages: [649 {650 role: "user",651 content: [652 {653 type: "image",654 source: {655 type: "file",656 file_id: fileUpload.id657 }658 },659 {660 type: "text",661 text: "Describe this image."662 }663 ]664 }665 ]666 });667668 console.log(response);669 ```670671 ```csharp C#672 using System.Collections.Generic;673 using Anthropic;674 using Anthropic.Core;675 using Anthropic.Models.Files;676 using Anthropic.Models.Messages;677678 AnthropicClient client = new();679680 // Upload the image file681 var fileUpload = await client.Files.Upload(new FileUploadParams682 {683 File = new BinaryContent684 {685 Stream = File.OpenRead("vision-example.jpg"),686 FileName = "vision-example.jpg",687 ContentType = new("image/jpeg"),688 },689 });690691 // Use the uploaded file in a message692 var response = await client.Messages.Create(new MessageCreateParams693 {694 Model = Model.ClaudeOpus5,695 MaxTokens = 1024,696 Messages =697 [698 new()699 {700 Role = Role.User,701 Content = new MessageParamContent(new List<ContentBlockParam>702 {703 new ContentBlockParam(new ImageBlockParam(704 new ImageBlockParamSource(new FileImageSource(fileUpload.ID))705 )),706 new ContentBlockParam(new TextBlockParam("Describe this image.")),707 }),708 }709 ]710 });711712 Console.WriteLine(response);713 ```714715 ```go Go716 client := anthropic.NewClient()717718 // Upload the image file719 file, err := os.Open("vision-example.jpg")720 if err != nil {721 log.Fatal(err)722 }723 defer file.Close()724725 fileUpload, err := client.Files.Upload(context.Background(),726 anthropic.FileUploadParams{727 File: anthropic.File(file, "vision-example.jpg", "image/jpeg"),728 })729 if err != nil {730 log.Fatal(err)731 }732733 // Use the uploaded file in a message734 message, err := client.Messages.New(context.Background(),735 anthropic.MessageNewParams{736 Model: anthropic.ModelClaudeOpus5,737 MaxTokens: 1024,738 Messages: []anthropic.MessageParam{739 anthropic.NewUserMessage(740 anthropic.NewImageBlock(anthropic.FileImageSourceParam{741 FileID: fileUpload.ID,742 }),743 anthropic.NewTextBlock("Describe this image."),744 ),745 },746 })747 if err != nil {748 log.Fatal(err)749 }750751 fmt.Println(message.Content)752 ```753754 ```java Java755 import com.anthropic.core.MultipartField;756 import com.anthropic.models.files.FileMetadata;757 import com.anthropic.models.files.FileUploadParams;758 // ...759 AnthropicClient client = AnthropicOkHttpClient.fromEnv();760761 // Upload the image file762 FileMetadata file = client.files().upload(763 FileUploadParams.builder()764 .file(765 MultipartField.<InputStream>builder()766 .value(Files.newInputStream(Path.of("vision-example.jpg")))767 .filename("vision-example.jpg")768 .contentType("image/jpeg")769 .build()770 )771 .build()772 );773774 // Use the uploaded file in a message775 ImageBlockParam imageParam = ImageBlockParam.builder().fileSource(file.id()).build();776777 MessageCreateParams params = MessageCreateParams.builder()778 .model(Model.CLAUDE_OPUS_5)779 .maxTokens(1024)780 .addUserMessageOfBlockParams(781 List.of(782 ContentBlockParam.ofImage(imageParam),783 ContentBlockParam.ofText(784 TextBlockParam.builder().text("Describe this image.").build()785 )786 )787 )788 .build();789790 Message message = client.messages().create(params);791 System.out.println(message.content());792 ```793794 ```php PHP795 use Anthropic\Core\FileParam;796797 $client = new Client();798799 // Upload the image file800 $fileUpload = $client->files->upload(801 file: FileParam::fromResource(fopen('vision-example.jpg', 'rb'), contentType: 'image/jpeg'),802 );803804 // Use the uploaded file in a message805 $message = $client->messages->create(806 maxTokens: 1024,807 messages: [808 [809 'role' => 'user',810 'content' => [811 [812 'type' => 'image',813 'source' => ['type' => 'file', 'fileID' => $fileUpload->id],814 ],815 ['type' => 'text', 'text' => 'Describe this image.'],816 ],817 ],818 ],819 model: 'claude-opus-5',820 );821822 echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;823 ```824825 ```ruby Ruby826 client = Anthropic::Client.new827828 # Upload the image file829 file_upload = client.files.upload(830 file: Anthropic::FilePart.new(831 File.open("vision-example.jpg", "rb"),832 content_type: "image/jpeg"833 )834 )835836 # Use the uploaded file in a message837 message = client.messages.create(838 model: "claude-opus-5",839 max_tokens: 1024,840 messages: [841 {842 role: "user",843 content: [844 {845 type: "image",846 source: { type: "file", file_id: file_upload.id }847 },848 { type: "text", text: "Describe this image." }849 ]850 }851 ]852 )853854 puts message.content855 ```856</CodeGroup>857858See [Messages API examples](https://platform.claude.com/docs/en/api/messages/create) for more example code and parameter details.859860### Multiple images861862You can include multiple images in a single request, and Claude analyzes them jointly. This is useful for comparing images, asking about differences, or working with a sequence such as pages of a document. When sending several images, introduce each one with a short text label (`Image 1:`, `Image 2:`, and so on) so you can refer to them by name in your prompt and in follow-up turns.863864<CodeGroup>865 ```bash cURL866 curl https://api.anthropic.com/v1/messages \867 -H "x-api-key: $ANTHROPIC_API_KEY" \868 -H "anthropic-version: 2023-06-01" \869 -H "content-type: application/json" \870 -d '{871 "model": "claude-opus-5",872 "max_tokens": 1024,873 "messages": [874 {875 "role": "user",876 "content": [877 {878 "type": "text",879 "text": "Image 1:"880 },881 {882 "type": "image",883 "source": {884 "type": "base64",885 "media_type": "image/png",886 "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"887 }888 },889 {890 "type": "text",891 "text": "Image 2:"892 },893 {894 "type": "image",895 "source": {896 "type": "base64",897 "media_type": "image/png",898 "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"899 }900 },901 {902 "type": "text",903 "text": "How are these images different?"904 }905 ]906 }907 ]908 }'909 ```910911 ```bash CLI912 ant messages create <<'YAML'913 model: claude-opus-5914 max_tokens: 1024915 messages:916 - role: user917 content:918 - type: text919 text: "Image 1:"920 - type: image921 source:922 type: base64923 media_type: image/png924 data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC925 - type: text926 text: "Image 2:"927 - type: image928 source:929 type: base64930 media_type: image/png931 data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC932 - type: text933 text: How are these images different?934 YAML935 ```936937 ```python Python938 image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"939 image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"940941 client = anthropic.Anthropic()942 message = client.messages.create(943 model="claude-opus-5",944 max_tokens=1024,945 messages=[946 {947 "role": "user",948 "content": [949 {"type": "text", "text": "Image 1:"},950 {951 "type": "image",952 "source": {953 "type": "base64",954 "media_type": "image/png",955 "data": image1_data,956 },957 },958 {"type": "text", "text": "Image 2:"},959 {960 "type": "image",961 "source": {962 "type": "base64",963 "media_type": "image/png",964 "data": image2_data,965 },966 },967 {"type": "text", "text": "How are these images different?"},968 ],969 }970 ],971 )972 print(message)973 ```974975 ```typescript TypeScript976 const anthropic = new Anthropic();977978 const image1Data =979 "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";980 const image2Data =981 "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";982983 const message = await anthropic.messages.create({984 model: "claude-opus-5",985 max_tokens: 1024,986 messages: [987 {988 role: "user",989 content: [990 {991 type: "text",992 text: "Image 1:"993 },994 {995 type: "image",996 source: {997 type: "base64",998 media_type: "image/png",999 data: image1Data1000 }1001 },1002 {1003 type: "text",1004 text: "Image 2:"1005 },1006 {1007 type: "image",1008 source: {1009 type: "base64",1010 media_type: "image/png",1011 data: image2Data1012 }1013 },1014 {1015 type: "text",1016 text: "How are these images different?"1017 }1018 ]1019 }1020 ]1021 });10221023 console.log(message);1024 ```10251026 ```csharp C#1027 AnthropicClient client = new();10281029 string image1Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";1030 string image2Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";10311032 var message = await client.Messages.Create(new MessageCreateParams1033 {1034 Model = Model.ClaudeOpus5,1035 MaxTokens = 1024,1036 Messages =1037 [1038 new()1039 {1040 Role = Role.User,1041 Content = new MessageParamContent(new List<ContentBlockParam>1042 {1043 new ContentBlockParam(new TextBlockParam("Image 1:")),1044 new ContentBlockParam(new ImageBlockParam(1045 new ImageBlockParamSource(new Base64ImageSource()1046 {1047 Data = image1Data,1048 MediaType = MediaType.ImagePng,1049 })1050 )),1051 new ContentBlockParam(new TextBlockParam("Image 2:")),1052 new ContentBlockParam(new ImageBlockParam(1053 new ImageBlockParamSource(new Base64ImageSource()1054 {1055 Data = image2Data,1056 MediaType = MediaType.ImagePng,1057 })1058 )),1059 new ContentBlockParam(new TextBlockParam("How are these images different?")),1060 }),1061 }1062 ]1063 });10641065 Console.WriteLine(message);1066 ```10671068 ```go Go1069 client := anthropic.NewClient()10701071 image1Data := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"1072 image2Data := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"10731074 message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{1075 Model: anthropic.ModelClaudeOpus5,1076 MaxTokens: 1024,1077 Messages: []anthropic.MessageParam{1078 anthropic.NewUserMessage(1079 anthropic.NewTextBlock("Image 1:"),1080 anthropic.NewImageBlockBase64("image/png", image1Data),1081 anthropic.NewTextBlock("Image 2:"),1082 anthropic.NewImageBlockBase64("image/png", image2Data),1083 anthropic.NewTextBlock("How are these images different?"),1084 ),1085 },1086 })1087 if err != nil {1088 log.Fatal(err)1089 }10901091 fmt.Println(message)1092 ```10931094 ```java Java1095 AnthropicClient client = AnthropicOkHttpClient.fromEnv();10961097 String image1Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";1098 String image2Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";10991100 List<ContentBlockParam> contentBlockParams = List.of(1101 ContentBlockParam.ofText(TextBlockParam.builder().text("Image 1:").build()),1102 ContentBlockParam.ofImage(1103 ImageBlockParam.builder()1104 .source(1105 Base64ImageSource.builder()1106 .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)1107 .data(image1Data)1108 .build()1109 )1110 .build()1111 ),1112 ContentBlockParam.ofText(TextBlockParam.builder().text("Image 2:").build()),1113 ContentBlockParam.ofImage(1114 ImageBlockParam.builder()1115 .source(1116 Base64ImageSource.builder()1117 .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)1118 .data(image2Data)1119 .build()1120 )1121 .build()1122 ),1123 ContentBlockParam.ofText(1124 TextBlockParam.builder().text("How are these images different?").build()1125 )1126 );11271128 Message message = client1129 .messages()1130 .create(1131 MessageCreateParams.builder()1132 .model(Model.CLAUDE_OPUS_5)1133 .maxTokens(1024)1134 .addUserMessageOfBlockParams(contentBlockParams)1135 .build()1136 );11371138 IO.println(message);1139 ```11401141 ```php PHP1142 $client = new Client();11431144 $image1Data = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';1145 $image2Data = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC';11461147 $message = $client->messages->create(1148 maxTokens: 1024,1149 messages: [1150 [1151 'role' => 'user',1152 'content' => [1153 ['type' => 'text', 'text' => 'Image 1:'],1154 [1155 'type' => 'image',1156 'source' => [1157 'type' => 'base64',1158 'media_type' => 'image/png',1159 'data' => $image1Data,1160 ],1161 ],1162 ['type' => 'text', 'text' => 'Image 2:'],1163 [1164 'type' => 'image',1165 'source' => [1166 'type' => 'base64',1167 'media_type' => 'image/png',1168 'data' => $image2Data,1169 ],1170 ],1171 ['type' => 'text', 'text' => 'How are these images different?'],1172 ],1173 ],1174 ],1175 model: 'claude-opus-5',1176 );11771178 echo $message;1179 ```11801181 ```ruby Ruby1182 client = Anthropic::Client.new11831184 image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"1185 image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"11861187 message = client.messages.create(1188 model: "claude-opus-5",1189 max_tokens: 1024,1190 messages: [1191 {1192 role: "user",1193 content: [1194 { type: "text", text: "Image 1:" },1195 {1196 type: "image",1197 source: {1198 type: "base64",1199 media_type: "image/png",1200 data: image1_data1201 }1202 },1203 { type: "text", text: "Image 2:" },1204 {1205 type: "image",1206 source: {1207 type: "base64",1208 media_type: "image/png",1209 data: image2_data1210 }1211 },1212 { type: "text", text: "How are these images different?" }1213 ]1214 }1215 ]1216 )12171218 puts message1219 ```1220</CodeGroup>12211222In a multi-turn conversation, add new images in later `user` turns the same way. Claude has access to every image from earlier turns, so follow-up questions such as "Are these similar to the first two?" work without including the earlier images again in the new turn's content.12231224***12251226## Image limits and costs12271228### Request limits12291230The maximum number of images per message or request is:12311232* 20 per message on [claude.ai](https://claude.ai/).1233* 100 per request on the API, for models with a 200k-token context window.1234* 600 per request on the API, for all other models.12351236The maximum dimensions per image are 8000x8000 px.12371238If a single API request contains more than 20 images, a stricter per-image dimension limit applies to every image in that request. All `image` blocks in the request count toward this threshold, including images from earlier conversation turns that you resend and images nested inside `tool_result` content (for example, screenshots returned to the computer use tool). On Amazon Bedrock and Google Cloud, document blocks such as PDFs also count toward this threshold. Images exceeding the stricter limit are rejected with an `invalid_request_error` whose message references "many-image requests" and states the current limit in pixels. To stay under the limit on all platforms, either resize each image so that neither dimension exceeds 2000 px, or keep the request to 20 or fewer image and document blocks.12391240The maximum size per image is:12411242* 10 MB (base64-encoded) when using the Claude API directly.1243* 5 MB (base64-encoded) on Amazon Bedrock and Google Cloud.1244* 10 MB on [claude.ai](https://claude.ai/).12451246<Note>1247 Although the API supports up to 600 images per request, [request size limits](https://platform.claude.com/docs/en/api/overview#request-size-limits) (32 MB for standard endpoints; lower on some partner-operated platforms, for example, Amazon Bedrock and Google Cloud) can be reached first. For many images, consider uploading with the [Files API](https://platform.claude.com/docs/en/build-with-claude/vision#files-api-image-example) and referencing by `file_id` to keep request payloads small.12481249 Even when using the Files API, requests with many large images can fail before reaching the 600-image count. Reduce image dimensions or file sizes (for example, by downsampling) before uploading (see [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size)).1250</Note>12511252### Supported formats12531254Claude supports JPEG, PNG, GIF, and WebP images (`image/jpeg`, `image/png`, `image/gif`, `image/webp`). Animations are unsupported, and only the first frame is used.12551256### Resolution and token cost12571258Claude views images in patches instead of pixels. Each patch is a 28×28-pixel block of the image, referred to as a visual token. An image, therefore, costs `⌈width / 28⌉ × ⌈height / 28⌉` visual tokens.12591260Each model has a maximum native image resolution, expressed as a long-edge limit and a visual-token limit. Images larger than either limit are downscaled before processing; see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images) for the exact rule. The exception is screenshots and zoom images that you return to the [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) toolsets: the API rejects a `tool_result` image that exceeds the model's limits with a validation error instead of downscaling it, so resize those images in your application before returning them. To have any other oversized image rejected with an error instead of downscaled, set the image block's [`transformations` field](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error).12611262| Resolution tier | Models | Max long edge | Max visual tokens |1263| --------------- | --------------------------- | ------------- | ----------------- |1264| High-resolution | Claude 4.7 and later models | 2576 px | 4784 |1265| Standard | All other models | 1568 px | 1568 |12661267High-resolution support is automatic on the listed models and requires no beta header or client-side opt-in.12681269The following table shows the downsized resolution and visual-token cost for several image sizes on each tier:12701271| Image size | Standard tier: downsized to | Standard tier: tokens | High-resolution tier: downsized to | High-resolution tier: tokens |1272| ------------------------------ | --------------------------- | --------------------- | ---------------------------------- | ---------------------------- |1273| 200x200 px (0.04 megapixels) | Not resized | 64 | Not resized | 64 |1274| 1000x1000 px (1 megapixel) | Not resized | 1296 | Not resized | 1296 |1275| 1092x1092 px (1.19 megapixels) | Not resized | 1521 | Not resized | 1521 |1276| 1920x1080 px (2.07 megapixels) | 1456x819 px | 1560 | Not resized | 2691 |1277| 2000x1500 px (3 megapixels) | 1269x952 px | 1564 | Not resized | 3888 |1278| 3840x2160 px (8.29 megapixels) | 1456x819 px | 1560 | 2576x1449 px | 4784 |12791280When an image is downsized, Claude scales it to the largest size that fits the tier's limits while preserving its aspect ratio. This caps the token cost. For the precise rule and a reference implementation, see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images).12811282To estimate cost, multiply the token count by the [per-token price of the model](https://claude.com/pricing) you're using. For example, at Claude Haiku 4.5's $1 USD per million input tokens (standard tier), the 1000×1000 image costs about $1.30 USD per thousand images. At Claude Opus 5's $5 USD per million (high-resolution tier), the same image costs about $6.48 USD per thousand and the 4K image about $23.92 USD per thousand.12831284High-resolution images can use up to roughly three times more visual tokens than the same image on a standard-tier model. If you don't need the additional fidelity that high resolution provides for computer use, screenshot understanding, and dense documents, downsample images before sending to control token costs. To minimize latency and to simplify [coordinate-based workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates), prefer resizing images before uploading them.12851286### Image quality guidance12871288When providing images to Claude, keep the following in mind for best results:12891290* **Image clarity:** Ensure images are clear and not too blurry or pixelated.1291* **Text:** If the image contains important text, make sure it's legible and not too small. Avoid cropping out key visual context solely to enlarge the text.1292* **Resizing:** Take into account that your image might be resized if it is too large (see [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size)); this might, for example, make text less legible. Consider pre-resizing your images, cropping them, or both. To have an oversized image rejected with an error instead of resized (important for [coordinate workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates)), mark the image block with [`"oversized_image": "error"`](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error).1293* **Image compression:** Compressing images before sending them, using a lossy format such as JPEG or WebP (lossy mode), can reduce latency by reducing the size of requests. However, this can introduce artifacts that are detrimental to model performance, especially when multiple compression passes are applied. For example, heavy JPEG compression can make text difficult to read. Confirm your compression settings are appropriate for the task by inspecting the actual images sent to the API.12941295***12961297## Coordinates and bounding boxes12981299For bounding boxes, points, and pixel coordinates, see [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates). Claude returns absolute pixel coordinates relative to the image it sees after resizing; that guide covers how Claude resizes and pads images and how to pre-resize or rescale so coordinates line up with your original image.13001301***13021303## Limitations13041305Although Claude's image understanding capabilities are cutting-edge, there are some limitations to be aware of:13061307* **People identification:** Claude [cannot be used](https://www.anthropic.com/legal/aup) to name people in images and refuses to do so.1308* **Accuracy:** Claude might hallucinate or make mistakes when interpreting low-quality, rotated, or very small images under 200 pixels.1309* **Spatial reasoning:** Claude's coordinate and localization outputs are approximate. Follow the guidance in [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates) and verify outputs before relying on them.1310* **Counting:** Claude can give approximate counts of objects in an image but might not always be precisely accurate, especially with large numbers of small objects.1311* **AI-generated images:** Claude cannot determine whether an image is AI-generated and might be incorrect if asked. Do not rely on it to detect fake or synthetic images.1312* **Inappropriate content:** Claude does not process inappropriate or explicit images that violate the [Acceptable Use Policy](https://www.anthropic.com/legal/aup).1313* **Healthcare applications:** Although Claude can analyze general medical images, it is not designed to interpret complex diagnostic scans such as CTs or MRIs. Claude's outputs should not be considered a substitute for professional medical advice or diagnosis.13141315Always carefully review and verify Claude's image interpretations, especially for high-stakes use cases. Do not use Claude for tasks requiring perfect precision or sensitive image analysis without human oversight.13161317***13181319## FAQ13201321<AccordionGroup>1322 <Accordion title="What image file types does Claude support?">1323 JPEG, PNG, GIF, and WebP. See [Supported formats](https://platform.claude.com/docs/en/build-with-claude/vision#supported-formats).1324 </Accordion>13251326 <Accordion title="Can Claude read image URLs?">1327 Yes. Use the `url` source type instead of `base64` in the `image` content block. See the [URL-based image example](https://platform.claude.com/docs/en/build-with-claude/vision#url-based-image-example).1328 </Accordion>13291330 <Accordion title="Is there a limit to the image file size I can upload?">1331 Yes. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for per-image and overall request size limits across the Claude API, Amazon Bedrock, Google Cloud, and claude.ai.1332 </Accordion>13331334 <Accordion title="How many images can I include in one request?">1335 Up to 600 per API request (100 for models with a 200k-token context window) and 20 per turn on claude.ai. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for details and the lower per-image dimension limit that applies above 20 images.1336 </Accordion>13371338 <Accordion title="Does Claude read image metadata?">1339 No, Claude does not parse or receive any metadata from images passed to it.1340 </Accordion>13411342 <Accordion title="Can I delete images I've uploaded?">1343 No. Image uploads are ephemeral and not stored beyond the duration of the API request. Uploaded images are automatically deleted after they have been processed.1344 </Accordion>13451346 <Accordion title="Where can I find details on data privacy for image uploads?">1347 Refer to the Anthropic privacy policy page for information on how uploaded images and other data are handled. Anthropic does not use uploaded images to train models.1348 </Accordion>13491350 <Accordion title="What if Claude's image interpretation seems wrong?">1351 If Claude's image interpretation seems incorrect:13521353 1. Ensure the image is clear, high-quality, and correctly oriented.1354 2. Try prompt engineering techniques to improve results.1355 3. If the issue persists, flag the output in claude.ai (thumbs up/down) or contact the [support team](https://support.claude.com/).13561357 Your feedback helps improve Claude!1358 </Accordion>13591360 <Accordion title="Can Claude generate or edit images?">1361 No, Claude is an image understanding model only. It can interpret and analyze images, but it cannot generate, produce, edit, manipulate, or create images.1362 </Accordion>1363</AccordionGroup>13641365***13661367## Next steps13681369<CardGroup cols={2}>1370 <Card title="Multimodal cookbook" icon="image" href="https://platform.claude.com/cookbook/multimodal-getting-started-with-vision">1371 Get tips and best-practice techniques for tasks such as interpreting charts and extracting content from forms.1372 </Card>13731374 <Card title="API reference" icon="code" href="https://platform.claude.com/docs/en/api/messages/create">1375 See the Messages API documentation, including example API calls involving images.1376 </Card>1377</CardGroup>1378